diff --git a/images/fido-attestation-structures.svg b/images/fido-attestation-structures.svg new file mode 100644 index 000000000..db4fe2ed7 --- /dev/null +++ b/images/fido-attestation-structures.svg @@ -0,0 +1,1619 @@ + + + +image/svg+xmlZeichenblatt-1Tabelle.4ATTESTATION OBJECTATTESTATION OBJECT +rect40line42line44line46line48line50line52line54line56line58line60line62line64line66line68rect70text72RP ID hashRP ID hash +rect76text78FLAGSFLAGS +text8200 +text8600 +text9000 +text9400 +text9800 +text102ATAT +text106EDED +text110TUPTUP +rect114text116COUNTERCOUNTER +rect120text122ATTESTATION DATAATTESTATION DATA +rect126text128EXTENSIONSEXTENSIONS +path132path134path136text13832 bytes32 bytes +text1421 byte1 byte +text1464 bytes (big-endian uint32)4 bytes (big-endian uint32) +text150variable length (if present)variable length (if present) +text154variable length (CBOR)variable length (CBOR) +text16200 +text16677 +Rechteck.3“authData“: ...“authData“: ... +Rechteck.5“fmt“: “packed“, ...“fmt“: “packed“, ... +Rechteck.6“attStmt“: ...“attStmt“: ... +line160.55line158.56Tabelle.57AUTHENTICATOR DATAAUTHENTICATOR DATA +Tabelle.58ATTESTATION STATEMENTATTESTATION STATEMENT +Rechteck.3“sig“: ...“sig“: ... +Rechteck.5“alg“: ...“alg“: ... +Rechteck.6“x5c“: ...“x5c“: ... +Tabelle.63packedpacked +text150.64If Basic or Privacy CAIf Basic or Privacy CA +Rechteck.65“daaKey“: ...“daaKey“: ... +text150.66If DAAIf DAA +Tabelle.67Other structures as defined in the respective attestation sta...Other structures as defined in the respective attestation statement format +line158.68line160.69rect120text128EXTENSIONSAAGUID +rect120 +text128EXTENSIONSL +rect120text128EXTENSIONSCREDENTIAL ID +CREDENTIAL PUBLIC KEY +rect120text154variable length (CBOR)variable length (CBOR) +LENGTH L +(variable length) +text1421 byte2 bytes +16 bytes +Tabelle.4ATTESTATION OBJECTATTESTATION DATA + \ No newline at end of file diff --git a/index.bs b/index.bs index af4da269f..01fef3a93 100644 --- a/index.bs +++ b/index.bs @@ -52,11 +52,11 @@ spec: HTML51; urlPrefix: http://www.w3.org/TR/html51/; for: web text: current settings object; for:web; url:current-settings-object text: Navigator; for: interface; url:the-navigator-object -spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/; for: web +spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/; for: web type: dfn text: normalizing an algorithm; url: dfn-normalize-an-algorithm -spec: Encoding; urlPrefix: https://www.w3.org/TR/encoding/; for: encoding +spec: Encoding; urlPrefix: https://www.w3.org/TR/encoding/; type: dfn text: UTF-8 Encoded; url: utf-8-encode @@ -135,7 +135,7 @@ A variety of additional use cases and configurations are also possible, includin - A user navigates to example.com on their laptop, is guided through a flow to create and register a credential on their phone. -- A user obtains an discrete, roaming authenticator, such as a "fob" with USB or USB+NFC/BLE connectivity options, loads +- A user obtains an discrete, roaming authenticator, such as a "fob" with USB or USB+NFC/BLE connectivity options, loads example.com in their browser on a laptop or phone, and is guided though a flow to create and register a credential on the fob. @@ -160,35 +160,37 @@ or a combination of both. This specification relies on several other underlying specifications. -: HTML -:: The concepts of current settings object, origin, - opaque origin, relaxing the same-origin restriction, and the Navigator interface are - defined in [[!HTML51]]. +: Base64url encoding +:: The term Base64url Encoding refers to the base64 encoding using the URL- and filename-safe character set defined + in Section 5 of [[!RFC4648]], with all trailing '=' characters omitted (as permitted by Section 3.2) and without the + inclusion of any line breaks, whitespace, or other additional characters. -: Web IDL -:: Many of the interface definitions and all of the IDL in this specification depend on [[!WebIDL-1]]. This updated version of - the Web IDL standard adds support for Promises, which are now the preferred mechanism for asynchronous - interaction in all new web APIs. +: CBOR +:: A number of structures in this specification, including attestation statements and extensions, are encoded using the Compact + Binary Object Representation (CBOR) [[!RFC7049]]. + +: CDDL +:: This specification describes the syntax of all CBOR-encoded data using the CBOR Data Definition Language (CDDL) [[!CDDL]]. : DOM :: DOMException and the DOMException values used in this specification are defined in [[!DOM4]]. +: HTML +:: The concepts of current settings object, origin, + opaque origin, relaxing the same-origin restriction, and the Navigator interface are + defined in [[!HTML51]]. + : Web Cryptography API :: The AlgorithmIdentifier type and the method for normalizing an algorithm are defined in [[WebCryptoAPI#algorithm-dictionary]]. +: Web IDL +:: Many of the interface definitions and all of the IDL in this specification depend on [[!WebIDL-1]]. This updated version of + the Web IDL standard adds support for Promises, which are now the preferred mechanism for asynchronous + interaction in all new web APIs. - -: Base64url encoding -:: The term Base64url Encoding refers to the base64 encoding using the URL- and filename-safe character set defined - in Section 5 of [[!RFC4648]], with all trailing '=' characters omitted (as permitted by Section 3.2) and without the - inclusion of any line breaks, whitespace, or other additional characters. This is the same encoding as used by JSON Web - Signature (JWS) [[RFC7515]]. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and -"OPTIONAL" in this document are to be interpreted as described in -[[!RFC2119]]. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in [[!RFC2119]]. # Terminology # {#terminology} @@ -204,9 +206,9 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and : Attestation :: Generally, a statement that serves to bear witness, confirm, or authenticate. In the WebAuthn context, attestation is employed to attest to the provenance of an authenticator and the data it emits; - including, for example: credential IDs, credential key pairs, signature counters, etc. Attestation information is - conveyed in attestation statements. - See also attestation format, and attestation type. + including, for example: credential IDs, credential key pairs, signature counters, etc. Attestation information is + conveyed in attestation objects. + See also attestation statement format, and attestation type. : Attestation Certificate :: A X.509 Certificate for the attestation key pair used by an Authenticator to attest to its manufacture @@ -219,30 +221,34 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and : Authentication :: The ceremony where a user, and the user's computing device(s) (containing at least one authenticator) work in - concert to cryptographically prove to an [RP] that the user controls the private key associated with a - previously-registered scoped credential (see Registration). Note that this includes employing user - verification. + concert to cryptographically prove to an [RP] that the user controls the private key associated with a + previously-registered scoped credential (see Registration). Note that this includes employing user + verification. + +: Authentication Assertion +:: The cryptographically signed {{AuthenticationAssertion}} object returned by an authenticator as the result of a + authenticatorGetAssertion operation. : Authenticator :: A cryptographic device used by a [WAC] to (i) generate a scoped credential and register it with a [RP], - and (ii) subsequently used to cryptographically sign and return, in the form of an Authentication Assertion, a challenge - and other data presented by a [RP] (in concert with the [WAC]) in order to effect authentication. + and (ii) subsequently used to cryptographically sign and return, in the form of an Authentication Assertion, a + challenge and other data presented by a [RP] (in concert with the [WAC]) in order to effect authentication. : Authorization Gesture :: Essentially the same as user verification. : Ceremony :: The concept of a ceremony [[Ceremony]] is an extension of the concept of a network protocol, with human nodes alongside - computer nodes and with communication links that include UI, human-to-human communication and transfers of physical objects - that carry data. What is out-of-band to a protocol is in-band to a ceremony. In this specification, Registration, - Authentication, and user verification are ceremonies. + computer nodes and with communication links that include UI, human-to-human communication and transfers of physical objects + that carry data. What is out-of-band to a protocol is in-band to a ceremony. In this specification, Registration, + Authentication, and user verification are ceremonies. : Client :: See Conforming User Agent. : Conforming User Agent :: A user agent implementing, in conjunction with the underlying platform, the Web Authentication API and algorithms - given in this specification, and handling communication between Authenticators and [RPS]. + given in this specification, and handling communication between Authenticators and [RPS]. : Credential Public Key :: The public key portion of an [RP]-specific credential key pair, generated by an authenticator and @@ -253,8 +259,8 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and : Registration :: The ceremony where a user, a [RP], and the user's computing device(s) (containing at least one - authenticator) work in concert to create a scoped credential and associate it with the user's [RP] - account. Note that this includes employing user verification. + authenticator) work in concert to create a scoped credential and associate it with the user's [RP] + account. Note that this includes employing user verification. : [RP] :: The entity whose web application utilizes the Web Authentication API to register and authenticate users. See @@ -273,39 +279,31 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and : Scoped Credential :: Generically, a credential is data one entity presents to another in order to authenticate the former's identity [[RFC4949]]. - A WebAuthn scoped credential is a { identifier, type } pair identifying authentication - information established by the authenticator and the [RP], together, at registration time. The authentication + A WebAuthn scoped credential is a { identifier, type } pair identifying authentication + information established by the authenticator and the [RP], together, at registration time. The authentication information consists of an asymmetric key pair, where the public key portion is returned to the [RP], which stores it in conjunction with the present user's account. The authenticator maps the private key to the [RP]'s RP ID and stores it. Subsequently, only that [RP], as identified by its RP ID, is able to employ the scoped credential in - authentication ceremonies, via the getAssertion() method. The [RP] uses its copy of the stored public key to + authentication ceremonies, via the getAssertion() method. The [RP] uses its copy of the stored public key to verify the resultant Authentication Assertion. - : User Consent :: User consent means the user agrees with what they are being asked, i.e., it encompasses reading and understanding prompts. - User verification encompasses the means employed by the user to indicate consent. + User verification encompasses the means employed by the user to indicate consent. : User Verification :: The process by which an authenticator locally authorizes the invocation of the - authenticatorMakeCredential and authenticatorGetAssertion operations, for example through a touch plus pin - code, a password, a gesture (e.g., presenting a fingerprint), or other modality. Note that invocation of said operations - implies use of key material managed by the authenticator. - -: Authentication Assertion -:: The cryptographically signed {{AuthenticationAssertion}} object returned by an authenticator as the result of an - authenticatorGetAssertion operation. + authenticatorMakeCredential and authenticatorGetAssertion operations, for example through a touch plus pin + code, a password, a gesture (e.g., presenting a fingerprint), or other modality. Note that invocation of said operations + implies use of key material managed by the authenticator. : [WAC] :: See Conforming User Agent. - - # Web Authentication API # {#api} -This section normatively specifies the API for creating and using scoped credentials. Support for deleting credentials is -deliberately omitted; this is expected to be done through platform-specific user interfaces rather than from a script. The basic +This section normatively specifies the API for creating and using scoped credentials. The basic idea is that the credentials belong to the user and are managed by an authenticator, with which the [RP] interacts through the client (consisting of the browser and underlying OS platform). Scripts can (with the user's consent) request the browser to create a new credential for future use by the [RP]. Scripts can also request the user’s permission to perform authentication @@ -313,11 +311,18 @@ operations with an existing credential. All such operations are performed in the and/or platform on the user's behalf. At no point does the script get access to the credentials themselves; it only gets information about the credentials in the form of objects. +In addition to the above script interface, the authenticator may implement (or come with client software that implements) a user +interface for management. Such an interface may be used, for example, to reset the authenticator to a clean state or to inspect +the current state of the authenticator. In other words, such an interface is similar to the user interfaces provided by browsers +for managing user state such as history, saved passwords and cookies. Authenticator management actions such as credential +deletion are considered to be the responsibility of such a user interface and are deliberately omitted from the API exposed to +scripts. + The security properties of this API are provided by the client and the authenticator working together. The authenticator, which holds and manages credentials, ensures that all operations are scoped to a particular origin, and cannot be replayed against -a different origin, by incorporating the origin in its responses. Specifically, as defined in [[#signature-format]], the full -origin of the requester is included, and signed over, in the attestation statement produced when a new credential is created as -well as in all assertions produced by WebAuthn credentials. +a different origin, by incorporating the origin in its responses. Specifically, as defined in [[#authenticator-ops]], the full +origin of the requester is included, and signed over, in the attestation object produced when a new credential is created +as well as in all assertions produced by WebAuthn credentials. Additionally, to maintain user privacy and prevent malicious [RPS] from probing for the presence of credentials belonging to other [RPS], each credential is also associated with a Relying Party Identifier, or RP ID. This RP ID is provided by the client @@ -363,6 +368,7 @@ This interface has two methods, which are described in the following subsections ### Create a new credential (makeCredential() method) ### {#makeCredential} +
With this method, a script can request the User Agent to create a new credential of a given type and persist it to the underlying platform, which may involve data storage managed by the browser or the OS. The user agent will prompt the user to approve this operation. On success, the promise will be resolved with a {{ScopedCredentialInfo}} object describing the newly @@ -385,19 +391,18 @@ This method takes the following parameters: The sequence is ordered from most preferred to least preferred. The platform makes a best effort to create the most preferred credential that it can. -- The attestationChallenge parameter contains a challenge intended to be used for generating the attestation - statement of the newly created credential. +- The attestationChallenge parameter contains a challenge intended to be used for generating the newly created + credential's attestation object. - The optional options parameter specifies additional options, as described in [[#credential-options]]. When this method is invoked, the user agent MUST execute the following algorithm: -1. If the {{ScopedCredentialOptions/timeoutSeconds}} member of {{options}} is present, check if its value lies - within a reasonable range as defined by - the platform and if not, correct it to the closest value lying within that range. Set |adjustedTimeout| to this adjusted - value. If {{ScopedCredentialOptions/timeoutSeconds}} was not specified, then set |adjustedTimeout| to a platform-specific - default. +1. If the {{ScopedCredentialOptions/timeoutSeconds}} member of {{options}} is present, check if its value lies within + a reasonable range as defined by the platform and if not, correct it to the closest value lying within that range. Set + |adjustedTimeout| to this adjusted value. If {{ScopedCredentialOptions/timeoutSeconds}} was not specified, then set + |adjustedTimeout| to a platform-specific default. 2. Let |promise| be a new Promise. Return |promise| and start a timer for |adjustedTimeout| seconds. Then asynchronously continue executing the following steps. If any fatal error is encountered in this process other than the @@ -407,20 +412,18 @@ When this method is invoked, the user agent MUST execute the following algorithm 3. Set |callerOrigin| to the current settings object's origin. If |callerOrigin| is an opaque origin, reject |promise| with a DOMException whose name is "NotAllowedError", and terminate this algorithm. Otherwise, - - If the {{ScopedCredentialOptions/rpId}} member of {{options}} is not present, then set |rpId| to |callerOrigin|, - and |rpIdHash| to the SHA-256 hash of |rpId|. - - If the {{ScopedCredentialOptions/rpId}} member of {{options}} is present, then invoke the procedure used for - relaxing the same-origin - restriction by setting the `document.domain` attribute, using {{ScopedCredentialOptions/rpId}} as the given value - but without changing the current document's `domain`. If no errors are thrown, set |rpId| to the value of `host` as - computed by this procedure, and |rpIdHash| to the SHA-256 hash of the UTF-8 encoding of |rpId|. Otherwise, reject |promise| with a + - If the {{ScopedCredentialOptions/rpId}} member of {{options}} is not present, then set |rpId| to |callerOrigin|. + - If the {{ScopedCredentialOptions/rpId}} member of {{options}} is present, then invoke the procedure used for + relaxing the same-origin restriction by setting the `document.domain` attribute, using + {{ScopedCredentialOptions/rpId}} as the given value but without changing the current document's `domain`. If no errors + are thrown, set |rpId| to the value of `host` as computed by this procedure. Otherwise, reject |promise| with a DOMException whose name is "SecurityError", and terminate this algorithm. 4. Process each element of {{cryptoParameters}} using the following steps, to produce a new sequence |normalizedParameters|. - Let |current| be the currently selected element of {{cryptoParameters}}. - If `current.type` does not contain a {{ScopedCredentialType}} supported by this implementation, then stop processing |current| and move on to the next element in {{cryptoParameters}}. - - Let |normalizedAlgorithm| be the result of normalizing an algorithm [[!WebCryptoAPI]], + - Let |normalizedAlgorithm| be the result of normalizing an algorithm [[!WebCryptoAPI]], with |alg| set to `current.algorithm` and |op| set to 'generateKey'. If an error occurs during this procedure, then stop processing |current| and move on to the next element in {{cryptoParameters}}. - Add a new object of type {{ScopedCredentialParameters}} to |normalizedParameters|, with |type| set to `current.type` and @@ -436,17 +439,17 @@ When this method is invoked, the user agent MUST execute the following algorithm 7. Use {{attestationChallenge}}, |callerOrigin| and |rpId|, along with the token binding key associated with |callerOrigin| (if any), to create a {{ClientData}} structure representing this request. Choose a hash algorithm for {{ClientData/hashAlg}} and - compute the clientDataJSON and clientDataHash. + compute the {{ScopedCredentialInfo/clientDataJSON}} and its clientDataHash. 8. Initialize |issuedRequests| and |currentlyAvailableAuthenticators| to empty lists. 9. For each authenticator currently available on this platform, add the authenticator to |currentlyAvailableAuthenticators| - unless the {{ScopedCredentialOptions/attachment}} member of {{options}} is present. In that case, let |attachment| be - {{ScopedCredentialOptions/attachment}}, and add the authenticator to |currentlyAvailableAuthenticators| if its attachment + unless the {{ScopedCredentialOptions/attachment}} member of {{options}} is present. In that case, let |attachment| + be {{ScopedCredentialOptions/attachment}}, and add the authenticator to |currentlyAvailableAuthenticators| if its attachment modality matches |attachment|. 10. For each authenticator in |currentlyAvailableAuthenticators|: asynchronously invoke the authenticatorMakeCredential - operation on that authenticator with |rpIdHash|, clientDataHash, {{accountInformation}}, |normalizedParameters|, + operation on that authenticator with |rpId|, clientDataHash, {{accountInformation}}, |normalizedParameters|, {{ScopedCredentialOptions/excludeList}} and |clientExtensions| as parameters. Add a corresponding entry to |issuedRequests|. - For each credential |C| in the {{ScopedCredentialOptions/excludeList}} member of {{options}} that has a non-empty |transports| list, optionally use only the specified transports to test for the existence of |C|. @@ -462,7 +465,7 @@ When this method is invoked, the user agent MUST execute the following algorithm - If any authenticator indicates success: - Remove this authenticator's entry from |issuedRequests|. - Create a new {{ScopedCredentialInfo}} object named |value| and populate its fields with the values returned from the - authenticator as well as the clientDataJSON computed earlier. + authenticator as well as the {{ScopedCredentialInfo/clientDataJSON}} computed earlier. - For each remaining entry in |issuedRequests| invoke the authenticatorCancel operation on that authenticator and remove its entry from the list. - Resolve |promise| with |value| and terminate this algorithm. @@ -471,10 +474,12 @@ When this method is invoked, the user agent MUST execute the following algorithm During the above process, the user agent SHOULD show some UI to the user to guide them in the process of selecting and authorizing an authenticator. +
### Use an existing credential (getAssertion() method) ### {#getAssertion} +
This method is used to discover and use an existing scoped credential, with the user's consent. The script optionally specifies some criteria to indicate what credentials are acceptable to it. The user agent and/or platform locates credentials matching the specified criteria, and guides the user to pick one that the script should be allowed to use. The user may choose not to provide @@ -490,7 +495,7 @@ This method takes the following parameters: When this method is invoked, the user agent MUST execute the following algorithm: -1. If the {{AssertionOptions/timeoutSeconds}} member of {{options}} is present, check if its value lies within a +1. If the {{AssertionOptions/timeoutSeconds}} member of {{options}} is present, check if its value lies within a reasonable range as defined by the platform and if not, correct it to the closest value lying within that range. Set |adjustedTimeout| to this adjusted value. If {{AssertionOptions/timeoutSeconds}} is not present, then set |adjustedTimeout| to a platform-specific default. @@ -503,36 +508,35 @@ When this method is invoked, the user agent MUST execute the following algorithm 3. Set |callerOrigin| to the current settings object's origin. If |callerOrigin| is an opaque origin, reject |promise| with a DOMException whose name is "NotAllowedError", and terminate this algorithm. Otherwise, - - If the {{AssertionOptions/rpId}} member of {{options}} is not present, then set |rpId| to |callerOrigin|, and - |rpIdHash| to the SHA-256 hash of the UTF-8 encoding of |rpId|. - - If the {{AssertionOptions/rpId}} member of {{options}} is present, then invoke the procedure used for relaxing + - If the {{AssertionOptions/rpId}} member of {{options}} is not present, then set |rpId| to |callerOrigin|. + - If the {{AssertionOptions/rpId}} member of {{options}} is present, then invoke the procedure used for relaxing the same-origin restriction by setting the `document.domain` attribute, using {{AssertionOptions/rpId}} as the given value but without changing the current document's `domain`. If no errors are thrown, set |rpId| to the value of `host` - as computed by this procedure, and |rpIdHash| to the SHA-256 hash of the UTF-8 encoding of |rpId|. Otherwise, reject - |promise| with a DOMException whose name is "SecurityError", and terminate this algorithm. + as computed by this procedure. Otherwise, reject |promise| with a DOMException whose name is "SecurityError", and + terminate this algorithm. -4. If the {{AssertionOptions/extensions}} member of {{options}} is present, process any extensions supported by this +4. If the {{AssertionOptions/extensions}} member of {{options}} is present, process any extensions supported by this client platform, to produce the extension data that needs to be sent to the authenticator. If an error is encountered while processing an extension, skip that extension and do not produce any extension data for it. Call the result of this processing |clientExtensions|. 5. Use {{assertionChallenge}}, |callerOrigin| and |rpId|, along with the token binding key associated with |callerOrigin| (if any), to create a {{ClientData}} structure representing this request. Choose a hash algorithm for {{ClientData/hashAlg}} and - compute the clientDataJSON and clientDataHash. + compute the {{AuthenticationAssertion/clientDataJSON}} and clientDataHash. 6. Initialize |issuedRequests| to an empty list. 7. For each authenticator currently available on this platform, perform the following steps: - - If the {{AssertionOptions/allowList}} member of {{options}} is empty, let |credentialList| be an empty list. Otherwise, + - If the {{AssertionOptions/allowList}} member of {{options}} is empty, let |credentialList| be an empty list. Otherwise, execute a platform-specific procedure to determine which, if any, credentials listed in {{AssertionOptions/allowList}} might be present on this authenticator, and set |credentialList| to this filtered list. If no such filtering is possible, set |credentialList| to an empty list. - For each credential C within the |credentialList| that has a non-empty |transports| list, optionally use only the specified transports to get assertions using credential C. - - If the above filtering process concludes that none of the credentials on the {{AssertionOptions/allowList}} can possibly + - If the above filtering process concludes that none of the credentials on the {{AssertionOptions/allowList}} can possibly be on this authenticator, do not perform any of the following steps for this authenticator, and proceed to the next authenticator (if any). - - Asynchronously invoke the authenticatorGetAssertion operation on this authenticator with |rpIdHash|, + - Asynchronously invoke the authenticatorGetAssertion operation on this authenticator with |rpId|, clientDataHash, |credentialList|, and |clientExtensions| as parameters. - Add an entry to |issuedRequests|, corresponding to this request. @@ -547,7 +551,7 @@ When this method is invoked, the user agent MUST execute the following algorithm - If any authenticator returns success: - Remove this authenticator's entry from |issuedRequests|. - Create a new {{AuthenticationAssertion}} object named |value| and populate its fields with the values returned from the - authenticator as well as the clientDataJSON computed earlier. + authenticator as well as the {{AuthenticationAssertion/clientDataJSON}} computed earlier. - For each remaining entry in |issuedRequests| invoke the authenticatorCancel operation on that authenticator and remove its entry from the list. - Resolve |promise| with |value| and terminate this algorithm. @@ -556,6 +560,7 @@ When this method is invoked, the user agent MUST execute the following algorithm During the above process, the user agent SHOULD show some UI to the user to guide them in the process of selecting and authorizing an authenticator with which to complete the operation. +
## Information about Scoped Credential (interface ScopedCredentialInfo) ## {#iface-credentialInfo} @@ -563,8 +568,8 @@ authorizing an authenticator with which to complete the operation. 
     [SecureContext]
     interface ScopedCredentialInfo {
-        readonly attribute ScopedCredential           credential;
-        readonly attribute AuthenticationAttestation  attestation;
+        readonly    attribute ArrayBuffer   clientDataJSON;
+        readonly    attribute ArrayBuffer   attestationObject;
     };
