Skip to content

README.md

Latest commit

 

History

History
115 lines (89 loc) · 6.43 KB

README.md

File metadata and controls

115 lines (89 loc) · 6.43 KB

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. ↩