Crate libwebauthn 

libwebauthn is a Linux platform library implementing the FIDO2/WebAuthn and FIDO U2F specifications. It provides traits for performing WebAuthn operations (make credential and get assertion) and U2F operations (register and sign) against authenticator devices connected over USB, Bluetooth, or optionally NFC. The core abstractions are the WebAuthn and U2F traits that drive the protocol logic, and the Channel trait that abstracts communication with a physical authenticator.

While an operation runs, the library may need user verification. It surfaces this through the UvUpdate enum and related types such as PinRequiredUpdate and PinNotSetUpdate, which let an application collect input (PIN entry or a presence confirmation) and feed it back into the ongoing operation. The transport module manages device discovery and communication, and the pin module handles the cryptographic side of PIN and user verification.

Getting started

A typical flow is to enumerate devices on your transport of choice, open a Channel to each one, and run a ceremony on that channel. The ceremony traits are blanket-implemented for every channel: WebAuthn for make-credential and get-assertion, and the management traits (CredentialManagement, AuthenticatorConfig, BioEnrollment) for the administrative ceremonies. The make-credential and get-assertion requests are built from their WebAuthn IDL (the JSON the browser API speaks) with MakeCredentialRequest::prepare and GetAssertionRequest::prepare, which validate the caller origin against the relying party ID.

use libwebauthn::ops::webauthn::{
    MakeCredentialRequest, OriginValidation, RelatedOrigins, RequestOrigin, RequestSettings,
    SystemPublicSuffixList,
};
use libwebauthn::transport::hid::list_devices;
use libwebauthn::transport::{ChannelSettings, Device};
use libwebauthn::webauthn::WebAuthn;

// 1. Enumerate authenticators on your transport of choice (HID shown here).
let devices = list_devices().await?;

for mut device in devices {
    // 2. Open a channel to the device.
    let mut channel = device.channel(ChannelSettings::default()).await?;

    // 3. Build a request from its WebAuthn IDL JSON.
    let origin: RequestOrigin = "https://example.org".try_into().expect("invalid origin");
    let psl = SystemPublicSuffixList::auto().expect("public suffix list unavailable");
    let settings = RequestSettings {
        origin: OriginValidation::Validate {
            public_suffix_list: &psl,
            related_origins: RelatedOrigins::Disabled,
        },
    };
    let request_json = r#"{ "rp": { "id": "example.org", "name": "Example" } }"#; // abbreviated
    let request =
        MakeCredentialRequest::prepare(&origin, request_json, &settings).await?;

    // 4. Run the ceremony on the channel.
    let _response = channel.webauthn_make_credential(&request).await?;
}

Modules

fido

Protocol abstractions shared between FIDO2 (CTAP2) and FIDO U2F (CTAP1). This module models the common protocol surface of the two standards, including protocol negotiation via FidoProtocol, revision tracking via FidoRevision, and the AuthenticatorData structure returned by a device during authentication and attestation ceremonies.

management

Administration interfaces for CTAP2 authenticators. This module exposes traits for managing device configuration, biometric enrollment, and stored credentials over any Channel transport. These operations require user verification through a PIN or biometric factor, and the protocol handles token acquisition and retry internally.

ops

Request and response types for WebAuthn registration and authentication ceremonies, alongside the legacy FIDO U2F operation types. The main types are MakeCredentialRequest and GetAssertionRequest, which describe the parameters for creating and asserting a credential, and the matching MakeCredentialResponse and GetAssertionResponse that carry the outcome. The request types also cover WebAuthn extensions such as PRF, HMAC secret, credProtect, and large blob storage.

pin

PIN and user-verification interaction for CTAP2 authenticators. This module implements the PIN/UV authentication protocols (PinUvAuthProtocolOne and PinUvAuthProtocolTwo), which perform ECDH key agreement and AES-CBC encryption with HMAC authentication. These are the primitives used to derive a shared secret, encrypt a PIN, and produce the authentication parameters sent during registration and assertion.

proto

The wire protocol layer for FIDO2/CTAP2 and FIDO U2F/CTAP1 authenticators. This module defines how device commands and responses are encoded and decoded: the CBOR request and response structures for CTAP2, the APDU frames for CTAP1, COSE keys, attestation statements, and the protocol status codes in CtapError. The Ctap1 and Ctap2 handlers drive these exchanges at the wire level.

transport

Transport layer that carries CTAP messages to FIDO2/WebAuthn authenticators. It abstracts over several physical media: HID (USB), BLE (Bluetooth Low Energy), caBLE (the cable/hybrid mode), and NFC (available when the nfc-backend-pcsc or nfc-backend-libnfc feature is enabled). The two core abstractions are Channel, an open session with an authenticator that sends and receives CTAP messages, and Device, a discovered authenticator from which a Channel can be opened.

u2f

High-level FIDO U2F (CTAP1) client API for registering and authenticating against an authenticator device. The U2F trait is blanket-implemented for any Channel and offers three async operations: protocol negotiation, registration, and signing.

webauthn

High-level FIDO2 (CTAP2) client API for WebAuthn ceremonies. The WebAuthn trait is blanket-implemented for any Channel. Its webauthn_make_credential and webauthn_get_assertion methods run the full CTAP2 make-credential and get-assertion ceremonies, including the user verification flow, PIN and biometric token handling, credential filtering via preflight, and extension support. When a device does not support FIDO2, the ceremony falls back to U2F (CTAP1).

Structs

PinNotSetUpdate

PinRequiredUpdate

Enums

Transport

UvUpdate

Functions

available_transports