@@ -573,12 +578,16 @@ authorizing an authenticator with which to complete the operation. to locate it later for use, and also contains metadata that can be used by the [RP] to assess the strength of the credential during registration. - The credential attribute contains an object whose attributes state the type of, and identifier for, the - credential represented by {{ScopedCredentialInfo}}. + The clientDataJSON attribute contains the clientDataJSON (see [[#cred-attestation]]) + passed to the authenticator by the client in order to generate this credential. The exact JSON serialization must be + preserved as a cryptographic hash (clientDataHash) has been computed over it. - The attestation attribute contains an attestation statement returned by the authenticator. This provides - information about the credential and the authenticator it is held in, such as the credential public key and the level - of security assurance provided by the authenticator. + The attestationObject attribute contains an attestation object. The contents of this object are + determined by the attestation statement format used by the authenticator. This object is opaque to, and + cryptographically protected against tampering by, the client. It contains the credential's unique identifier, credential + public key, and attestation statement. It also contains any additional information that the [RP]'s server requires to + validate the attestation statement, as well as to decode and validate the bindings of both the client and authenticator + data. For more details, see [[#cred-attestation]]. @@ -602,8 +611,8 @@ authorizing an authenticator with which to complete the operation. The rpDisplayName member contains the friendly name of the [RP], such as "Acme Corporation", "Widgets Inc" or "Awesome Site". - The displayName member contains the friendly name associated with the user account by the [RP], such as "John P. - Smith". + The displayName member contains the friendly name associated with the user account by the [RP], such as "John + P. Smith". The id member contains an identifier for the account, specified by the [RP]. This is not meant to be displayed to the user. It is used by the [RP] to control the number of credentials - an authenticator will never contain more than one @@ -611,8 +620,8 @@ authorizing an authenticator with which to complete the operation. The name member contains a detailed name for the account, such as "john.p.smith@example.com". - The imageURL member contains a URL that resolves to the user's account image. This may be a URL that can be used - to retrieve an image containing the user's current avatar, or a data URI that contains the image data. + The imageURL member contains a URL that resolves to the user's account image. This may be a URL that can be + used to retrieve an image containing the user's current avatar, or a data URI that contains the image data. @@ -663,8 +672,8 @@ authorizing an authenticator with which to complete the operation. - The extensions parameter contains additional parameters requesting additional processing by the client and authenticator. For example, the caller may request that only authenticators with certain capabilities be used to create - the credential, or that additional information be returned in the attestation statement. Alternatively, the caller may - specify an additional message that they would like the authenticator to display to the user. Extensions are defined in + the credential, or that particular information be returned in the attestation object. The caller may also specify + an additional message that they would like the authenticator to display to the user. Extensions are defined in [[#extensions]]. - The attachment parameter contains authenticator attachment descriptions, which are used as an additional @@ -716,7 +725,7 @@ authorizing an authenticator with which to complete the operation. [SecureContext] interface AuthenticationAssertion { readonly attribute ScopedCredential credential; - readonly attribute ArrayBuffer clientData; + readonly attribute ArrayBuffer clientDataJSON; readonly attribute ArrayBuffer authenticatorData; readonly attribute ArrayBuffer signature; }; @@ -726,16 +735,16 @@ Scoped credentials produce a cryptographic signature that provides proof of poss user consent to a specific transaction. The structure of these signatures is defined as follows.
- The credential member represents the credential that was used to generate this assertion. + The credential attribute represents the credential that was used to generate this assertion. - The clientData member contains the parameters sent to the authenticator by the client, in serialized form. See - [[#sec-client-data]] for the format of this parameter and how it is generated. + The clientDataJSON attribute contains the parameters sent to the authenticator by the client, in serialized form. + See [[#sec-client-data]] for the format of this parameter and how it is generated. - The authenticatorData member contains the serialized data returned by the authenticator. See + The authenticatorData attribute contains the serialized data returned by the authenticator. See [[#sec-authenticator-data]]. - The signature member contains the raw signature returned from the authenticator. See - [[#authenticator-signature]]. + The signature attribute contains the raw signature returned from the authenticator. See + [[#op-get-assertion]].
@@ -759,8 +768,8 @@ user consent to a specific transaction. The structure of these signatures is def - The optional rpId parameter specifies the rpId claimed by the caller. If it is omitted, it will be assumed to be equal to the current settings object's origin. - - The optional allowList member contains a list of credentials acceptable to the caller, in order of the caller's - preference. + - The optional allowList member contains a list of credentials acceptable to the caller, in order of the + caller's preference. - The optional extensions parameter contains additional parameters requesting additional processing by the client and authenticator. For example, if transaction confirmation is sought from the user, then the prompt string would be @@ -783,45 +792,6 @@ If the caller wishes to pass extensions to the platform, it MUST do so by adding with the extension identifier as the key, and the extension's value as the value (see [[#extensions]] for details). -## Credential Attestation Structure (interface AuthenticationAttestation) ## {#iface-attestation} - -
-    [SecureContext]
-    interface AuthenticationAttestation {
-        readonly    attribute USVString     format;
-        readonly    attribute ArrayBuffer   clientData;
-        readonly    attribute ArrayBuffer   authenticatorData;
-        readonly    attribute any           attestation;
-    };
-
- -Authenticators must also provide some form of attestation. The basic requirement is that the authenticator can produce, for each -credential public key, attestation information that can be verified by a [RP]. Typically, this information -contains a signature by an attestation private key over the attested credential public key and a challenge, as well as a -certificate or similar information providing provenance information for the attestation public key, enabling a trust -decision to be made. However, if an attestation key pair is not available, then the authenticator MUST perform self -attestation of the credential public key with the corresponding credential private key. - -
- The format member specifies the format of attestation statement contained in this structure. Attestation formats - are defined in [[#attestation-formats]]. This specification supports a number of attestation formats, in - [[#defined-attestation-formats]]. Other attestation formats may be defined in later versions of this specification. - - The clientData member contains the clientDataJSON (see [[#signature-format]]). The exact JSON encoding - must be preserved as the hash (clientDataHash) has been computed over it. - - The authenticatorData member contains the serialized data returned by the authenticator. See - [[#sec-authenticator-data]]. - - The attestation element contains the actual attestation statement. The structure of this object - depends on the attestation format. For more details, see [[#cred-attestation-stmts]]. -
- -This attestation structure is delivered to the [RP] by the [RP]'s script running on the client, using methods outside -the scope of this specification. It contains all the information that the [RP]'s server requires to validate the statement, as -well as to decode and validate the bindings of both the client and authenticator data. - - ## Supporting Data Structures ## {#supporting-data-structures} The scoped credential type uses certain data structures that are specified in supporting specifications. These are as follows. @@ -845,12 +815,12 @@ string-valued keys. Values may be any type that has a valid encoding in JSON. It
The challenge member contains the base64url encoding of the challenge provided by the RP. - The origin member contains the fully qualified origin of the requester, as provided to the authenticator by + The origin member contains the fully qualified origin of the requester, as provided to the authenticator by the client, in the syntax defined by [[RFC6454]]. - The hashAlg member specifies the hash algorithm used to compute clientDataHash (see - [[#authenticator-signature]]). Use "S256" for SHA-256, "S384" for SHA384, "S512" for SHA512, and "SM3" for SM3 (see - [[#iana-considerations]]). This algorithm is chosen by the client at its sole discretion. + The hashAlg member specifies the hash algorithm used to compute clientDataHash. Use "S256" for SHA-256, + "S384" for SHA384, "S512" for SHA512, and "SM3" for SM3 (see [[#iana-considerations]]). This algorithm is chosen by the + client at its sole discretion. The tokenBinding member contains the base64url encoding of the Token Binding ID that this client uses for the Token Binding protocol when communicating with the [RP]. This can be omitted if no Token Binding has been negotiated between @@ -858,15 +828,18 @@ string-valued keys. Values may be any type that has a valid encoding in JSON. It The optional extensions member contains additional parameters generated by processing the extensions passed in by the [RP]. WebAuthn extensions are detailed in Section [[#extensions]]. -
-This structure is used by the client to compute the following quantities: + This structure is used by the client to compute the following quantities: -: clientDataJSON -:: This is the UTF-8 encoded JSON serialization [[RFC7159]] of a {{ClientData}} dictionary. + : clientDataJSON + :: This is the UTF-8 encoded JSON serialization [[RFC7159]] of a {{ClientData}} dictionary. Any valid JSON + serialization may be used by the client. This specification imposes no canonicalization requirements. Instead, the + {{ScopedCredentialInfo}} and {{AuthenticationAssertion}} structures contain the actual serializations used by the client + to generate them. -: clientDataHash -:: This is the hash (computed using hashAlg) of clientDataJSON. + : clientDataHash + :: This is the hash (computed using hashAlg) of clientDataJSON, as constructed by the client. + ### Credential Type enumeration (enum ScopedCredentialType) ### {#credentialType} @@ -879,7 +852,7 @@ This structure is used by the client to compute the following quantities:
This enumeration defines the valid credential types. It is an extension point; values may be added to it in the future, as - more credential types are defined. The values of this enumeration are used for versioning the WebAuthn assertion and + more credential types are defined. The values of this enumeration are used for versioning the Authentication Assertion and attestation structures according to the type of the authenticator. Currently one credential type is defined, namely "ScopedCred". @@ -927,9 +900,9 @@ the {{makeCredential()}} or {{getAssertion()}} method. It mirrors the fields of these methods.
- The type attribute contains the type of the credential the caller is referring to. + The type member contains the type of the credential the caller is referring to. - The id attribute contains the identifier of the credential that the caller is referring to. + The id member contains the identifier of the credential that the caller is referring to.
@@ -944,22 +917,16 @@ these methods.
- Authenticators may communicate with Clients using a variety of transports. - This enumeration defines a hint as to how Clients might communicate with a - particular Authenticator in order to obtain an assertion for a specific - credential. Note that these hints represent the [RP]'s best belief as to - how an Authenticator may be reached. A [RP] may obtain a list of - transports hints from some attestation formats or via some out-of-band - mechanism; it is outside the scope of this specification to define that - mechanism. + Authenticators may communicate with Clients using a variety of transports. This enumeration defines a hint as to how Clients + might communicate with a particular Authenticator in order to obtain an assertion for a specific credential. Note that + these hints represent the [RP]'s best belief as to how an Authenticator may be reached. A [RP] may obtain a list of + transports hints from some attestation statement formats or via some out-of-band mechanism; it is outside the scope of this + specification to define that mechanism.
@@ -973,16 +940,29 @@ defined in [[!WebCryptoAPI]]. # WebAuthn Authenticator model # {#authenticator-model} The API defined in this specification implies a specific abstract functional model for an authenticator. This section -describes the authenticator model. Client platforms may implement and expose this abstract model in any way desired. For -instance, this abstract model does not define specific error codes or methods of returning them; however, it does define error -behavior in terms of the needs of the client. Therefore, specific error codes are mentioned as a means of showing which error -conditions must be distinguishable (or not) from each other in order to enable a compliant and secure client implementation. -The overall requirement is that the behavior of the client's Web Authentication API implementation, when operating on the -authenticators supported by that platform, MUST be indistinguishable from the behavior specified in [[#api]]. - -In this abstract model, each authenticator stores some number of scoped credentials. Each scoped credential has an identifier -which is unique (or extremely unlikely to be duplicated) among all scoped credentials. Each credential is also associated with a -[RP], whose identity is represented by a Relying Party Identifier (RP ID). +describes the authenticator model. + +Client platforms may implement and expose this abstract model in any way desired. However, the behavior of the client's Web +Authentication API implementation, when operating on the authenticators supported by that platform, MUST be indistinguishable +from the behavior specified in [[#api]]. + +For authenticators, this model defines the logical operations that they must support, and the data formats that they expose to +the client and the [RP]. However, it does not define the details of how authenticators communicate with the client platform, +unless they are required for interoperability with [RPS]. For instance, this abstract model does not define protocols for +connecting authenticators to clients over transports such as USB or NFC. Similarly, this abstract model does not define specific +error codes or methods of returning them; however, it does define error behavior in terms of the needs of the client. Therefore, +specific error codes are mentioned as a means of showing which error conditions must be distinguishable (or not) from each other +in order to enable a compliant and secure client implementation. + +In this abstract model, the authenticator provides key management and cryptographic signatures. It may be embedded in the +WebAuthn client, or housed in a separate device entirely. The authenticator may itself contain a cryptographic module which +operates at a higher security level than the rest of the authenticator. This is particularly important for authenticators that +are embedded in the WebAuthn client, as in those cases this cryptographic module (which may, for example, be a TPM) could be +considered more trustworthy than the rest of the authenticator. + +Each authenticator stores some number of scoped credentials. Each scoped credential has an identifier which is unique (or +extremely unlikely to be duplicated) among all scoped credentials. Each credential is also associated with a [RP], whose +identity is represented by a Relying Party Identifier (RP ID). Each authenticator has an AAGUID, which is a 128-bit identifier that indicates the type (e.g. make and model) of the authenticator. The AAGUID MUST be chosen by the manufacturer to be identical across all substantially identical authenticators @@ -990,131 +970,14 @@ made by that manufacturer, and different (with probability 1-2-128 or authenticators. The RP MAY use the AAGUID to infer certain properties of the authenticator, such as certification level and strength of key protection, using information from other sources. - -## Authenticator operations ## {#authenticator-ops} - -A client must connect to an authenticator in order to invoke any of the operations of that authenticator. This connection -defines an authenticator session. An authenticator must maintain isolation between sessions. It may do this by only allowing one -session to exist at any particular time, or by providing more complicated session management. - -The following operations can be invoked by the client in an authenticator session. - - -### The authenticatorMakeCredential operation ### {#op-make-cred} - -This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following -input parameters: - -- The SHA-256 hash of the caller's RP ID, as determined by the user agent and the client. -- The clientDataHash, which is the hash of the serialized {{ClientData}} and is provided by the client. -- The {{Account}} information provided by the [RP]. -- The {{ScopedCredentialType}} and cryptographic parameters requested by the [RP], with the cryptographic algorithms normalized - as per the procedure in [[WebCryptoAPI#algorithm-normalization-normalize-an-algorithm]]. -- A list of {{ScopedCredential}} objects provided by the [RP] with the intention that, if any of these are known to the - authenticator, it should not create a new credential. -- Extension data created by the client based on the extensions requested by the [RP]. - -When this operation is invoked, the authenticator must perform the following procedure: -- Check if all the supplied parameters are syntactically well-formed and of the correct length. If not, return an error code - equivalent to UnknownError and terminate the operation. -- Check if at least one of the specified combinations of {{ScopedCredentialType}} and cryptographic parameters is supported. If - not, return an error code equivalent to NotSupportedError and terminate the operation. -- Check if a credential matching any of the supplied {{ScopedCredential}} identifiers is present on this authenticator. If so, - return an error code equivalent to NotAllowedError and terminate the operation. -- Prompt the user for consent to create a new credential. The prompt for obtaining this consent is shown by the authenticator - if it has its own output capability, or by the user agent otherwise. If the user denies consent, return an error code - equivalent to NotAllowedError and terminate the operation. -- Once user consent has been obtained, generate a new credential object: - - Generate a set of cryptographic keys using the most preferred combination of {{ScopedCredentialType}} and cryptographic - parameters supported by this authenticator. - - Generate an identifier for this credential, such that this identifier is globally unique with high probability across all - credentials with the same type across all authenticators. - - Associate the credential with the specified RP ID hash and the user's account identifier {{Account/id}}. - - Delete any older credentials with the same RP ID hash and {{Account/id}} that are stored locally in the authenticator. -- If any error occurred while creating the new credential object, return an error code equivalent to UnknownError and terminate - the operation. -- Process all the supported extensions requested by the client, and generate an attestation statement. If no authority key is - available to sign such an attestation statement, then the authenticator performs self attestation of the credential - with its own private key. For more details on attestation, see [[#cred-attestation-stmts]]. - -On successful completion of this operation, the authenticator must return the following to the client: -- The type and unique identifier of the new credential. -- The new credential public key. -- The fields of the attestation structure {{AuthenticationAttestation}}, including information about the attestation format used. - - -### The authenticatorGetAssertion operation ### {#op-get-assertion} - -This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following -input parameters: - -- The SHA-256 hash of the caller's RP ID, as determined by the user agent and the client. -- The clientDataHash, which is the hash of the serialized {{ClientData}} and is provided by the client. -- A list of credentials acceptable to the [RP] (possibly filtered by the client). -- Extension data created by the client based on the extensions requested by the [RP]. - -When this method is invoked, the authenticator must perform the following procedure: -- Check if all the supplied parameters are syntactically well-formed and of the correct length. If not, return an error code - equivalent to UnknownError and terminate the operation. -- If a list of credentials was supplied by the client, filter it by removing those credentials that are not present on this - authenticator. If no list was supplied, create a list with all credentials stored for the caller's RP ID (as determined by - an exact match of the RP ID hash). -- If the previous step resulted in an empty list, return an error code equivalent to NotAllowedError and terminate the - operation. -- Prompt the user to select a credential from among the above list. Obtain user consent for using this credential. The prompt - for obtaining this consent may be shown by the authenticator if it has its own output capability, or by the user agent - otherwise. -- Process all the supported extensions requested by the client, then generate a cryptographic signature using the private key of - the selected credential (as specified in [[#signature-format]]), and use it to construct an assertion. -- If any error occurred while generating the assertion, return an error code equivalent to UnknownError and terminate the - operation. - -On successful completion, the authenticator must return to the user agent: -- The identifier of the credential used to generate the signature. -- The authenticatorData used to generate the signature. -- The signature itself. - -If the authenticator cannot find any credential corresponding to the specified [RP] that matches the specified criteria, it -terminates the operation and returns an error. - -If the user refuses consent, the authenticator returns an appropriate error status to the client. - - -### The authenticatorCancel operation ### {#op-cancel} - -This operation takes no input parameters and returns no result. - -When this operation is invoked by the client in an authenticator session, it has the effect of terminating any -authenticatorMakeCredential or authenticatorGetAssertion operation currently in progress in that authenticator -session. The authenticator stops prompting for, or accepting, any user input related to authorizing the canceled operation. The -client ignores any further responses from the authenticator for the canceled operation. - -This operation is ignored if it is invoked in an authenticator session which does not have an authenticatorMakeCredential -or authenticatorGetAssertion operation currently in progress. - - -## Signature Format ## {#signature-format} - -WebAuthn signatures are bound to various contextual data. These data are observed, and added at different levels of the stack as -a signature request passes from the server to the authenticator. In verifying a signature, the server checks these bindings -against expected values. - -The components of a system using WebAuthn can be divided into three layers: - -1. The [RP] (RP), which uses the WebAuthn services. The RP consists of a server component and a web-application running - in a browser. - -2. The WebAuthn Client platform, which consists of the User Agent and the OS and device on which it executes. - -3. The Authenticator itself, which provides key management and cryptographic signatures. This may be embedded in the - WebAuthn client, or housed in a separate device entirely. In the latter case, the interface between the WebAuthn client and - the authenticator is a separately-defined protocol. The authenticator may itself contain a cryptographic module which - operates at a higher security level than the rest of the authenticator. This is particularly important for authenticators - that are embedded in the WebAuthn client, as in those cases this cryptographic module (which may, for example, be a TPM) - could be considered more trustworthy than the rest of the authenticator. - -This specification defines the common signature format shared by all the above layers. This includes how the different -contextual bindings are encoded, signed over, and delivered to the RP. +The primary function of the authenticator is to provide WebAuthn signatures, which are bound to various contextual data. These +data are observed, and added at different levels of the stack as a signature request passes from the server to the +authenticator. In verifying a signature, the server checks these bindings against expected values. These contextual bindings +are divided in two: Those added by the RP or the client, referred to as client data; and those added by the authenticator, +referred to as the authenticator data. The authenticator signs over the client data, but is otherwise not interested in its +contents. To save bandwidth and processing requirements on the authenticator, the client hashes the {{ClientData}} and sends +only the result to the authenticator. The authenticator signs over the combination of this clientDataHash, and its own +authenticator data. The goals of this design can be summarized as follows. @@ -1128,19 +991,28 @@ The goals of this design can be summarized as follows. - The design aims to reuse as much as possible of existing encoding formats in order to aid adoption and implementation. -The contextual bindings are divided in two: Those added by the RP or the client platform, referred to as client data; and those -added by the authenticator, referred to as the authenticator data. The client data must be signed over, but an authenticator is -otherwise not interested in its contents. To save bandwidth and processing requirements on the authenticator, the client -platform hashes the {{ClientData}} and sends only the result to the authenticator. The authenticator signs over the combination -of this clientDataHash, and its own authenticator data. +Authenticators produce cryptographic signatures for two distinct purposes: +1. An attestation signature is produced when a new credential is created, and provides cryptographic proof of certain + properties of the credential and the authenticator. For instance, an attestation signature asserts the type of authenticator + (as denoted by its AAGUID) and the public key of the credential. The attestation signature is signed by an attestation key, + which is chosen depending on the type of attestation desired. For more details on attestation, see [[#cred-attestation]]. +2. An assertion signature is produced when the authenticatorGetAssertion method is invoked. It represents an + assertion by the authenticator that the user has consented to a specific transaction, such as logging in, or completing a + purchase. Thus, an assertion signature asserts that the authenticator which possesses a particular credential private key + has established, to the best of its ability, that the human who is requesting this transaction is the same human who + consented to creating that particular credential. It also provides additional information that might be useful to the + caller, such as the means by which user consent was provided, and the prompt that was shown to the user by the + authenticator. + +The formats of these signatures, as well as the procedures for generating them, are specified below. -### Authenticator data ### {#sec-authenticator-data} +## Authenticator data ## {#sec-authenticator-data} -The authenticator data, authenticatorData, encodes contextual bindings made by the authenticator -itself. These bindings are controlled by the authenticator itself, and derive their trust from the [RP]'s assessment of the -security of the authenticator. In one extreme case, the authenticator may be embedded in the client, and its bindings may be no -more trustworthy than the {{ClientData}}. At the other extreme, the authenticator may be a discrete entity with high-security +The authenticator data structure, authenticatorData, encodes contextual bindings made by the authenticator. +These bindings are controlled by the authenticator itself, and derive their trust from the [RP]'s assessment of the security +properties of the authenticator. In one extreme case, the authenticator may be embedded in the client, and its bindings may be +no more trustworthy than the {{ClientData}}. At the other extreme, the authenticator may be a discrete entity with high-security hardware and software, connected to the client over a secure channel. In both cases, the [RP] receives the authenticator data in the same format, and uses its knowledge of the authenticator to make trust decisions. @@ -1177,8 +1049,8 @@ The encoding of authenticator data is a byte array of 37 bytes or more, as follo variable (if present) - Attestation data (if present). See [[#generating-an-attestation-statement]] for details. Its length n depends on the - length of the credential public key and credential ID being attested. + Attestation data (if present). See [[#sec-attestation-data]] for details. Its length depends on the length of the + credential public key and credential ID being attested. @@ -1190,14 +1062,11 @@ The encoding of authenticator data is a byte array of 37 bytes or more, as follo -The RP ID hash is originally received from the client when the credential is created, and again when an assertion is generated. +The RP ID is originally received from the client when the credential is created, and again when an assertion is generated. However, it differs from other client data in some important ways. First, unlike the client data, the RP ID of a credential does not change between operations but instead remains the same for the lifetime of that credential. Secondly, it is validated by the -authenticator during the authenticatorGetAssertion operation, by making sure that the RP ID hash associated with the -requested credential exactly matches the RP ID hash supplied by the client. These differences also explain why the RP ID hash is -always a SHA-256 hash instead of being crypto-agile like the clientDataHash; for a given RP ID, we need the hash to be -computed the same way by all clients for all operations so that authenticators can roam among clients without losing -interoperability. +authenticator during the authenticatorGetAssertion operation, by verifying that the RP ID associated with the requested +credential exactly matches the RP ID supplied by the client. The `TUP` flag SHALL be set if and only if the authenticator detected a user through an authenticator specific gesture. The `RFU` bits in the flags byte SHALL be set to zero. @@ -1208,9 +1077,9 @@ signatures, the AT flag MUST NOT be set and the attestation data MUST NOT be inc If the authenticator does not include any extension data, it MUST set the `ED` flag in the first byte to zero, and to one if extension data is included. -The figure below shows a visual representation of the authenticator data structure. +The [figure below](#fig-authData) shows a visual representation of the authenticator data structure. -
+
authenticatorData layout.
@@ -1220,109 +1089,240 @@ The attestation data (which is only present if the AT flag is set) describes its total length is 37 bytes plus the length of the attestation data, plus the length of the CBOR map that follows. -### Generating a signature ### {#authenticator-signature} +## Authenticator operations ## {#authenticator-ops} -A raw cryptographic signature must assert the integrity of both the client data and the authenticator data. Thus, an -authenticator SHALL compute a signature over the concatenation of the authenticatorData and the -clientDataHash. +A client must connect to an authenticator in order to invoke any of the operations of that authenticator. This connection +defines an authenticator session. An authenticator must maintain isolation between sessions. It may do this by only allowing one +session to exist at any particular time, or by providing more complicated session management. -
- -
Generating a signature on the authenticator.
-
+The following operations can be invoked by the client in an authenticator session. -A simple, undelimited concatenation is safe to use here because the authenticatorData describes its own length. The -clientDataHash (which potentially has a variable length) is always the last element. -The authenticator MUST return both the authenticatorData and the raw signature back to the client. The client, in turn, -MUST return clientDataJSON, authenticatorData and the signature to the RP. The first two are returned in the -`clientData` and `authenticatorData` members respectively of the {{AuthenticationAssertion}} and {{AuthenticationAttestation}} structures. +### The authenticatorMakeCredential operation ### {#op-make-cred} -### Verifying a signature ### {#authenticator-signature-verification} +This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following +input parameters: -This section specifies the algorithm for verifying a signature assertion. +- The caller's RP ID, as determined by the user agent and the client. +- The clientDataHash, which is the hash of the serialized {{ClientData}} and is provided by the client. +- The {{Account}} information provided by the [RP]. +- The {{ScopedCredentialType}} and cryptographic parameters requested by the [RP], with the cryptographic algorithms normalized + as per the procedure in [[WebCryptoAPI#algorithm-normalization-normalize-an-algorithm]]. +- A list of {{ScopedCredential}} objects provided by the [RP] with the intention that, if any of these are known to the + authenticator, it should not create a new credential. +- Extension data created by the client based on the extensions requested by the [RP]. -Upon receiving a signature assertion in the form of a {{AuthenticationAssertion}} structure, the [RP] shall: +When this operation is invoked, the authenticator must perform the following procedure: +- Check if all the supplied parameters are syntactically well-formed and of the correct length. If not, return an error code + equivalent to UnknownError and terminate the operation. +- Check if at least one of the specified combinations of {{ScopedCredentialType}} and cryptographic parameters is supported. If + not, return an error code equivalent to NotSupportedError and terminate the operation. +- Check if a credential matching any of the supplied {{ScopedCredential}} identifiers is present on this authenticator. If so, + return an error code equivalent to NotAllowedError and terminate the operation. +- Prompt the user for consent to create a new credential. The prompt for obtaining this consent is shown by the authenticator + if it has its own output capability, or by the user agent otherwise. If the user denies consent, return an error code + equivalent to NotAllowedError and terminate the operation. +- Once user consent has been obtained, generate a new credential object: + - Generate a set of cryptographic keys using the most preferred combination of {{ScopedCredentialType}} and cryptographic + parameters supported by this authenticator. + - Generate an identifier for this credential, such that this identifier is globally unique with high probability across all + credentials with the same type across all authenticators. + - Associate the credential with the specified RP ID and the user's account identifier {{Account/id}}. + - Delete any older credentials with the same RP ID and {{Account/id}} that are stored locally in the authenticator. +- If any error occurred while creating the new credential object, return an error code equivalent to UnknownError and terminate + the operation. +- Process all the supported extensions requested by the client, and generate an authenticatorData structure with + attestation data as specified in [[#sec-authenticator-data]]. Use this authenticatorData and the + clientDataHash received from the client to create an attestation object for the new credential using the + procedure specified in [[#generating-an-attestation-object]]. For more details on attestation, see [[#cred-attestation]]. -1. Perform JSON decoding to extract the {{ClientData}} used for the assertion from the {{AuthenticationAssertion/clientData}}. +On successful completion of this operation, the authenticator returns the attestation object to the client. -2. Verify that the {{ClientData/challenge}} in the {{ClientData}} matches the challenge that was sent to the authenticator. -3. Verify that the {{ClientData/origin}} in the {{ClientData}} matches the [RP]'s origin. +### The authenticatorGetAssertion operation ### {#op-get-assertion} -4. Verify that the {{ClientData/tokenBinding}} (if present) in the {{ClientData}} matches the token - binding public key for the TLS connection - over which the attestation was obtained. +This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following +input parameters: -5. Verify that the {{ClientData/extensions}} in the {{ClientData}} is a proper subset of the extensions requested by the RP. +- The caller's RP ID, as determined by the user agent and the client. +- The clientDataHash, which is the hash of the serialized {{ClientData}} and is provided by the client. +- A list of credentials acceptable to the [RP] (possibly filtered by the client). +- Extension data created by the client based on the extensions requested by the [RP]. + +When this method is invoked, the authenticator must perform the following procedure: +- Check if all the supplied parameters are syntactically well-formed and of the correct length. If not, return an error code + equivalent to UnknownError and terminate the operation. +- If a list of credentials was supplied by the client, filter it by removing those credentials that are not present on this + authenticator. If no list was supplied, create a list with all credentials stored for the caller's RP ID (as determined by + an exact match of the RP ID). +- If the previous step resulted in an empty list, return an error code equivalent to NotAllowedError and terminate the + operation. +- Prompt the user to select a credential from among the above list. Obtain user consent for using this credential. The prompt + for obtaining this consent may be shown by the authenticator if it has its own output capability, or by the user agent + otherwise. +- Process all the supported extensions requested by the client, and generate an authenticatorData structure without + attestation data as specified in [[#sec-authenticator-data]]. Concatenate this authenticatorData with the + clientDataHash received from the client to generate an assertion signature using the private key of the selected + credential [as shown below](#fig-signature). A simple, undelimited concatenation is safe to use here because the + authenticatorData describes its own length. The clientDataHash (which potentially has a variable length) is + always the last element. +- If any error occurred while generating the assertion signature, return an error code equivalent to UnknownError and terminate + the operation. + +
+ +
Generating a signature on the authenticator.
+
+ +On successful completion, the authenticator returns to the user agent: +- The identifier of the credential used to generate the signature. +- The authenticatorData used to generate the signature. +- The assertion signature. + +If the authenticator cannot find any credential corresponding to the specified [RP] that matches the specified criteria, it +terminates the operation and returns an error. -6. Verify that the RP ID hash in the {{AuthenticationAssertion/authenticatorData}} is indeed the SHA-256 hash of the RP ID expected - by the RP. +If the user refuses consent, the authenticator returns an appropriate error status to the client. + + +### The authenticatorCancel operation ### {#op-cancel} + +This operation takes no input parameters and returns no result. -7. Compute the clientDataHash, i.e. hash of {{AuthenticationAssertion/clientData}}. +When this operation is invoked by the client in an authenticator session, it has the effect of terminating any +authenticatorMakeCredential or authenticatorGetAssertion operation currently in progress in that authenticator +session. The authenticator stops prompting for, or accepting, any user input related to authorizing the canceled operation. The +client ignores any further responses from the authenticator for the canceled operation. + +This operation is ignored if it is invoked in an authenticator session which does not have an authenticatorMakeCredential +or authenticatorGetAssertion operation currently in progress. -8. Look up the previously registered public key associated with the credential (see {{makeCredential()}}) and - verify the signature in {{AuthenticationAssertion/signature}} computed over the - binary concatenation of {{AuthenticationAssertion/authenticatorData}} and clientDataHash. -If all the above steps succeed, then the signature is valid, otherwise it is invalid. +## Credential Attestation ## {#cred-attestation} -## Credential Attestation Statements ## {#cred-attestation-stmts} +Authenticators must also provide some form of attestation. The basic requirement is that the authenticator can produce, for each +credential public key, attestation information that can be verified by a Relying Party. Typically, this information contains a +signature by an attestation private key over the attested credential public key and a challenge, as well as a certificate or +similar information providing provenance information for the attestation public key, enabling a trust decision to be made. +However, if an attestation key pair is not available, then the authenticator MUST perform self attestation of the credential +public key with the corresponding credential private key. All this information is returned by the authenticator any time a new +credential is generated, in the form of an attestation object. The relationship of authenticator data and the attestation +data, attestation object, and attestation statement data structures is illustrated in [the figure below](#fig-attStructs). + +
+ +
Relationship of authenticator data and attestation data structures.
+
-A credential attestation statement is a specific type of signed data object, containing statements about a credential itself and -the authenticator that created it. It is created using the process described in [[#signature-format]], with the important -difference that the signature is generated not using the private key associated with the credential but using the key of the -attesting authority (except for the case of self attestation). In order to correctly interpret an attestation statement, -a [RP] needs to understand two aspects of the attestation: +An important component of the attestation object is the credential attestation statement. This is a specific type of +signed data object, containing statements about a credential itself and the authenticator that created it. It contains an +attestation signature created using the key of the attesting authority (except for the case of self attestation, when it +is created using the private key associated with the credential). In order to correctly interpret an attestation statement, a +[RP] needs to understand two aspects of the attestation: -1. The attestation format is the manner in which the signature is represented and the various contextual bindings are - incorporated into the attestation statement by the authenticator. In other words, this defines the syntax of the - statement. Various existing devices and platforms (such as TPMs and the Android OS) have previously defined attestation - formats. This specification supports a variety of such formats in an extensible way, as defined in [[#attestation-formats]]. +1. The attestation statement format is the manner in which the signature is represented and the various contextual + bindings are incorporated into the attestation statement by the authenticator. In other words, this defines the + syntax of the statement. Various existing devices and platforms (such as TPMs and the Android OS) have previously defined + attestation statement formats. This specification supports a variety of such formats in an extensible way, as defined in + [[#attestation-formats]]. 2. The attestation type defines the semantics of the attestation statement and its underlying trust model. It defines - how a [RP] establishes trust in a particular attestation statement, after verifying that it is cryptographically valid. + how a [RP] establishes trust in a particular attestation statement, after verifying that it is cryptographically valid. This + specification supports a number of attestation types, as described in [[#sctn-attestation-types]]. -In general, there is no simple mapping between attestation formats and attestation types. For example the "packed" attestation -format defined in [[#packed-attestation]] can be used in conjunction with all attestation types, while other formats and types -have more limited applicability. +In general, there is no simple mapping between attestation statement formats and attestation types. For example the "packed" +attestation statement format defined in [[#packed-attestation]] can be used in conjunction with all attestation types, while +other formats and types have more limited applicability. The privacy, security and operational characteristics of attestation depend on: - The attestation type, which determines the trust model, -- The attestation format, which may constrain the strength of the attestation by limiting what can be expressed in an +- The attestation statement format, which may constrain the strength of the attestation by limiting what can be expressed in an attestation statement, and - The characteristics of the individual authenticator, such as its construction, whether part or all of it runs in a secure operating environment, and so on. -It is expected that most authenticators will support a small number of attestation types and formats, while [RPS] will decide -what attestation types are acceptable to them by policy. [RPS] will also need to understand the characteristics of the -authenticators that they trust, based on information they have about these authenticators. For example, the FIDO Metadata -Service [[FIDOMetadataService]] provides one way to access such information. +It is expected that most authenticators will support a small number of attestation types and attestation statement formats, +while [RPS] will decide what attestation types are acceptable to them by policy. [RPS] will also need to understand the +characteristics of the authenticators that they trust, based on information they have about these authenticators. For example, +the FIDO Metadata Service [[FIDOMetadataService]] provides one way to access such information. -### Attestation Formats ### {#attestation-formats} +### Attestation data ### {#sec-attestation-data} -As described above, an attestation format is a data format which represents a cryptographic signature by an authenticator over a -set of contextual bindings. Each attestation format is defined by the following attributes: +Attestation data is added to the authenticatorData when generating an attestation object for a given credential. +It has the following format: -- The name of the format, used to identify it in a {{AuthenticationAttestation}} structure. This MUST be an ASCII string, and MUST - NOT be an ASCII case-insensitive match for the name of any other attestation format. + + + + + + + + + + + + + + + + + + + + + +
Length (in bytes)Description
16The AAGUID of the authenticator.
2Byte length L of Credential ID
LCredential ID
variable + Credential public key encoded in CBOR format. This is a CBOR map defined by the following CDDL rules: + + ``` + pubKey = $pubKeyFmt + + ; All public key formats must include an alg name + pubKeyTemplate = { alg: text } + pubKeyTemplate .within $pubKeyFmt + + pubKeyFmt /= rsaPubKey + rsaPubKey = { alg: rsaAlgName, n: biguint, e: uint } + rsaAlgName = "RS256" / "RS384" / "RS512" / "PS256" / "PS384" / "PS512" + + pubKeyFmt /= eccPubKey + eccPubKey = { alg: eccAlgName, x: biguint, y: biguint } + eccAlgName = "ES256" / "ES384" / "ES512" + ``` + + Thus, each public key type is a CBOR map starting with an entry named `alg`, which contains a text string that + specifies the name of the signature algorithm associated with the credential private key, using values defined in + [[!RFC7518]] section 3.1. The semantics and naming of the other fields (though not their encoding) follows the + definitions in [[!RFC7518]] section 6. Specifically, for ECC keys, the semantics of the `x` and `y` fields are + defined in [[!RFC7518]] sections 6.2.1.2 and 6.2.1.3, while for RSA keys, the semantics of the `n` and `e` fields + are defined in [[!RFC7518]] sections 6.3.1.1 and 6.3.1.2. +
-- The set of attestation types supported by the format. -- The syntax of an attestation statement produced in this format. +### Attestation Statement Formats ### {#attestation-formats} + +As described above, an attestation statement format is a data format which represents a cryptographic signature by an +authenticator over a set of contextual bindings. Each attestation statement format is defined by the following attributes: -- The procedure for computing an attestation statement in this format given the attToBeSigned for the attestation, - created as per [[#generating-an-attestation-statement]]. +- Its attestation statement format identifier. -- The procedure for verifying an attestation statement, takes the following inputs: - - The authenticator data claimed to have been used for the attestation, - - The clientDataHash of the client's contextual bindings, - - A trust anchor (a root certificate, a DAA root key, or the credential public key itself), +- The set of attestation types supported by the format. + +- The syntax of an attestation statement produced in this format, defined using CDDL for the extension point `$attStmtFormat` + defined in [[#generating-an-attestation-object]]. + +- The procedure for computing an attestation statement in this format given the credential to be attested, the + authenticatorData for the attestation, and a clientDataHash. - and returns a Boolean value indicating whether the attestation is cryptographically valid, and if so the attestation type. +- The procedure for verifying an attestation statement, which takes as inputs the authenticatorData claimed to have been + used for the attestation and the clientDataHash of the client's contextual bindings, and returns either: + - An error indicating that the attestation is invalid, or + - The attestation type, and the trust path of the attestation. This trust path is either empty (in case of + self-attestation), a DAA root key (in the case of Direct Anonymous Attestation), or a set of X.509 certificates. -The initial list of supported formats is in [[#defined-attestation-formats]]. +The initial list of supported attestation statement formats is in [[#defined-attestation-formats]].