Crypto.WebAuthn.Operation.Registration

This module implements attestation of the received authenticator response. See the WebAuthn specification for the algorithm implemented in this module. Assertion is typically represented as a "register" action in the front-end. Section 7 of the specification describes when the relying party must perform attestation. Another relevant section is Section 1.3.1 which is a high level overview of the registration procedure.

Documentation

verifyRegistrationResponse

Arguments

:: Origin

The origin of the server

-> RpIdHash

The relying party id

-> MetadataServiceRegistry

The metadata registry, used for verifying the validity of the attestation by looking up root certificates

-> DateTime

The current time, used for verifying the validity of the attestation statement certificate chain

-> CredentialOptions 'Registration

The options passed to the create() method

-> Credential 'Registration 'True

The response from the authenticator

-> Validation (NonEmpty RegistrationError) RegistrationResult

Either a nonempty list of validation errors in case the attestation FailedReason Or () in case of a result.

(spec) The resulting rrEntry of this call should be stored in a database by the Relying Party. The rrAttestationStatement contains the result of the attempted attestation, allowing the Relying Party to reject certain authenticators/attempted entry creations based on policy.

data RegistrationError

All the errors that can result from a call to verifyRegistrationResponse

Constructors

RegistrationChallengeMismatch

The received challenge does not match the originally created challenge

Fields

• reCreatedChallenge :: Challenge

  The challenge created by the relying party and part of the CredentialOptions

• reReceivedChallenge :: Challenge

  The challenge received from the client, part of the response

RegistrationOriginMismatch

The returned origin does not match the relying party's origin

Fields

• reExpectedOrigin :: Origin

  The origin explicitly passed to the verifyRegistrationResponse response, set by the RP

• reReceivedOrigin :: Origin

  The origin received from the client as part of the client data

RegistrationRpIdHashMismatch

The rpIdHash in the authData is not a valid hash over the RpId expected by the Relying party

Fields

• reExpectedRpIdHash :: RpIdHash

  The RP ID hash explicitly passed to the verifyRegistrationResponse response, set by the RP

• reReceivedRpIdHash :: RpIdHash

  The RP ID hash received from the client as part of the authenticator data

RegistrationUserNotPresent

The userpresent bit in the authdata was not set

RegistrationUserNotVerified

The userverified bit in the authdata was not set

RegistrationPublicKeyAlgorithmDisallowed

The algorithm received from the client was not one of the algorithms we (the relying party) requested from the client.

Fields

• reAllowedSigningAlgorithms :: [CoseSignAlg]

  The signing algorithms requested by the RP

• reReceivedSigningAlgorithm :: CoseSignAlg

  The signing algorithm received from the client

forall a.AttestationStatementFormat a => RegistrationAttestationFormatError a (NonEmpty (AttStmtVerificationError a))

There was some exception in the statement format specific section

Instances

Exception RegistrationError

Defined in Crypto.WebAuthn.Operation.Registration

Methods

toException :: RegistrationError -> SomeException

fromException :: SomeException -> Maybe RegistrationError

displayException :: RegistrationError -> String

Show RegistrationError

Defined in Crypto.WebAuthn.Operation.Registration

Methods

showsPrec :: Int -> RegistrationError -> ShowS

show :: RegistrationError -> String

showList :: [RegistrationError] -> ShowS

data RegistrationResult

The result returned from verifyRegistrationResponse. It indicates that the operation of registering a new credential didn't fail.

Constructors

RegistrationResult

Fields

• rrEntry :: CredentialEntry

  The entry to insert into the database

• rrAttestationStatement :: SomeAttestationStatement

  Information about the attestation statement

Instances

ToJSON RegistrationResult

Defined in Crypto.WebAuthn.Operation.Registration

Methods

toJSON :: RegistrationResult -> Value

toEncoding :: RegistrationResult -> Encoding

toJSONList :: [RegistrationResult] -> Value

toEncodingList :: [RegistrationResult] -> Encoding

Generic RegistrationResult

Defined in Crypto.WebAuthn.Operation.Registration

Associated Types

type Rep RegistrationResult :: Type -> Type

Methods

from :: RegistrationResult -> Rep RegistrationResult x

to :: Rep RegistrationResult x -> RegistrationResult

Show RegistrationResult

Defined in Crypto.WebAuthn.Operation.Registration

Methods

showsPrec :: Int -> RegistrationResult -> ShowS

show :: RegistrationResult -> String

showList :: [RegistrationResult] -> ShowS

type Rep RegistrationResult

Defined in Crypto.WebAuthn.Operation.Registration

