Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package webauthn
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.
val create : string -> (t, string) Stdlib.resultcreate 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 -> stringrpid 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.
The type os json decoding errors: context, message, and data.
type decoding_error = [ | json_decoding_error| `Base64_decoding of string * string * string| `CBOR_decoding of string * string * string| `Unexpected_CBOR of string * string * CBOR.Simple.t| `Binary_decoding of string * string * Cstruct.t| `Attestation_object_decoding of string * string * string
]The variant of decoding errors with the various encoding formats.
type error = [ | decoding_error| `Unsupported_key_type of int| `Unsupported_algorithm of int| `Unsupported_elliptic_curve of int| `Unsupported_attestation_format of string| `Invalid_public_key of string| `Client_data_type_mismatch of string| `Origin_mismatch of string * string| `Rpid_hash_mismatch of string * string| `Missing_credential_data| `Signature_verification of string
]The variant of errors.
val pp_error : Stdlib.Format.formatter -> [< error ] -> unitpp_error ppf e pretty-prints the error e on ppf.
val generate_challenge : ?size:int -> unit -> challenge * stringgenerate_challenge ~size () generates a new challenge, and returns a pair of the challenge and its Base64 URI safe encoding.
val challenge_to_string : challenge -> stringchallenge_to_string c is a string representing this challenge.
val challenge_of_string : string -> challenge optionchallenge_of_string s decodes s as a challenge.
challenge_equal a b is true if a and b are the same challenge.
type credential_data = {aaguid : string;credential_id : credential_id;public_key : Mirage_crypto_ec.P256.Dsa.pub;
}The type for credential data.
type registration = {user_present : bool;user_verified : bool;sign_count : Stdlib.Int32.t;attested_credential_data : credential_data;authenticator_extensions : (string * CBOR.Simple.t) list option;client_extensions : (string * Yojson.Safe.t) list option;certificate : X509.Certificate.t option;
}The type for a registration.
val register_response_of_string :
string ->
(register_response, json_decoding_error) Stdlib.resultregister_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.resultregister 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 = {user_present : bool;user_verified : bool;sign_count : Stdlib.Int32.t;authenticator_extensions : (string * CBOR.Simple.t) list option;client_extensions : (string * Yojson.Safe.t) list option;
}The type for an authentication.
val authenticate_response_of_string :
string ->
(authenticate_response, json_decoding_error) Stdlib.resultauthentication_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.
val authenticate :
t ->
Mirage_crypto_ec.P256.Dsa.pub ->
authenticate_response ->
(challenge * authentication, error) Stdlib.resultauthenticate 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.
The type of FIDO U2F transports.
val pp_transport : Stdlib.Format.formatter -> transport -> unitpp_transport ppf tranport pretty-prints the transport on ppf.
val transports_of_cert :
X509.Certificate.t ->
(transport list, [ `Msg of string ]) Stdlib.resulttransports_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.