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)
  • 🟢 Related origins (WebAuthn L3 §5.11)
• 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
  • 🟢 Persistent pinUvAuthToken for read-only credential management (pcmr, CTAP 2.2+)
• Passkey Authentication
  • 🟢 Discoverable credentials (resident keys)
  • 🟢 Hybrid transport (caBLE v2): QR-initiated transactions
  • 🟢 Hybrid transport (caBLE v2): State-assisted transactions (remember this phone)
  • 🟢 Hybrid transport (CTAP 2.3): direct BLE L2CAP data channel, QR-initiated, no tunnel server

Runtime requirements

Validating the relying party ID against the calling origin requires the Public Suffix List. The built-in SystemPublicSuffixList::auto() loader reads it from the standard system path, probing the binary .dafsa format first and falling back to the text .dat format. The publicsuffix package on Debian/Ubuntu ships both. On Fedora the binary .dafsa file is shipped by publicsuffix-list-dafsa (a transitive dependency of libpsl, so usually already installed), while the text .dat file requires the optional publicsuffix-list package. On Arch only the text .dat format is packaged. Callers wiring their own list don't need a system package.

Transports

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.

[^nfc]: 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.

[^ro]: The ceremony examples run with related origins disabled (they are same-origin, so it never applies). The bundled reqwest-backed related-origins source is shown in the webauthn_related_origins_hid example below, behind the optional reqwest-related-origins-source feature. Consumers that ship their own HTTP stack can implement HttpClient or RelatedOriginsSource directly.

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

# Related origins (reqwest-backed well-known fetch)
$ cargo run --features reqwest-related-origins-source --example webauthn_related_origins_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
$ cargo run --example persistent_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.