Stability | experimental |
---|---|
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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.
Synopsis
- verifyRegistrationResponse :: NonEmpty Origin -> RpIdHash -> MetadataServiceRegistry -> DateTime -> CredentialOptions 'Registration -> Credential 'Registration 'True -> Validation (NonEmpty RegistrationError) RegistrationResult
- data RegistrationError
- = RegistrationChallengeMismatch { }
- | RegistrationOriginMismatch { }
- | RegistrationRpIdHashMismatch { }
- | RegistrationUserNotPresent
- | RegistrationUserNotVerified
- | RegistrationPublicKeyAlgorithmDisallowed { }
- | forall a.AttestationStatementFormat a => RegistrationAttestationFormatError a (NonEmpty (AttStmtVerificationError a))
- data RegistrationResult = RegistrationResult {}
- data AuthenticatorModel k where
- UnknownAuthenticator :: AuthenticatorModel 'Unverifiable
- UnverifiedAuthenticator :: {..} -> AuthenticatorModel ('Verifiable p)
- VerifiedAuthenticator :: {..} -> AuthenticatorModel ('Verifiable p)
- data SomeAttestationStatement = forall k.SomeAttestationStatement {
- asType :: AttestationType k
- asModel :: AuthenticatorModel k
Documentation
verifyRegistrationResponse Source #
:: NonEmpty Origin | The list of allowed origins for the ceremony |
-> 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) Verifies a Credential
response for a registration ceremony.
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.
Though this library implements the WebAuthn L2 spec, for origin validation we
follow the L3 draft. This is because allowing multiple origins is often
needed in the wild. See Validating the origin of a credential
more details.
In the simplest case, just a single origin is allowed and this is the RpId
with https://
prepended:
verifyRegistrationResponse (NE.singleton (M.Origin "https://example.org")) ...
In the more complex case, multiple origins are allowed:
verifyRegistrationResponse (M.Origin <$> "https://example.org" :| ["https://signin.example.org"]) ...
One might also allow native apps to authenticate:
verifyRegistrationResponse (M.Origin <$> "https://example.org" :| ["ios:bundle-id:org.example.ourapp"]) ...
See Apple's documentation on associated domains and Google's documentation on Digital Asset Links for more information on how to link app origins to your Relying Party ID.
data RegistrationError Source #
All the errors that can result from a call to verifyRegistrationResponse
RegistrationChallengeMismatch | The received challenge does not match the originally created challenge |
| |
RegistrationOriginMismatch | The returned origin does not match any of the the relying party's origins |
| |
RegistrationRpIdHashMismatch | The rpIdHash in the authData is not a valid hash over the RpId expected by the Relying party |
| |
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. |
| |
forall a.AttestationStatementFormat a => RegistrationAttestationFormatError a (NonEmpty (AttStmtVerificationError a)) | There was some exception in the statement format specific section |
Instances
Exception RegistrationError Source # | |
Show RegistrationError Source # | |
Defined in Crypto.WebAuthn.Operation.Registration showsPrec :: Int -> RegistrationError -> ShowS # show :: RegistrationError -> String # showList :: [RegistrationError] -> ShowS # |
data RegistrationResult Source #
The result returned from verifyRegistrationResponse
. It indicates that
the operation of registering a new credential
didn't fail.
RegistrationResult | |
|
Instances
data AuthenticatorModel k where Source #
Information about the authenticator model that created the public key credential. Depending on the constructor, this information can be used to base security decisions.
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
|
| |
VerifiedAuthenticator | An authenticator that
provided a verifiable attestation type,
see
|
|
Instances
ToJSON (AuthenticatorModel k) Source # | An arbitrary and potentially unstable JSON encoding, only intended for logging purposes. To actually encode and decode structures, use the Crypto.WebAuthn.Encoding modules |
Defined in Crypto.WebAuthn.Operation.Registration toJSON :: AuthenticatorModel k -> Value # toEncoding :: AuthenticatorModel k -> Encoding # toJSONList :: [AuthenticatorModel k] -> Value # toEncodingList :: [AuthenticatorModel k] -> Encoding # | |
Show (AuthenticatorModel k) Source # | |
Defined in Crypto.WebAuthn.Operation.Registration showsPrec :: Int -> AuthenticatorModel k -> ShowS # show :: AuthenticatorModel k -> String # showList :: [AuthenticatorModel k] -> ShowS # | |
Eq (AuthenticatorModel k) Source # | |
Defined in Crypto.WebAuthn.Operation.Registration (==) :: AuthenticatorModel k -> AuthenticatorModel k -> Bool # (/=) :: AuthenticatorModel k -> AuthenticatorModel k -> Bool # |
data SomeAttestationStatement Source #
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.
forall k. SomeAttestationStatement | |
|
Instances
ToJSON SomeAttestationStatement Source # | An arbitrary and potentially unstable JSON encoding, only intended for logging purposes. To actually encode and decode structures, use the Crypto.WebAuthn.Encoding modules |
Defined in Crypto.WebAuthn.Operation.Registration | |
Show SomeAttestationStatement Source # | |
Defined in Crypto.WebAuthn.Operation.Registration showsPrec :: Int -> SomeAttestationStatement -> ShowS # show :: SomeAttestationStatement -> String # showList :: [SomeAttestationStatement] -> ShowS # |