Skip to main content

Getting Started

Welcome to FIDO Bridge! This project enables you to use your YubiKey via NFC for WebAuthn authentication on Linux, bridging the gap between desktop browsers and mobile NFC capabilities.

What is FIDO Bridge?​

FIDO Bridge is a secure, end-to-end encrypted bridge that allows Linux users to leverage their Android device's NFC capabilities to interact with FIDO2/WebAuthn security keys (like YubiKey) for browser authentication. It solves the problem of limited NFC support in Linux desktop environments.

The Problem​

Linux desktop environments typically lack native NFC support for FIDO2/WebAuthn authentication. While you can use USB-connected security keys, NFC-based authentication with keys like YubiKey requires cumbersome workarounds or isn't possible at all.

The Solution​

FIDO Bridge creates a secure channel between your Linux desktop and Android device:

  1. Your Linux browser makes a WebAuthn request
  2. The FIDO Bridge client intercepts it via a virtual UHID device
  3. The request is encrypted and sent to your paired Android device
  4. Your Android device communicates with the YubiKey via NFC
  5. The response is encrypted and returned to your Linux browser

All communication is end-to-end encrypted with double-layer encryption, ensuring even the relay server cannot read your authentication data.

Architecture Overview​

Components​

  • Rust Client (/crates/client): Runs on Linux, creates a virtual UHID FIDO device, handles CTAP2 protocol
  • Rust Server (/crates/server): Relay server that forwards encrypted messages (server-blind design)
  • Transport Library (/crates/transport): Shared crypto and protocol implementation
  • Flutter Android App (/app): Handles NFC communication with YubiKey, message polling, and pairing UI
  • Kotlin NFC Layer (/app/android): Low-level NFC APDU communication with YubiKey

Key Features​

Double-Layer End-to-End Encryption​

FIDO Bridge uses a unique two-layer encryption approach:

  1. SPAKE2 Pairing Protocol: Initial device pairing using Ed25519-based SPAKE2 with PIN authentication
  2. X25519 ECDH Ephemeral Keys: Per-session ephemeral key exchange with AES-256-GCM encryption

This ensures that even if the relay server is compromised, it cannot decrypt your authentication data.

PRF Extension Support​

Full support for the WebAuthn PRF (Pseudo-Random Function) extension, enabling advanced use cases like:

  • Credential encryption
  • Deterministic key derivation
  • Custom authentication flows

Session Caching​

Intelligent session caching (30-second timeout) reduces repeated NFC taps during multi-step authentication flows like ClientPIN operations.

Adaptive Polling​

The Android app uses adaptive polling intervals:

  • Active: 250ms when expecting responses
  • Background: Reduces to lower frequency to save battery

Transaction Management​

Every WebAuthn operation is wrapped in a transaction with:

  • Unique transaction ID
  • 240-second timeout (configurable)
  • State tracking (GetInfo → MakeCredential/GetAssertion → Completion)
  • Automatic cleanup of expired transactions

Quick Start​

Prerequisites​

  • Linux Machine: Running a modern distribution with systemd
  • Android Device: Android 7.0+ with NFC support
  • YubiKey: YubiKey 5 NFC or similar FIDO2-compatible NFC key

Installation​

The fastest way to get started is to download the latest pre-built binaries from GitHub Releases:

  1. Download the latest release from GitHub Releases:

    • fido-bridge-android-v*.apk - Android app
    • fido-bridge-linux-v* - Linux client binary
    • fido-bridge-server-linux-v* - Server binary (optional, if running standalone server)

  2. Install the Android app:

    # Transfer the APK to your Android device and install
    # Or use adb if device is connected:
    adb install fido-bridge-android-v*.apk

  3. Install the Linux client:

    # Make the binary executable
    chmod +x fido-bridge-linux-v*

    # Run the built-in installer (recommended)
    ./fido-bridge-linux-v* install

Option 2: Build from Source​

For developers or if you want to build from source:

  1. Additional requirements:

    • Rust: 1.90+
    • Flutter: 3.0+

  2. Build the Rust client:

    cd /path/to/fido-bridge
    cargo build --release --bin fido-bridge

  3. Build the Android app:

    cd /path/to/fido-bridge/app
    flutter build apk --release

  4. Install the Android app:

    flutter install

  5. Run the client:

    # Recommended: Install with built-in installer
    ./target/release/fido-bridge install

    # Or run directly (requires UHID access)
    ./target/release/fido-bridge daemon

See Building from Source for detailed build instructions.

Pairing Your Devices​

  1. Start the Linux client
  2. Open the Android app
  3. Tap "Pair New Device"
  4. Scan the QR code displayed on your Linux terminal
  5. Enter the 6-digit PIN shown on both devices
  6. Wait for pairing confirmation

For detailed pairing instructions, see the Pairing Guide.

Next Steps​

Security Note​

FIDO Bridge is designed with security as a top priority:

  • Server-blind design: The relay server never sees plaintext authentication data
  • Ephemeral keys: Session keys are rotated per-transaction
  • No credential storage: Credentials remain on your YubiKey
  • Replay protection: Timestamp-based freshness validation

For a complete security analysis, see the Security Documentation.

License​

FIDO Bridge is dual-licensed under MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE for details.