livery_auth_webauthn (livery v0.13.0)

View Source

Passkey (WebAuthn Level 3) ceremonies, without I/O.

Two ceremonies, each in two steps: the server sends options with a fresh challenge, the browser asks the authenticator, the server verifies the answer.

Options are JSON-ready maps for the browser's PublicKeyCredential.parseCreationOptionsFromJSON and parseRequestOptionsFromJSON; responses are what credential.toJSON() gives, decoded. Both use unpadded base64url for binary fields.

The checks follow sections 7.1 and 7.2: the client data type, the challenge, the origin (one of origins), cross-origin calls (refused unless allow_cross_origin => true, and then the framing page, topOrigin, must be one of top_origins), the RP ID hash, the user-present flag, the user-verified flag when user_verification => required, the backup flags, the user handle on sign-in (required, unless user_identified => true says you picked the user before the ceremony, as for a second factor), the algorithm, the attestation (livery_auth_webauthn_attest), the signature, and the signature counter.

Each challenge must be used once. livery_auth_passkey does that for you; when you call these functions yourself, keep the challenge on the server and drop it as soon as a response arrives.

Summary

Types

credential()

Functions

creation_options/2

Registration options for User (id, a stable opaque handle of at most 64 bytes, name, display_name). Returns the raw challenge, to keep for the verify step, and the options. Opts: rp_id and rp_name (required), exclude (credential ids the user already has), user_verification and resident_key (required, preferred default, discouraged), attestation (none default or direct), timeout (ms), algorithms (COSE ids).

request_options(Opts)

Sign-in options. With no allow (credential ids), any passkey for the RP can answer (discoverable credentials, no username). Opts: rp_id (required), allow, user_verification, timeout.

verify_authentication/3

Verify a sign-in response with the stored Credential (id, public_key, sign_count, backup_eligible, and user_handle when known) against Expected (challenge, rp_id, origins, optionally user_verification, allow_cross_origin, top_origins, user_identified). Returns what to update: sign_count, backup_state, user_verified.

verify_registration/2

Verify a registration response against Expected: challenge (raw), rp_id, origins, and optionally user_verification, algorithms, allow_cross_origin, top_origins, attestation_roots, allow_unattested.

Types

credential()

-type credential() ::
          #{id := binary(),
            public_key := binary(),
            sign_count := non_neg_integer(),
            backup_eligible := boolean(),
            backup_state := boolean(),
            user_verified := boolean(),
            aaguid := binary(),
            transports := [binary()],
            attestation := livery_auth_webauthn_attest:result()}.

Functions

creation_options/2

-spec creation_options(map(), map()) -> {binary(), map()}.

Registration options for User (id, a stable opaque handle of at most 64 bytes, name, display_name). Returns the raw challenge, to keep for the verify step, and the options. Opts: rp_id and rp_name (required), exclude (credential ids the user already has), user_verification and resident_key (required, preferred default, discouraged), attestation (none default or direct), timeout (ms), algorithms (COSE ids).

request_options(Opts)

-spec request_options(map()) -> {binary(), map()}.

Sign-in options. With no allow (credential ids), any passkey for the RP can answer (discoverable credentials, no username). Opts: rp_id (required), allow, user_verification, timeout.

verify_authentication/3

-spec verify_authentication(map(), map(), map()) -> {ok, map()} | {error, term()}.

Verify a sign-in response with the stored Credential (id, public_key, sign_count, backup_eligible, and user_handle when known) against Expected (challenge, rp_id, origins, optionally user_verification, allow_cross_origin, top_origins, user_identified). Returns what to update: sign_count, backup_state, user_verified.

verify_registration/2

-spec verify_registration(map(), map()) -> {ok, credential()} | {error, term()}.

Verify a registration response against Expected: challenge (raw), rp_id, origins, and optionally user_verification, algorithms, allow_cross_origin, top_origins, attestation_roots, allow_unattested.