exception Error of string
Module 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.
type tThe type of a webauthn state, containing the origin.
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.
type json_decoding_error = [ | `Json_decoding of string * string * string |
]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.
type challengeThe abstract type of challenges.
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.
- raises Invalid_argument
if size is smaller than 16.
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.
val challenge_equal : challenge -> challenge -> boolchallenge_equal a b is true if a and b are the same challenge.
type credential_id = stringThe type of credential identifiers.
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.
type register_responseThe type for a register_response.
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.
type authenticate_responseThe type for an authentication response.
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.
type transport = [ | `Bluetooth_classic |
| `Bluetooth_low_energy |
| `Usb |
| `Nfc |
| `Usb_internal |
]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.
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.
The type of a webauthn state, containing the origin.
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
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 = [ | `Json_decoding of string * string * string |
]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 |
]val pp_error : Stdlib.Format.formatter -> [< error ] -> unitpp_error ppf e pretty-prints the error e on ppf.
The abstract type of challenges.
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_id = stringThe type of credential identifiers.
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.
The type for a register_response.
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.
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 = {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.
type authenticate_responseThe type for an authentication response.
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 = [ | `Bluetooth_classic |
| `Bluetooth_low_energy |
| `Usb |
| `Nfc |
| `Usb_internal |
]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.
webauthn index
Library webauthn
The entry point of this library is the module: Webauthn.
Library webauthn.cbor
The entry point of this library is the module: CBOR.
Library webauthn
The entry point of this library is the module: Webauthn.