Skip to main content

Pairing Guide

This guide walks you through pairing your Linux desktop with your Android device to enable WebAuthn authentication via NFC.

Pairing Overview​

Pairing establishes a secure, encrypted channel between your Linux client and Android device using:

  • SPAKE2 protocol: Password-authenticated key exchange
  • 6-digit PIN: Shared secret for authentication
  • QR code: Convenient way to transfer pairing ID and PIN

After pairing, both devices share a 32-byte secret that's used to encrypt all future communications.

Prerequisites​

Before pairing:

  1. Linux client is running:

    # If installed as a service
    systemctl --user start fido-bridge

    # Or run directly
    sudo ./target/release/fido-bridge daemon

  2. Android app is installed and opened

  3. Both devices can reach the relay server:

    • If using embedded server: Android device must be on same network as Linux machine
    • If using remote server: Both devices need internet connection

  4. QR code scanner ready: Android device camera must have permission

Step-by-Step Pairing​

Step 1: Initiate Pairing on Linux​

  1. Start the client (if not already running):

    # If installed as a service
    systemctl --user start fido-bridge

    # Or run directly
    sudo ./target/release/fido-bridge daemon

  2. Trigger pairing mode:

    • The client automatically starts in pairing mode if no devices are paired
    • OR press P in the interactive mode to start a new pairing session

  3. Observe the terminal output:

    [INFO] Starting pairing session...
    [INFO] Pairing ID: pair-123e4567-e89b-12d3-a456-426614174000
    [INFO] PIN: 123456

    ┌─────────────────────────────────────┐
    │ █▀▀▀▀▀█ ▀▀█▄ ▀█▀▄▀▄ █ █▀▀▀▀▀█ │
    │ █ ███ █ ▀  █▀▀▀█ ▀▄█▀ █ ███ █ │
    │ █ ▀▀▀ █ █▄▄ █▄▀█▄ ▄▀ █ ▀▀▀ █ │
    │ ▀▀▀▀▀▀▀ █ ▀ ▀ █▄▀ ▀ █ ▀▀▀▀▀▀▀ │
    │ ...QR code continues...           │
    └─────────────────────────────────────┘

    [INFO] Scan this QR code with your Android device
    [INFO] Pairing session expires in 5 minutes

  4. Note the PIN: The 6-digit PIN displayed (e.g., 123456)

Step 2: Scan QR Code on Android​

  1. Open the FIDO Bridge app on your Android device

  2. Tap the "+" button or "Pair New Device" button

  3. Grant camera permission if prompted

  4. Point camera at the QR code displayed on your Linux terminal

    • The app will automatically scan and parse the QR code
    • QR code contains: {pairing_id: "pair-...", pin: "123456"}

  5. Verify the PIN matches:

    • The app will display the PIN from the QR code
    • IMPORTANT: Verify it matches the PIN shown on your Linux terminal
    • This prevents man-in-the-middle attacks

  6. Tap "Confirm and Pair"

Step 3: Wait for Pairing Completion​

  1. Android app shows "Pairing in progress..."

    • The app sends its SPAKE2 response to the server
    • Both devices derive the shared secret

  2. Linux client shows:

    [INFO] Received pairing response from android-device-1
    [INFO] Pairing completed successfully!
    [INFO] Device name: Pixel 7 (Android 14)
    [INFO] Paired devices: 1

  3. Android app shows:

    ✓ Pairing successful!

    Paired with: ThinkPad X1 (Linux)
    Device ID: linux-desktop-1

  4. You're ready to authenticate! Both devices are now paired and can communicate securely.

Pairing Multiple Devices​

You can pair multiple Android devices to one Linux client, or multiple Linux clients to one Android device.

Pairing a Second Android Device​

  1. On Linux: Press P to start a new pairing session (generates new PIN and QR code)
  2. On second Android device: Follow the same pairing steps above
  3. Result: Linux client now has 2 paired Android devices

Note: During WebAuthn authentication, the first device to respond wins. Both devices will receive the request.

Pairing a Second Linux Client​

  1. On second Linux machine: Start the client and initiate pairing
  2. On Android: Pair with the new Linux machine (scan its QR code)
  3. Result: Android device now has 2 paired Linux clients

Note: Each pairing is independent with its own shared secret.

Managing Paired Devices​

View Paired Devices​

On Linux:

# List paired devices
cat ~/.config/fido-bridge/devices.json | jq

Output:

[
  {
    "device_id": "android-phone-1",
    "device_name": "Pixel 7",
    "device_type": "android",
    "device_token": "token-abc123...",
    "shared_secret": "...",
    "paired_at": 1704067200
  }
]

On Android:

  • Open FIDO Bridge app
  • Paired devices are listed on the home screen
  • Tap a device to view details or unpair

Unpair a Device​

On Linux:

  1. Stop the client (if running)
  2. Edit the devices file: 
    nano ~/.config/fido-bridge/devices.json
  3. Remove the device entry from the JSON array
  4. Restart the client

On Android:

  1. Open FIDO Bridge app
  2. Tap the device you want to unpair
  3. Tap "Unpair" or swipe left and tap "Delete"
  4. Confirm the action

