Crypto.WebAuthn.Operation.Authentication

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

Documentation

verifyAuthenticationResponse

Arguments

:: Origin

The origin of the server

-> RpIdHash

The hash of the relying party id

-> Maybe UserHandle

The user handle, in case the user is identified already TODO: Mention that this would be empty for username-less authentication

-> CredentialEntry

The database entry for the credential, as created in the initial attestation and optionally updated in subsequent assertions

-> CredentialOptions 'Authentication

The options that were passed to the get() method

-> Credential 'Authentication 'True

The credential returned from get()

-> Validation (NonEmpty AuthenticationError) AuthenticationResult

Either a non-empty list of validation errors in case of the assertion being invalid Or in case of success a signature counter result, which should be dealt with

(spec) Verifies a Credential response for an authentication ceremony. The arSignatureCounterResult field of the result should be inspected to enforce Relying Party policy regarding potentially cloned authenticators.

data AuthenticationError

Errors that may occur during assertion

Constructors

AuthenticationCredentialDisallowed

The provided Credential was not one explicitly allowed by the server

Fields

• aeAllowedCredentials :: [CredentialDescriptor]

  The credentials allowed by the server

• aeReceivedCredential :: Credential 'Authentication 'True

  The credential returned by the client

AuthenticationIdentifiedUserHandleMismatch

The received credential does not match the currently identified user

Fields

• aeIdentifiedUser :: UserHandle

  The UserHandle of the user who is attempting authentication

• aeRegisteredUser :: UserHandle

  The owner of the credential passed to the verifyAuthenticationResponse function (retrieved from the database)

AuthenticationCredentialUserHandleMismatch

The stored credential does not match the user specified in the response

Fields

• aeIdentifiedUser :: UserHandle

  The UserHandle of the user who is attempting authentication

• aeAuthenticatorUser :: UserHandle

  The UserHandle reported by the authenticator in the response

AuthenticationCannotVerifyUserHandle

No user was identified and the response did not specify a user

AuthenticationChallengeMismatch

The received challenge does not match the originally created challenge

Fields

• aeCreatedChallenge :: Challenge

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

• aeReceivedChallenge :: Challenge

  The challenge received from the client, part of the response

AuthenticationOriginMismatch

The origin derived by the client does match the assumed origin

Fields

• aeExpectedOrigin :: Origin

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

• aeReceivedOrigin :: Origin

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

AuthenticationRpIdHashMismatch

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

Fields

• aeExpectedRpIdHash :: RpIdHash

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

• aeReceivedRpIdHash :: RpIdHash

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

AuthenticationUserNotPresent

The UserPresent bit was not set in the authData

AuthenticationUserNotVerified

The UserVerified bit was not set in the authData while user verification was required

AuthenticationSignatureDecodingError DeserialiseFailure

The public key provided in the CredentialEntry could not be decoded

AuthenticationSignatureInvalid Text

The public key doesn't verify the signature over the authData

Instances

Exception AuthenticationError

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

toException :: AuthenticationError -> SomeException

fromException :: SomeException -> Maybe AuthenticationError

displayException :: AuthenticationError -> String

Show AuthenticationError

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

showsPrec :: Int -> AuthenticationError -> ShowS

show :: AuthenticationError -> String

showList :: [AuthenticationError] -> ShowS

newtype AuthenticationResult

A successful result of verifyAuthenticationResponse, it should be inspected by the Relying Party to enforce its policy regarding logins.

Constructors

AuthenticationResult

Fields

• arSignatureCounterResult :: SignatureCounterResult

  How the signature counter of the credential changed compared to the existing database entry

Instances

Show AuthenticationResult

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

showsPrec :: Int -> AuthenticationResult -> ShowS

show :: AuthenticationResult -> String

showList :: [AuthenticationResult] -> ShowS

Eq AuthenticationResult

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

(==) :: AuthenticationResult -> AuthenticationResult -> Bool

(/=) :: AuthenticationResult -> AuthenticationResult -> Bool

data SignatureCounterResult

Section 6.1.1 of the specification describes the use of the signature counter, and describes what the relying part must do with them. In particular:

The signature counter 's purpose is to aid Relying Parties in detecting cloned authenticators. Clone detection is more important for authenticators with limited protection measures.

A Relying Party stores the signature counter of the most recent authenticatorGetAssertion operation. (Or the counter from the authenticatorMakeCredential operation if no authenticatorGetAssertion has ever been performed on a credential.) In subsequent authenticatorGetAssertion operations, the Relying Party compares the stored signature counter value with the new `signCount` value returned in the assertion’s authenticator data. If either is non-zero, and the new `signCount` value is less than or equal to the stored value, a cloned authenticator may exist, or the authenticator may be malfunctioning.

Constructors

SignatureCounterZero

There is no signature counter being used, the database entry doesn't need to be updated, but we also have no guarantees about the authenticator not being cloned

SignatureCounterUpdated SignatureCounter

The signature counter needs to be updated in the database

SignatureCounterPotentiallyCloned

The signature counter decreased, the authenticator was potentially cloned and the relying party may want to e.g. lock this credential

Instances

Show SignatureCounterResult

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

showsPrec :: Int -> SignatureCounterResult -> ShowS

show :: SignatureCounterResult -> String

showList :: [SignatureCounterResult] -> ShowS

Eq SignatureCounterResult

Defined in Crypto.WebAuthn.Operation.Authentication

Methods

(==) :: SignatureCounterResult -> SignatureCounterResult -> Bool

(/=) :: SignatureCounterResult -> SignatureCounterResult -> Bool