WebAuthn.hs

{-# OPTIONS_GHC -Wno-missing-import-lists #-}

-- | Stability: provisional
--
-- 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](https://www.w3.org/TR/webauthn-2/)
-- 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](https://www.w3.org/TR/webauthn-2/#sctn-conformance):
--
-- * A [Relying Party](https://www.w3.org/TR/webauthn-2/#webauthn-relying-party),
--   aka a __website__ like @github.com@ or @google.com@
-- * A [User Agent](https://www.w3.org/TR/webauthn-2/#conforming-user-agent),
--   aka usually a __browser__ like Firefox or Chrome
-- * A [Authenticator](https://www.w3.org/TR/webauthn-2/#authenticator),
--   aka something like a __security key__ like a Yubikey or a fingerprint sensor
--
-- This library implements the server side of [Relying Party conformance](https://www.w3.org/TR/webauthn-2/#sctn-conforming-relying-parties)
-- 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](https://www.w3.org/TR/webauthn-2/#sctn-rp-operations),
-- aka [ceremonies](https://www.w3.org/TR/webauthn-2/#ceremony):
--
-- * The [Registration Ceremony](https://www.w3.org/TR/webauthn-2/#registration-ceremony),
--   where a [public key credential](https://www.w3.org/TR/webauthn-2/#public-key-credential)
--   is created and associated with the user's account. The public key credential
--   may be [attested](https://www.w3.org/TR/webauthn-2/#sctn-attestation) via
--   one of the supported
--   [attestation statement formats](https://www.w3.org/TR/webauthn-2/#attestation-statement-format).
--   Afterwards the user can be authenticated by an Authentication Ceremony.
-- * The [Authentication Ceremony](https://www.w3.org/TR/webauthn-2/#authentication-ceremony),
--   where it is [asserted](https://www.w3.org/TR/webauthn-2/#assertion) that
--   the user controls the [credential private key](https://www.w3.org/TR/webauthn-2/#credential-private-key)
--   of a previously-registered [public key credential](https://www.w3.org/TR/webauthn-2/#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.
-- #step-2#
-- 2. The Relying Party creates an [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialcreationoptions)
--   or [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialrequestoptions) object respectively,
--   which encodes the parameters for the [ceremony](https://www.w3.org/TR/webauthn-2/#ceremony),
--   and sends it back as the response. This notably includes a
--   [Cryptographic Challenge](https://www.w3.org/TR/webauthn-2/#sctn-cryptographic-challenges),
--   generated by the server.
-- 3. Using the response as an argument, the script calls the
--   [@navigator.credentials.create()@](https://w3c.github.io/webappsec-credential-management/#dom-credentialscontainer-create)
--   or [@navigator.credentials.get()@](https://w3c.github.io/webappsec-credential-management/#dom-credentialscontainer-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.
-- #step-4#
-- 4. The Relying Party verifies the request according to
--   [§ 7.1 Registering a New Credential](https://www.w3.org/TR/webauthn-2/#sctn-registering-a-new-credential) or
--   [§ 7.2 Verifying an Authentication Assertion](https://www.w3.org/TR/webauthn-2/#sctn-verifying-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](https://github.com/tweag/webauthn/blob/master/server/www/unauthenticated.js).
-- See also these [Sample API Usage Scenarios](https://www.w3.org/TR/webauthn-2/#sctn-sample-scenarios).
--
-- == WebAuthn Security considerations
--
-- [Chapter 13](https://www.w3.org/TR/webauthn-2/#sctn-security-considerations)
-- details the security considerations of WebAuthn. It is highly recommend to
-- read at least the
-- [relying party section](https://www.w3.org/TR/webauthn-2/#sctn-security-considerations-rp)
-- 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
module Crypto.WebAuthn
  ( -- * Model Types

    -- | A set of types representing credential options ('CredentialOptions')
    -- and their resulting credentials responses ('Credential'), used in
    -- [step 2](#step-2) and [step 4](#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](https://github.com/github/webauthn-json) JavaScript
    -- library: Encoding 'CredentialOptions' to intermediate JSON-serializable
    -- types using 'wjEncodeCredentialOptionsRegistration' and
    -- 'wjEncodeCredentialOptionsAuthentication', which can be used for [step
    -- 2](#step-2). Also decoding 'Credential's from intermediate
    -- JSON-deserializable types using 'wjDecodeCredentialRegistration' and
    -- 'wjDecodeCredentialAuthentication', which can be used for [step
    -- 4](#step-4).
    module Crypto.WebAuthn.Encoding,

    -- * Attestation Statement Formats

    -- | In case of a [registration ceremony](https://www.w3.org/TR/webauthn-2/#registration),
    -- there is the possibility for the Relying Party to request an
    -- [attestation](https://www.w3.org/TR/webauthn-2/#sctn-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](#step-4).
    -- This is the main functionality implemented by the library. This module
    -- exports these two main symbols:
    --
    -- * 'verifyRegistrationResponseL3': Verifies a 'Credential' response for
    --   registration using the L3 spec, supporting conditional create.
    -- * 'verifyRegistrationResponse': Verifies a 'Credential' response for
    --   registration using the L2 spec.
    -- * 'verifyAuthenticationResponse': Verifies a 'Credential' response for
    --   authentication.
    module Crypto.WebAuthn.Operation,

    -- * Metadata

    -- | A function for decoding a [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/)
    -- 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](https://fidoalliance.org/certification/functional-certification/).
    --
    -- Notably this library does not define any functions for fetching the
    -- metadata, which is left to the user of the library. See the
    -- [@MetadataFetch@](https://github.com/tweag/webauthn/blob/master/server/src/MetadataFetch.hs)
    -- 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,
  )
where

import Crypto.WebAuthn.AttestationStatementFormat
import Crypto.WebAuthn.Encoding
import Crypto.WebAuthn.Metadata
import Crypto.WebAuthn.Model
import Crypto.WebAuthn.Operation