Crypto.WebAuthn

This is the main module of the library. It re-exports the most commonly needed modules and should be the only module considered stable. The following sections give an overview of how a web application can use the exported symbols to make use of the WebAuthn standard.

WebAuthn basics

For a web application the WebAuthn standard allows the creation and use of public key-based credentials for the purpose of strongly authenticating users.

The WebAuthn standard usually involves three different devices, each of which can be WebAuthn conformant:

• A Relying Party, aka a website like github.com or google.com
• A User Agent, aka usually a browser like Firefox or Chrome
• A Authenticator, aka something like a security key like a Yubikey or a fingerprint sensor

This library implements the server side of Relying Party conformance and is therefore intended to be used by a website's server.

Ceremonies

In order for a Relying Party to be conformant, it needs to implement two Relying Party Operations, aka ceremonies:

• The Registration Ceremony, where a public key credential is created and associated with the user's account. The public key credential may be attested via one of the supported attestation statement formats. Afterwards the user can be authenticated by an Authentication Ceremony.
• The Authentication Ceremony, where it is asserted that the user controls the credential private key of a previously-registered public key credential.

Both Ceremonies have the same general flow:

1. The user interacts with the website, triggering a registration or authentication ceremony via some Relying Party website script, which sends a request to the Relying Party server to request the credential creation/request options. Depending on the scenario this request may include a username and more.
2. The Relying Party creates an PublicKeyCredentialCreationOptions or PublicKeyCredentialRequestOptions object respectively, which encodes the parameters for the ceremony, and sends it back as the response. This notably includes a Cryptographic Challenge, generated by the server.
3. Using the response as an argument, the script calls the navigator.credentials.create() or navigator.credentials.get() functions of the browser respectively. This typically causes the browser to request some gesture by the user. The result of these functions is then sent to the Relying Party server with another request.
4. The Relying Party verifies the request according to § 7.1 Registering a New Credential or § 7.2 Verifying an Authentication Assertion respectively. The response indicates the result of this verification. For successful registration ceremonies, the server stores the resulting public key and some additional information in its database. For successful authentication ceremonies, the server may want to update the relevant database entry.
5. The script handles the received response accordingly, displaying errors as needed.

This library only implements the server side of these steps, since the browser script is usually very specific to the website and use case, but also fairly simple. The example server in the source of this implementation shows how a potential implementation. See also these Sample API Usage Scenarios.

WebAuthn Security considerations

Chapter 13 details the security considerations of WebAuthn. It is highly recommend to read at least the relying party section of these considerations before implementing a relying party.

Library

The two ceremonies described above are very similar in many ways. Because of this, the library has many functions and types that are parametrized by CeremonyKind, which allows improved type safety.

The library consists of the following main parts

Model Types

A set of types representing credential options (CredentialOptions) and their resulting credentials responses (Credential), used in step 2 and step 4 respectively.

module Crypto.WebAuthn.Model

WebAuthn Encoding

Includes everything needed to encode/decode WebAuthn types between serializations and Haskell types defined in Crypto.WebAuthn.Model. Most notably this includes encoding and decoding functions for messages exchanged with the webauthn-json JavaScript library: Encoding CredentialOptions to intermediate JSON-serializable types using wjEncodeCredentialOptionsRegistration and wjEncodeCredentialOptionsAuthentication, which can be used for step 2. Also decoding Credentials from intermediate JSON-deserializable types using wjDecodeCredentialRegistration and wjDecodeCredentialAuthentication, which can be used for step 4.

module Crypto.WebAuthn.Encoding

Attestation Statement Formats

In case of a registration ceremony, there is the possibility for the Relying Party to request an attestation, which if returned may allow the Relying Party to make a trust decision (rrAttestationStatement) with the authenticator model used.

This module contains the allSupportedFormats value, which contains implementations of all standard attestation statement formats supported by this library. It can be manually passed to the wjDecodeCredentialRegistration' to enable only specific formats or add support for additional ones.

module Crypto.WebAuthn.AttestationStatementFormat

Operations

Functions for verifying resulting credential responses, needed in step 4. This is the main functionality implemented by the library. This module exports these two main symbols:

• verifyRegistrationResponse: Verifies a Credential response for registration.
• verifyAuthenticationResponse: Verifies a Credential response for authentication.

module Crypto.WebAuthn.Operation

Metadata

A function for decoding a FIDO Alliance Metadata Service BLOB in order to be able to enforce a set of requirements on the authenticator used, e.g. to only allow authenticators that have been FIDO certified.

Notably this library does not define any functions for fetching the metadata, which is left to the user of the library. See the MetadataFetch module in the example server for a potential implementation.

Currently the only function exported from this module is

• metadataBlobToRegistry: Decodes and verifies a Metadata BLOB to a MetadataServiceRegistry, which can be passed to verifyRegistrationResponse

module Crypto.WebAuthn.Metadata