type Rep RegistrationResult = D1 ('MetaData "RegistrationResult" "Crypto.WebAuthn.Operation.Registration" "webauthn-0.4.1.1-inplace" 'False) (C1 ('MetaCons "RegistrationResult" 'PrefixI 'True) (S1 ('MetaSel ('Just "rrEntry") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 CredentialEntry) :*: S1 ('MetaSel ('Just "rrAttestationStatement") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 SomeAttestationStatement)))

data AuthenticatorModel k where

Information about the authenticator model that created the public key credential. Depending on the constructor, this information can be used to base security decisions.

Constructors

UnknownAuthenticator :: AuthenticatorModel 'Unverifiable

An unknown authenticator, meaning that we received no information about what authenticator model was used to generate the public key credential. We therefore also cannot assume any security guarantees regarding how the key is stored and other properties of the authenticator. This is expected to be the case when the "none" Attestation Conveyance Preference was selected.

UnverifiedAuthenticator

An authenticator that provided a verifiable attestation type, see Verifiable, but the certificate chain in the attestation statement failed to be verified. This is an indication that the uaIdentifier and uaMetadata fields cannot be trusted currently. This can happen when the root certificate of the chain is not trusted or known. Root certificates are discovered using both the AttestationStatementFormats asfTrustAnchors method, and the passed MetadataServiceRegistry. The relying party can decide what to do in such a case, for example:

1. Treating it as if it was an UnknownAuthenticator, but logging the SomeAttestationStatement structure, so that the admin can be informed of this and perhaps add custom entries to the MetadataServiceRegistry to allow such authenticators to be verified in the future
2. Only using the uaIdentifier and uaMetadata for non-security-critical decisions. For example in order to show the user which authenticator they used to register.

Fields

• :: { uaFailures :: NonEmpty FailedReason

  The failures that occurred when trying to validate the certificate chain

•    , uaIdentifier :: AuthenticatorIdentifier p

  The identifier for the authenticator model

•    , uaMetadata :: Maybe (MetadataEntry p)

  The metadata looked up in the provided MetadataServiceRegistry This field is always equal to 'Meta.queryMetadata registry vaIdentifier', and is only provided for convenience and because the implementation already has to look it up

•    } -> AuthenticatorModel ('Verifiable p)

VerifiedAuthenticator

An authenticator that provided a verifiable attestation type, see Verifiable and whose certificate chain in the attestation statement could successfully be verified. This is an indication that the uaIdentifier and uaMetadata fields can be trusted, meaning that we can be sure that the CredentialEntry was created from the authenticator model with these fields as properties. In this case, the Relying Party can reasonably do the following:

• Persistently store the vaIdentifier alongside CredentialEntry, such that even after the registration is complete, the vaMetadata entry from the MetadataServiceRegistry can be accessed. This also allows getting more up-to-date metadata (or at all if vaMetadata was Nothing) on an authenticator over time.
• The vaMetadata may be used to determine whether this authenticator model is trustful enough to be allowed for registration. For example, srStatus in meStatusReports may be inspected for the authenticator being FIDO_CERTIFIED, aka that it passed the FIDO Alliances Functional Certification
• It is encouraged to persistently store the certificate chain from the AttestationType and check CRLs for revocations of any certificates in the chain. See here for more information

Fields

• :: { vaIdentifier :: AuthenticatorIdentifier p

  The identifier for the authenticator model

•    , vaMetadata :: Maybe (MetadataEntry p)

  The metadata looked up in the provided MetadataServiceRegistry This field is always equal to 'Meta.queryMetadata registry vaIdentifier', and is only provided for convenience and because the implementation already has to look it up

•    } -> AuthenticatorModel ('Verifiable p)

Instances

ToJSON (AuthenticatorModel k)

Defined in Crypto.WebAuthn.Operation.Registration

Methods

toJSON :: AuthenticatorModel k -> Value

toEncoding :: AuthenticatorModel k -> Encoding

toJSONList :: [AuthenticatorModel k] -> Value

toEncodingList :: [AuthenticatorModel k] -> Encoding

Show (AuthenticatorModel k)

Defined in Crypto.WebAuthn.Operation.Registration

Methods

showsPrec :: Int -> AuthenticatorModel k -> ShowS

show :: AuthenticatorModel k -> String

showList :: [AuthenticatorModel k] -> ShowS

Eq (AuthenticatorModel k)

Defined in Crypto.WebAuthn.Operation.Registration

Methods

(==) :: AuthenticatorModel k -> AuthenticatorModel k -> Bool

(/=) :: AuthenticatorModel k -> AuthenticatorModel k -> Bool

data SomeAttestationStatement

Some attestation statement that represents both the attestation type that was returned along with information about the authenticator model that created it. This result may be inspected to enforce relying party policy, see the individual fields for more information.

Constructors

forall k. SomeAttestationStatement

Fields

• asType :: AttestationType k

  The attestation type of the attestation statement. This could be used to only allow specific attestation types. E.g. disallowing Basic and Self attestation, or marking those specially in the database.

• asModel :: AuthenticatorModel k

  The authenticator model that produced the attestation statement. Relying Party policy could accept this credential based on properties of this field:

  • Disallowing unverified authenticators by checking whether it is an UnverifiedAuthenticator
  • Disallowing authenticators that don't meet the required security level by inspecting the vaMetadata of a VerifiedAuthenticator
  • Only allowing a very specific authenticator to be used by looking at vaIdentifier of a VerifiedAuthenticator

Instances

ToJSON SomeAttestationStatement

Defined in Crypto.WebAuthn.Operation.Registration

Methods

toJSON :: SomeAttestationStatement -> Value

toEncoding :: SomeAttestationStatement -> Encoding

toJSONList :: [SomeAttestationStatement] -> Value

toEncodingList :: [SomeAttestationStatement] -> Encoding

Show SomeAttestationStatement

Defined in Crypto.WebAuthn.Operation.Registration

Methods

showsPrec :: Int -> SomeAttestationStatement -> ShowS

show :: SomeAttestationStatement -> String

showList :: [SomeAttestationStatement] -> ShowS