package webauthn

  1. Overview
  2. Docs
package webauthn
Legend:
Library
Module
Module type
Parameter
Class
Class type

WebAuthn - authenticating users to services using public key cryptography

WebAuthn is a web standard published by the W3C. Its goal is to standardize an interfacefor authenticating users to web-based applications and services using public key cryptography. Modern web browsers support WebAuthn functionality.

WebAuthn provides two funcitons: register and authenticate. Usually the public and private keypair is stored on an external token (Yuikey etc.) or part of the platform (TPM). After the public key is registered, it can be used to authenticate to the same service.

This module implements at the moment only "fido-u2f" and "none" attestations with P256 keys.

A common use of this module is that on startup a t is created (using create). A public key can then be registered (register) with a server generated challenge. When this is successfull, the client can be authenticated authenticate.

This module does not preserve a database of registered public keys, their credential ID, usernames and pending challenges - instead this data must be stored by a client of this API in a database or other persistent storage.

WebAuthn specification at W3C.

type t

The type of a webauthn state, containing the origin.

val create : string -> (t, string) Stdlib.result

create origin is a webauthn state, or an error if the origin does not meet the specification (schema must be https, the host must be a valid hostname. An optional port is supported: https://example.com:4444

val rpid : t -> string

rpid t is the relying party ID. Specifically, it is the effective domain of the origin. Using registrable domain suffix as the relying party ID is currently unsupported.

type json_decoding_error = [
  1. | `Json_decoding of string * string * string
]

The type os json decoding errors: context, message, and data.

type decoding_error = [
  1. | json_decoding_error
  2. | `Base64_decoding of string * string * string
  3. | `CBOR_decoding of string * string * string
  4. | `Unexpected_CBOR of string * string * CBOR.Simple.t
  5. | `Binary_decoding of string * string * Cstruct.t
  6. | `Attestation_object_decoding of string * string * string
]

The variant of decoding errors with the various encoding formats.

type error = [
  1. | decoding_error
  2. | `Unsupported_key_type of int
  3. | `Unsupported_algorithm of int
  4. | `Unsupported_elliptic_curve of int
  5. | `Unsupported_attestation_format of string
  6. | `Invalid_public_key of string
  7. | `Client_data_type_mismatch of string
  8. | `Origin_mismatch of string * string
  9. | `Rpid_hash_mismatch of string * string
  10. | `Missing_credential_data
  11. | `Signature_verification of string
]

The variant of errors.

val pp_error : Stdlib.Format.formatter -> [< error ] -> unit

pp_error ppf e pretty-prints the error e on ppf.

type challenge

The abstract type of challenges.

val generate_challenge : ?size:int -> unit -> challenge * string

generate_challenge ~size () generates a new challenge, and returns a pair of the challenge and its Base64 URI safe encoding.

  • raises Invalid_argument

    if size is smaller than 16.

val challenge_to_string : challenge -> string

challenge_to_string c is a string representing this challenge.

val challenge_of_string : string -> challenge option

challenge_of_string s decodes s as a challenge.

val challenge_equal : challenge -> challenge -> bool

challenge_equal a b is true if a and b are the same challenge.

type credential_id = string

The type of credential identifiers.

type credential_data = {
  1. aaguid : string;
  2. credential_id : credential_id;
  3. public_key : Mirage_crypto_ec.P256.Dsa.pub;
}

The type for credential data.

type registration = {
  1. user_present : bool;
  2. user_verified : bool;
  3. sign_count : Stdlib.Int32.t;
  4. attested_credential_data : credential_data;
  5. authenticator_extensions : (string * CBOR.Simple.t) list option;
  6. client_extensions : (string * Yojson.Safe.t) list option;
  7. certificate : X509.Certificate.t option;
}

The type for a registration.

type register_response

The type for a register_response.

val register_response_of_string : string -> (register_response, json_decoding_error) Stdlib.result

register_response_of_string s decodes the json encoded response (consisting of a JSON dictionary with an attestationObject and clientDataJSON - both Base64 URI safe encoded). The result is a register_response or a decoding error.

val register : t -> register_response -> (challenge * registration, error) Stdlib.result

register t response registers the response, and returns the used challenge and a registration. The challenge needs to be verified to be valid by the caller. If a direct attestation is used, the certificate is returned -- and the signature is validated to establish the trust chain between certificate and public key. The certificate should be validated by the caller.

type authentication = {
  1. user_present : bool;
  2. user_verified : bool;
  3. sign_count : Stdlib.Int32.t;
  4. authenticator_extensions : (string * CBOR.Simple.t) list option;
  5. client_extensions : (string * Yojson.Safe.t) list option;
}

The type for an authentication.

type authenticate_response

The type for an authentication response.

val authenticate_response_of_string : string -> (authenticate_response, json_decoding_error) Stdlib.result

authentication_response_of_string s decodes the response (a JSON dictionary of Base64 URI-safe encoded values: authenticatorData, clientDataJSON, signature, userHandle). If decoding fails, an error is reported.

authenticate t public_key response authenticates response, by checking the signature with the public_key. If it is valid, the used challenge is returned together with the authentication. The challenge needs to be validated by the caller, and then caller is responsible for looking up the public key corresponding to the credential id returned by the client web browser.

type transport = [
  1. | `Bluetooth_classic
  2. | `Bluetooth_low_energy
  3. | `Usb
  4. | `Nfc
  5. | `Usb_internal
]

The type of FIDO U2F transports.

val pp_transport : Stdlib.Format.formatter -> transport -> unit

pp_transport ppf tranport pretty-prints the transport on ppf.

val transports_of_cert : X509.Certificate.t -> (transport list, [ `Msg of string ]) Stdlib.result

transports_of_cert certficate attempts to extract the FIDO U2F authenticator transports extension (OID 1.3.6.1.4.1.45724.2.1.1) from the certificate.