cryptnox-fido2-bridge

Linux HID to PC/SC bridge for FIDO2 smart cards

cryptnox-fido2-bridge is a Linux-only Python bridge that creates a virtual USB-HID device, enabling browsers to use FIDO2 smart cards for WebAuthn/FIDO2 authentication. It translates CTAP2 commands from the browser into PC/SC APDUs for the card.

---

Supported hardware

Smart cards

Works with Cryptnox smart cards and any other FIDO2-capable smart card over PC/SC.

Smart card	Interface
Crypto Hardware Wallet – Dual Card Set	NFC + Contact
Cryptnox FIDO2 Security Key & MIFARE DESFire	NFC + Contact

Smart card readers

Works with Cryptnox readers and any other standard PC/SC smart card reader:

Reader	Type	Interface
Cryptnox® Smartcard Reader	Contact (ID-1 + SIM)	USB-A
Compact USB Mini Smartcard Reader	Contact (ID-1)	USB-A
Cryptnox NFC Contactless Reader	Contactless (NFC/ISO 14443)	USB-C

---

How it works

┌──────────────┐     USB-HID      ┌────────────────────────┐     PC/SC     ┌─────────────┐
│   Browser    │ ◄──────────────► │  Cryptnox FIDO2 Bridge │ ◄────────────►│  Smart Card │
│   (Chrome)   │                  │    (Virtual Device)    │               │             │
└──────────────┘                  └────────────────────────┘               └─────────────┘

1. The bridge creates a virtual USB-HID device using Linux's UHID facility
2. When a browser sends a FIDO2/CTAP2 command via USB-HID
3. The bridge translates it to PC/SC APDUs
4. Commands are sent to your smart card via the card reader
5. Responses are translated back and sent to the browser

This enables using PC/SC smartcards in browsers that only support USB-HID authenticators.

---

Installation

Important

Requires Linux (Ubuntu 22.04+, Debian 12+, or similar) and Python 3.12 or newer. Check your version with python3 --version.

Prerequisites

Install system dependencies (required for all installation methods below):

sudo apt update
sudo apt install -y pcscd pcsc-tools libpcsclite-dev swig \
    python3-venv python3-dev build-essential libffi-dev
sudo systemctl enable --now pcscd

From source

git clone https://github.com/Cryptnox/cryptnox-fido2-bridge.git
cd cryptnox-fido2-bridge
pip install poetry
poetry install

# Run
sudo -E env PATH=$PATH poetry run cryptnox-fido2-bridge

Using pipx

sudo apt install -y pipx
pipx install git+https://github.com/Cryptnox/cryptnox-fido2-bridge.git

# Run (use full path or add ~/.local/bin to PATH)
sudo -E ~/.local/bin/cryptnox-fido2-bridge

Using virtual environment

python3 -m venv venv
source venv/bin/activate
pip install git+https://github.com/Cryptnox/cryptnox-fido2-bridge.git

# Run
sudo -E cryptnox-fido2-bridge

---

Quick usage examples

Tip

Supported browsers: Chrome (recommended), Chromium. Firefox and Brave have limited support due to stricter security policies.

1. Basic usage

1. Connect your smartcard reader to your computer
2. Insert your card (or place on NFC reader)
3. Run the bridge:

   sudo -E cryptnox-fido2-bridge

4. Open Chrome and navigate to a WebAuthn site:
   • https://webauthn.io/ (test site)
   • https://demo.yubico.com/webauthn-technical/registration
5. Register or Authenticate - the bridge will communicate with your card!

2. Command line options

# Show help
cryptnox-fido2-bridge --help

# Enable debug logging
sudo -E cryptnox-fido2-bridge --debug

# Quiet mode (no banner)
sudo -E cryptnox-fido2-bridge --quiet

# Show version
cryptnox-fido2-bridge --version

---

Troubleshooting

Command not found with pipx and sudo

If you installed with pipx and get a "command not found" error when running with sudo, the system cannot find the binary in the root PATH:

# Use the full path
sudo -E ~/.local/bin/cryptnox-fido2-bridge

# Or add ~/.local/bin to your PATH (add to ~/.bashrc)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Command not found with Poetry and sudo

sudo resets PATH, so poetry is often missing. Use the full path or preserve PATH:

sudo -E ~/.local/bin/poetry run cryptnox-fido2-bridge

# Or
sudo -E env "PATH=$PATH" poetry run cryptnox-fido2-bridge

Permission denied on /dev/uhid

If you get a permission error when running the bridge, the current user does not have access to the UHID device. You can fix this temporarily or permanently:

# Fix permissions
sudo chmod 666 /dev/uhid

# Or create udev rule (permanent fix)
sudo tee /etc/udev/rules.d/70-cryptnox-fido2.rules << 'EOF'
KERNEL=="uhid", MODE="0666"
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger

Card not detected

If the bridge cannot find your card, pcscd may not be running or the reader is not properly recognized:

# Check if pcscd is running
sudo systemctl status pcscd

# Restart pcscd
sudo systemctl restart pcscd

# Test card detection
pcsc_scan

CryptnoxCR reader and CCID (PC/SC)

The CryptnoxCR USB contact reader (0x05F8:0x0018) is included in upstream CCID from version 1.7.1 onward. That driver is what pcscd uses (via the libccid / ifd-ccid bundle on Debian and Ubuntu).

Check your installed version:

dpkg -l libccid

If it is older than 1.7.1, build and install from source as Ubuntu does not yet package a newer version.

Option A — Simple install (files only)

Installs the driver files but dpkg will still report the old version.

sudo apt install -y meson libusb-1.0-0-dev flex libpcsclite-dev
wget https://ccid.apdu.fr/files/ccid-1.8.0.tar.xz
tar -xf ccid-1.8.0.tar.xz
cd ccid-1.8.0
meson setup builddir
cd builddir
meson compile
sudo meson install
sudo systemctl restart pcscd.socket pcscd
pcsc_scan -r

Option B — Install with package manager tracking (recommended)

Creates a .deb and registers it with dpkg so the version is correctly tracked and can be removed with apt remove.

sudo apt install -y meson libusb-1.0-0-dev flex libpcsclite-dev checkinstall
wget https://ccid.apdu.fr/files/ccid-1.8.0.tar.xz
tar -xf ccid-1.8.0.tar.xz
cd ccid-1.8.0
meson setup builddir
cd builddir
meson compile
sudo checkinstall --pkgname=libccid --pkgversion=1.8.0 --pkgrelease=1 --nodoc meson install
sudo systemctl restart pcscd.socket pcscd
pcsc_scan -r

---

License

cryptnox-fido2-bridge is licensed under the MIT License — see LICENSE for details.

This project is based on fido2-hid-bridge by Bryan Jacobs, also MIT-licensed.