Stability | experimental |
---|---|
Safe Haskell | None |
Language | Haskell2010 |
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.
Synopsis
- verifyAuthenticationResponse :: Origin -> RpIdHash -> Maybe UserHandle -> CredentialEntry -> CredentialOptions 'Authentication -> Credential 'Authentication 'True -> Validation (NonEmpty AuthenticationError) AuthenticationResult
- data AuthenticationError
- = AuthenticationDisallowedCredential [CredentialDescriptor] (Credential 'Authentication 'True)
- | AuthenticationIdentifiedUserHandleMismatch UserHandle UserHandle
- | AuthenticationCredentialUserHandleMismatch UserHandle UserHandle
- | AuthenticationCannotVerifyUserHandle
- | AuthenticationChallengeMismatch Challenge Challenge
- | AuthenticationOriginMismatch Origin Origin
- | AuthenticationRpIdHashMismatch RpIdHash RpIdHash
- | AuthenticationUserNotPresent
- | AuthenticationUserNotVerified
- | AuthenticationSignatureDecodingError DeserialiseFailure
- | AuthenticationInvalidSignature PublicKey ByteString AssertionSignature Text
- newtype AuthenticationResult = AuthenticationResult {}
- data SignatureCounterResult
Documentation
verifyAuthenticationResponse Source #
:: 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 Source #
Errors that may occur during assertion
AuthenticationDisallowedCredential [CredentialDescriptor] (Credential 'Authentication 'True) | The provided Credential was not one explicitly allowed by the server (first: allowed credentials, second: received credential) |
AuthenticationIdentifiedUserHandleMismatch UserHandle UserHandle | The received credential does not match the currently identified user (first: identified, second: received) |
AuthenticationCredentialUserHandleMismatch UserHandle UserHandle | The stored credential does not match the user specified in the response (first: stored, second: received) |
AuthenticationCannotVerifyUserHandle | No user was identified and the response did not specify a user |
AuthenticationChallengeMismatch Challenge Challenge | The received challenge does not match the originally created challenge (first: expected, second: received) |
AuthenticationOriginMismatch Origin Origin | The origin derived by the client does match the assumed origin (first: expected, second: received) |
AuthenticationRpIdHashMismatch RpIdHash RpIdHash | The rpIdHash in the authData is not a valid hash over the RpId expected by the Relying party (first: expected, second: received) |
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 |
AuthenticationInvalidSignature PublicKey ByteString AssertionSignature Text | the public key does verify the signature over the authData |
Instances
Show AuthenticationError Source # | |
Defined in Crypto.WebAuthn.Operation.Authentication showsPrec :: Int -> AuthenticationError -> ShowS # show :: AuthenticationError -> String # showList :: [AuthenticationError] -> ShowS # | |
Exception AuthenticationError Source # | |
newtype AuthenticationResult Source #
A successful result of verifyAuthenticationResponse
, it should be inspected by the Relying Party to enforce its policy regarding logins.
AuthenticationResult | |
|
Instances
Eq AuthenticationResult Source # | |
Defined in Crypto.WebAuthn.Operation.Authentication (==) :: AuthenticationResult -> AuthenticationResult -> Bool # (/=) :: AuthenticationResult -> AuthenticationResult -> Bool # | |
Show AuthenticationResult Source # | |
Defined in Crypto.WebAuthn.Operation.Authentication showsPrec :: Int -> AuthenticationResult -> ShowS # show :: AuthenticationResult -> String # showList :: [AuthenticationResult] -> ShowS # |
data SignatureCounterResult Source #
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.
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
Eq SignatureCounterResult Source # | |
Defined in Crypto.WebAuthn.Operation.Authentication | |
Show SignatureCounterResult Source # | |
Defined in Crypto.WebAuthn.Operation.Authentication showsPrec :: Int -> SignatureCounterResult -> ShowS # show :: SignatureCounterResult -> String # showList :: [SignatureCounterResult] -> ShowS # |