diff --git a/img/fido-signature-formats-figure1.svg b/img/fido-signature-formats-figure1.svg index 39d528140..29b5d55bb 100644 --- a/img/fido-signature-formats-figure1.svg +++ b/img/fido-signature-formats-figure1.svg @@ -1,3 +1,3 @@ - - - Produced by OmniGraffle 6.2.5 2015-08-20 21:39:49 +0000authenticatorDataLayer 1FLAGS000000EDTUPCOUNTEREXTENSIONS1 byte4 bytes (big-endian uint32)variable length (CBOR)07 + + + Produced by OmniGraffle 6.2.5 2015-08-20 21:39:49 +0000authenticatorDataLayer 1RP ID hashFLAGS000000EDTUPCOUNTEREXTENSIONS32 bytes1 byte4 bytes (big-endian uint32)variable length (CBOR)07 diff --git a/index.bs b/index.bs index c5b895a5d..49939b7fe 100644 --- a/index.bs +++ b/index.bs @@ -391,7 +391,8 @@ When this method is invoked, the user agent MUST execute the following algorithm 3. Set |callerOrigin| to the origin of the caller. Derive the RP ID from |callerOrigin| by computing the "public suffix + 1" or "PS+1" (which is also referred to as the "Effective Top-Level Domain plus One" or "eTLD+1") - part of |callerOrigin| [[PSL]]. Set |rpId| to the RP ID. + part of |callerOrigin| [[PSL]]. Set |rpIdHash| to the SHA-256 hash of the UTF-8 encoding of the lowercase form of this RP + ID. 4. Initialize |issuedRequests| to an empty list. @@ -411,9 +412,9 @@ When this method is invoked, the user agent MUST execute the following algorithm produce the extension data that needs to be sent to the authenticator. Call this data |clientExtensions|. 8. For each authenticator currently available on this platform: asynchronously invoke the - authenticatorMakeCredential operation on that authenticator with |callerOrigin|, |rpId|, accountInformation, - `normalizedParameters`, excludeList, attestationChallenge and |clientExtensions| as parameters. Add a - corresponding entry to |issuedRequests|. + authenticatorMakeCredential operation on that authenticator with |callerOrigin|, |rpIdHash|, + accountInformation, `normalizedParameters`, excludeList, attestationChallenge and |clientExtensions| as + parameters. Add a corresponding entry to |issuedRequests|. 9. While |issuedRequests| is not empty, perform the following actions depending upon the |adjustedTimeout| timer and responses from the authenticators: @@ -459,7 +460,8 @@ When this method is invoked, the user agent MUST execute the following algorithm 3. Set |callerOrigin| to the origin of the caller. Derive the RP ID from |callerOrigin| by computing the "public suffix + 1" or "PS+1" (which is also referred to as the "Effective Top-Level Domain plus One" or "eTLD+1") - part of |callerOrigin| [[PSL]]. Set |rpId| to the RP ID. + part of |callerOrigin| [[PSL]]. Set |rpIdHash| to the SHA-256 hash of the UTF-8 encoding of the lowercase form of this RP + ID. 4. Initialize |issuedRequests| to an empty list. @@ -472,8 +474,8 @@ When this method is invoked, the user agent MUST execute the following algorithm and set |credentialList| to this filtered list. - If |credentialList| is empty, ignore this authenticator and do not perform any of the following per-authenticator steps. - - Asynchronously invoke the authenticatorGetAssertion operation on this authenticator with |callerOrigin|, |rpId|, - assertionChallenge, |credentialList|, and |clientExtensions| as parameters. + - Asynchronously invoke the authenticatorGetAssertion operation on this authenticator with |callerOrigin|, + |rpIdHash|, assertionChallenge, |credentialList|, and |clientExtensions| as parameters. - Add an entry to |issuedRequests|, corresponding to this request. 7. While |issuedRequests| is not empty, perform the following actions depending upon the |adjustedTimeout| timer and responses @@ -703,7 +705,7 @@ This operation must be invoked in an authenticator session which has no other op input parameters: - The web origin of the script on whose behalf the operation is being initiated, as determined by the user agent and the client. -- The RP ID corresponding to the above web origin, as determined by the user agent and the client. +- The SHA-256 hash of the RP ID corresponding to the above web origin, as determined by the user agent and the client. - The {{Account}} information provided by the [RP]. - The {{CredentialType}} requested by the [RP]. - The cryptographic parameters requested by the [RP], with the cryptographic algorithms normalized as per the procedure in @@ -717,11 +719,16 @@ When this operation is invoked, the authenticator obtains user consent for creat this consent is shown by the authenticator if it has its own output capability, or by the user agent otherwise. Once user consent is obtained, the authenticator generates the appropriate cryptographic keys and creates a new credential. It also generates an identifier for the credential, such that this identifier is globally unique with high probability across all -credentials with the same type across all authenticators. It then associates the credential with the specified RP ID such that -it will be able to retrieve the RP ID later, given the credential ID. +credentials with the same type across all authenticators. It then associates the credential with the specified RP ID hash such +that it will be able to retrieve the RP ID hash later, given the credential ID. Finally, it generates an attestation statement +that describes its own attributes as well as some attributes of the credential. For more details on attestation, see +[[#attestation]]. -On successful completion of this operation, the authenticator returns the type and unique identifier of this new credential to -the user agent. +On successful completion of this operation, the authenticator returns the following to the client: + +- The type and unique identifier of the new credential. +- The public key associated with the new credential. +- The attestation statement, including information about the attestation format used. If the user refuses consent, the authenticator returns an appropriate error status to the client. @@ -732,16 +739,22 @@ This operation must be invoked in an authenticator session which has no other op input parameters: - The web origin of the script on whose behalf the operation is being initiated, as determined by the user agent and the client. -- The RP ID corresponding to the above web origin, as determined by the user agent and the client. +- The RP ID hash corresponding to the above web origin, as determined by the user agent and the client. - A challenge provided by the [RP] to assure freshness of the assertion produced. - 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 allows the user to select a credential from among the credentials associated with -that [RP] and matching the specified criteria, then obtains user consent for using that 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. Once a -credential is selected and user consent is obtained, the authenticator computes a cryptographic signature using the credential's -private key and constructs an assertion as specified in [[#signature-format]]. It then returns this assertion to the user agent. +that [RP] (as determined by an exact match of the RP ID hash) and matching the specified criteria, then obtains user consent +for using that 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. Once a credential is selected and user consent is obtained, the authenticator +computes a cryptographic signature using the credential's private key and constructs an assertion signature as specified in +[[#signature-format]]. + +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 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. @@ -810,6 +823,7 @@ string-valued keys. Values may be any type that has a valid encoding in JSON. It dictionary ClientData { required DOMString challenge; required DOMString facet; + required DOMString rpId; required AlgorithmIdentifier hashAlg; JsonWebKey tokenBinding; WebAuthnExtensions extensions; @@ -822,6 +836,8 @@ string-valued keys. Values may be any type that has a valid encoding in JSON. It The facet member contains the fully qualified web origin of the requester, as provided to the authenticator by the client, in the syntax defined by [[RFC6454]]. + The rpId member contains the RP ID of the requester, as computed by the client. + 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]]). @@ -841,7 +857,7 @@ The authenticator data encodes contextual bindings made by the authenticator< but extensible encoding. This is desired since authenticators can be devices with limited capabilities and low power requirements, with much simpler software stacks than the client platform components. -The encoding of authenticator data is a byte array of 5 bytes or more, as follows. +The encoding of authenticator data is a byte array of 37 bytes or more, as follows. @@ -849,7 +865,13 @@ The encoding of authenticator data is a byte array of 5 bytes or more, as follow - + + + + + - + - +
Description
00-31 + SHA-256 hash of the RP ID associated with the credential. +
32 Flags (bit 0 is the least significant bit): - Bit 0: Test of User Presence (`TUP`) result. @@ -858,11 +880,11 @@ The encoding of authenticator data is a byte array of 5 bytes or more, as follow
1-433-36 Signature counter (`signCount`), 32-bit unsigned big-endian integer.
5-37- Extension-defined authenticator data. This is a CBOR [[RFC7049]] map with extension identifiers as keys, and extension authenticator data values as values. See [[#extensions]] for details. @@ -870,6 +892,15 @@ The encoding of authenticator data is a byte array of 5 bytes or more, as follow
+Note that the RP ID hash 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 move between clients without +losing interoperability. + 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. @@ -883,8 +914,8 @@ The figure below shows a visual representation of the authenticator data structu
authenticatorData layout.
-Note: The `signatureData` describes its own length: If the ED flag is not set, it is always 5 bytes long. If the ED flag is set, -it is 5 bytes plus the CBOR map that follows. +Note: The `authenticatorData` describes its own length: If the ED flag is not set, it is always 37 bytes long. If the ED flag is set, +it is 37 bytes plus the CBOR map that follows. ### Generating a signature ### {#authenticator-signature}