Stability | provisional |
---|---|
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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
orgoogle.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:
- 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.
- 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.
- Using the response as an argument, the script calls the
navigator.credentials.create()
ornavigator.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. - 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.
- 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
Synopsis
- module Crypto.WebAuthn.Model
- module Crypto.WebAuthn.Encoding
- module Crypto.WebAuthn.AttestationStatementFormat
- module Crypto.WebAuthn.Operation
- module Crypto.WebAuthn.Metadata
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 Credential
s 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.
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 aCredential
response for registration.verifyAuthenticationResponse
: Verifies aCredential
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 aMetadataServiceRegistry
, which can be passed toverifyRegistrationResponse
module Crypto.WebAuthn.Metadata