libwebauthn

A Linux-native implementation of FIDO2 and FIDO U2F Platform API, fully written in Rust.

This library supports multiple transports (see Transports for a list) via a pluggable interface, making it easy to add additional backends.

Credentials for Linux Project

This repository is now part of the Credentials for Linux project, and was previously known as xdg-credentials-portal.

The Credentials for Linux project aims to offer FIDO2 platform functionality (FIDO U2F, and WebAuthn) on Linux, over a D-Bus Portal interface.

Looking for the D-Bus API proposal? Check out credentialsd.

Features

• FIDO U2F
  • 🟢 Registration (U2F_REGISTER)
  • 🟢 Authentication (U2F_AUTHENTICATE)
  • 🟢 Version (U2F_VERSION)
• FIDO2
  • 🟢 Create credential
  • 🟢 Verify assertion
  • 🟢 Biometric user verification
  • 🟢 Discoverable credentials (resident keys)
• FIDO2 to FIDO U2F downgrade
  • 🟢 Basic functionality
  • 🟢 Support for excludeList and pre-flight requests
• PIN/UV Protocols
  • 🟢 PIN/UV Auth Protocol One
  • 🟢 PIN/UV Auth Protocol Two
• PIN/UV Operations
  • 🟢 GetPinToken
  • 🟢 GetPinUvAuthTokenUsingPinWithPermissions
  • 🟢 GetPinUvAuthTokenUsingUvWithPermissions
• Passkey Authentication
  • 🟢 Discoverable credentials (resident keys)
  • 🟢 Hybrid transport (caBLE v2): QR-initiated transactions
  • 🟢 Hybrid transport (caBLE v2): State-assisted transactions (remember this phone)

Runtime requirements

Validating the relying party ID against the calling origin requires the Public Suffix List. The built-in loader reads it from the standard system path. The publicsuffix package on Debian/Ubuntu or publicsuffix-list on Fedora and Arch installs it there, but these are not always present on minimal installs. Install explicitly if needed. Callers wiring their own list don't need a system package.

Transports

	FIDO U2F	WebAuthn (FIDO2)
USB (HID)	🟢 Supported (hidapi)	🟢 Supported (hidapi)
Bluetooth Low Energy	🟢 Supported (bluez)	🟢 Supported (bluez)
NFC	🟢 Supported (pcsc or libnfc)	🟢 Supported (pcsc or libnfc)
TPM 2.0 (Platform)	🟠 Planned (#4)	🟠 Planned (#4)
Hybrid (QR code scan, aka caBLE v2)	N/A	🟢 Supported

Example programs

Examples live in libwebauthn/examples/ and are grouped by purpose: ceremony/ for register and authenticate flows, features/ for per-feature demos (extensions, preflight, PRF, device selection), and management/ for CTAP2 admin operations. All examples share helpers from examples/common/.

$ cd libwebauthn
$ git submodule update --init

The basic ceremony examples (register + authenticate) cover all transports. The WebAuthn examples consume and emit JSON per the WebAuthn IDL.

Transport	FIDO U2F	WebAuthn (FIDO2)
USB (HID)	cargo run --example u2f_hid	cargo run --example webauthn_hid
Bluetooth (BLE)	cargo run --example u2f_ble	—
NFC 1	cargo run --features nfc-backend-pcsc --example u2f_nfc cargo run --features nfc-backend-libnfc --example u2f_nfc	cargo run --features nfc-backend-pcsc --example webauthn_nfc cargo run --features nfc-backend-libnfc --example webauthn_nfc
Hybrid (caBLE v2)	—	cargo run --example webauthn_cable

Additional HID-only examples cover specific FIDO2 features and authenticator management:

# WebAuthn extension and preflight demos
$ cargo run --example webauthn_extensions_hid
$ cargo run --example webauthn_preflight_hid
$ cargo run --example webauthn_prf_hid
$ cargo run --example prf_replay -- CREDENTIAL_ID FIRST_PRF_INPUT
$ cargo run --example device_selection_hid

# CTAP2 authenticator management
$ cargo run --example change_pin_hid
$ cargo run --example bio_enrollment_hid
$ cargo run --example authenticator_config_hid
$ cargo run --example cred_management_hid

Contributing

We welcome contributions!

Join the discussion on Matrix at #credentials-for-linux:matrix.org.

If you don't know where to start, check out the Issues tab.

Footnotes

1. nfc-backend-pcsc is pure userspace and recommended on most systems. nfc-backend-libnfc requires the libnfc system library. Both can be enabled together; the first FIDO device found by either backend is used. ↩