Re-pair After Unpair​

If you unpaired by mistake or want to re-establish the pairing:

  1. Unpair on both devices (to avoid confusion)
  2. Initiate a fresh pairing following the steps above
  3. New shared secret will be generated

Pairing Security​

PIN Verification is Critical​

Always verify the PIN matches on both devices before confirming pairing.

Attack Scenario:

  • Attacker intercepts QR code scan
  • Attacker displays their own QR code with different PIN
  • If you don't verify, you'll pair with attacker's device instead

Protection:

  • PIN is displayed on both devices
  • User must manually confirm they match
  • 6-digit PIN provides 1,000,000 combinations (1 in 1M guess rate)

QR Code Security​

The QR code contains:

{
  "pairing_id": "pair-123e4567-e89b-12d3-a456-426614174000",
  "pin": "123456",
  "server_url": "http://localhost:3000"  // optional
}

Security Considerations:

  • QR code is not encrypted (it's just base64-encoded JSON)
  • QR code should only be displayed in trusted environments
  • Don't share screenshots of QR codes publicly
  • Pairing session expires after 5 minutes

Shared Secret Storage​

On Linux: Stored in ~/.config/fido-bridge/devices.json

  • Plaintext on disk (relies on OS-level encryption)
  • Recommendation: Use full-disk encryption (LUKS, dm-crypt)

On Android: Stored in app's secure storage

  • Encrypted by Android's app sandbox
  • Recommendation: Use device encryption + PIN/biometric lock

Impact of Compromise:

  • Attacker with shared secret can impersonate the device
  • Attacker can decrypt messages intended for that device
  • Attacker cannot access YubiKey credentials (they remain on hardware)

Troubleshooting Pairing​

QR Code Won't Scan​

Issue: Android app doesn't recognize QR code

Solutions:

  1. Ensure good lighting: QR code needs clear visibility
  2. Adjust terminal window size: Make QR code larger 
    # Increase terminal font size, then restart pairing
  3. Manually enter pairing details:
    • In Android app, tap "Manual entry" instead of scanning
    • Enter the pairing ID and PIN shown on Linux terminal

"Pairing Failed: Invalid PIN"​

Issue: SPAKE2 key derivation failed (PINs don't match)

Cause:

  • Typo in manual PIN entry
  • QR code parsing error
  • PIN mismatch attack attempt

Solution:

  1. Verify PIN exactly matches on both devices
  2. Restart pairing on both sides (generates new PIN)
  3. Try manual entry if QR scanning is unreliable

"Pairing Timeout"​

Issue: Pairing session expired (5-minute limit)

Cause:

  • User took too long to complete pairing
  • Network connectivity issues prevented message delivery

Solution:

  1. Restart pairing on Linux (press P again)
  2. Complete pairing within 5 minutes
  3. Check network connectivity between devices and server

"Connection Refused"​

Issue: Android app can't reach relay server

Cause:

  • Server is not running
  • Wrong server URL in app configuration
  • Firewall blocking port 3000

Solutions:

  1. Verify server is running:

    curl http://localhost:3000/health
    # Should return: {"status": "ok"}

  2. Check server URL in Android app:

    • Go to app settings
    • Verify server URL matches actual server address
    • For embedded server: Use Linux machine's local IP (e.g., http://192.168.1.100:3000)

  3. Check firewall:

    # Allow port 3000 on Linux
    sudo ufw allow 3000/tcp  # Ubuntu/Debian
    sudo firewall-cmd --add-port=3000/tcp --permanent  # Fedora

"Device Already Paired"​

Issue: Attempting to re-pair without unpairing first

Solution:

  1. Unpair existing pairing on both devices
  2. Initiate fresh pairing with new QR code/PIN

Pairing Best Practices​

Security Best Practices​

  1. Verify PIN on both devices - Don't skip this step!
  2. Complete pairing in private - Don't display QR codes in public
  3. Use strong device authentication - Enable PIN/biometric lock on Android
  4. Enable full-disk encryption - Protect shared secret at rest on Linux
  5. Unpair unused devices - Remove old pairings you no longer need

Usability Best Practices​

  1. Pair in a well-lit area - Improves QR code scanning reliability
  2. Keep devices close to router - Ensures good network connectivity during pairing
  3. Name devices descriptively - Makes it easier to identify pairings later
  4. Pair before you need it - Don't wait until you urgently need to authenticate

Advanced: Manual Pairing​

If QR code scanning isn't available, you can manually pair:

On Linux​

  1. Start pairing and note the pairing ID and PIN: 
    Pairing ID: pair-123e4567-e89b-12d3-a456-426614174000
    PIN: 123456

On Android​

  1. In the app, tap "Manual Pairing"
  2. Enter the pairing ID: pair-123e4567-e89b-12d3-a456-426614174000
  3. Enter the PIN: 123456
  4. Enter server URL (if not using default): http://192.168.1.100:3000
  5. Tap "Pair"

The rest of the pairing process is identical to QR code pairing.

Next Steps​