Skip to main content

Crate webauthn

Crate webauthn 

Source
Expand description

§webauthn — WebAuthn relying-party library

Server-side (relying party) verification for the two core WebAuthn ceremonies:

  • Registration (navigator.credentials.create) — the authenticator generates a public/private keypair. The relying party verifies the attestation and stores the public key and credential ID.
  • Authentication (navigator.credentials.get) — the authenticator signs a challenge with the stored private key. The relying party verifies the signature and sign count.

§Quick start

use webauthn::{
    AuthenticatorAssertionResponse, AuthenticatorAttestationResponse,
    Challenge, RelyingParty,
};

// Configure the relying party once at startup.
let rp = RelyingParty::new("example.com", "https://example.com", "My Service");

// ── Registration ──────────────────────────────────────────────────────────

// Issue a challenge, send it to the browser, receive the attestation response.
let reg_challenge = Challenge::new().expect("RNG failure");

// Verify the registration and persist the returned credential.
let reg_result = rp
    .verify_registration(&reg_challenge, &reg_response, b"user-id-42")
    .expect("registration failed");
let stored_credential = reg_result.credential;

// ── Authentication ────────────────────────────────────────────────────────

// Issue a new challenge, send it to the browser, receive the assertion response.
let auth_challenge = Challenge::new().expect("RNG failure");

// Verify the assertion and update the stored sign count.
let auth_result = rp
    .verify_authentication(&stored_credential, &auth_challenge, &auth_response)
    .expect("authentication failed");
// Persist auth_result.new_sign_count to your database.

§Supported algorithms

AlgorithmCOSE IDDescription
ES256-7ECDSA P-256 with SHA-256 — recommended, most common
ES384-35ECDSA P-384 with SHA-384
EdDSA-8Ed25519 — newer FIDO2 authenticators
RS256-257RSA PKCS#1 v1.5 with SHA-256 — legacy YubiKey 4, Windows Hello

See the COSE algorithm registry for the full list of identifiers.

§Security properties

  • No unsafe code — #![forbid(unsafe_code)] is enforced at compile time. All cryptographic operations are delegated to ring, which descends from BoringSSL and manages its own unsafe code behind a safe API boundary.
  • No panics — #![deny(clippy::unwrap_used)] prevents .unwrap() in library code. Every error path returns a typed WebAuthnError variant.
  • No custom crypto — signature verification, hashing, and random number generation are all inside ring’s audited boundary.
  • Caller responsibilities — credential uniqueness checks and FIDO Metadata Service integration are out of scope. Challenge single-use enforcement is opt-in via RelyingParty::enforce_single_use_challenges.

Learning project — this library is a portfolio demonstration of a correct WebAuthn implementation. For production use, consider webauthn-rs, which includes FIDO MDS integration and a broader attestation format set.

§Features

FeatureDefaultDescription
serdeoffDerives serde::Serialize and serde::Deserialize on Credential, PublicKey, Challenge, RegistrationResult, AuthenticationResult, AttestationType, and WebAuthnError. Vec<u8> fields are encoded as compact byte sequences via serde_bytes rather than arrays of integers. Enable with features = ["serde"] in Cargo.toml.

Note: serde and serde_json are unconditional dependencies used internally for clientDataJSON parsing. The serde feature only controls whether the public-facing types implement Serialize/Deserialize.

§Spec references

Re-exports§

pub use algorithm::COSE_EDDSA;
pub use algorithm::COSE_ES256;
pub use algorithm::COSE_ES384;
pub use algorithm::COSE_RS256;
pub use challenge::is_expired;
pub use challenge::is_expired_with_max_age;
pub use challenge::CHALLENGE_MAX_AGE_SECS;
pub use credential::AttestationType;
pub use credential::AuthenticationResult;
pub use credential::AuthenticatorAttestationResponse;
pub use credential::Challenge;
pub use credential::Credential;
pub use credential::PublicKey;
pub use credential::RegistrationResult;
pub use crypto::generate_challenge;
pub use crypto::random_bytes;
pub use crypto::rsa_components_to_der;
pub use crypto::sha256;
pub use error::Result;
pub use error::WebAuthnError;

Modules§

algorithm
COSE algorithm and key-type constants.
attestation
Attestation statement verification.
authenticator_data
Authenticator data parsing.
challenge
Challenge lifecycle helpers.
client_data
Parsing and validation of clientDataJSON.
credential
Core domain types for stored credentials, challenges, and ceremony results.
crypto
Low-level cryptographic primitives used throughout WebAuthn ceremony verification.
der
Minimal DER (Distinguished Encoding Rules) builder for RSA public keys.
error
Error types for the webauthn library.

Structs§

AuthenticatorAssertionResponse
The browser’s response after a navigator.credentials.get() call.
RelyingParty
The relying party — your server application.