Skip to content

Commit

Permalink
merge from master & resolve conflicts
Browse files Browse the repository at this point in the history
  • Loading branch information
JeffH authored and JeffH committed Nov 3, 2017
2 parents 1a606eb + 625bd7a commit e645370
Showing 1 changed file with 98 additions and 31 deletions.
129 changes: 98 additions & 31 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
: <dfn>Attestation</dfn>
:: Generally, <em>attestation</em> is a statement serving to bear witness, confirm, or authenticate.
In the WebAuthn context, [=attestation=] is employed to <em>attest</em> to the <em>provenance</em> of an [=authenticator=]
and the data it emits; including, for example: credential IDs, [=credential key pairs=], signature counters, etc. An
and the data it emits; including, for example: [=credential IDs=], [=credential key pairs=], signature counters, etc. An
[=attestation statement=] is conveyed in an [=attestation object=] during [=registration=]. See also [[#sctn-attestation]]
and [Figure 3](#fig-attStructs).

Expand All @@ -300,6 +300,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
:: The cryptographically signed {{AuthenticatorAssertionResponse}} object returned by an [=authenticator=] as the result of a
[=authenticatorGetAssertion=] operation.

This corresponds to the [[CREDENTIAL-MANAGEMENT-1]] specification's single-use <a
spec="credential-management">credentials</a>.

: <dfn>Authenticator</dfn>
:: A cryptographic entity used by a [=[WAC]=] to (i) generate a [=public key credential=] and register it with a [=[RP]=],
and (ii) [=authentication|authenticate=] by potentially [=user verification|verifying the user=], and then
Expand Down Expand Up @@ -342,13 +345,70 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
:: 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]=].

: <dfn>Credential ID</dfn>
:: A probabilistically-unique [=byte sequence=] identifying a [=public key credential source=] and its [=authentication assertions=].

Credential IDs are generated by [=authenticators=] in two forms:
1. At least 16 bytes that include at least 100 bits of entropy, or
1. The [=public key credential source=], without its [=Credential ID=], encrypted so only its [=managing authenticator=] can
decrypt it. This form allows the [=authenticator=] to be nearly stateless, by having the [=[RP]=] store any necessary
state.

Note: [[FIDO-UAF-AUTHNR-CMDS]] includes guidance on encryption techniques under "Security Guidelines".

[=[RPS]=] do not need to distinguish these two [=Credential ID=] forms.

: <dfn>Credential Public Key</dfn>
:: The public key portion of an [=[RP]=]-specific <dfn>credential key pair</dfn>, generated by an [=authenticator=] and
returned to an [=[RP]=] at [=registration=] time (see also [=public key credential=]). The private key portion of the
[=credential key pair=] is known as the <dfn>credential private key</dfn>. Note that in the case of [=self
attestation=], the [=credential key pair=] is also used as the [=attestation key pair=], see [=self attestation=]
for details.

: <dfn>Public Key Credential Source</dfn>
:: A [=credential source=] ([[CREDENTIAL-MANAGEMENT-1]]) used by an [=authenticator=] to generate [=authentication assertions=]. A public key credential source has:

* A [=Credential ID=].
* A [=credential private key=].
* The [=Relying Party Identifier=] for the [=[RP]=] that created this credential source.
* An optional [=user handle=] for the person who created this credential source.
* Optional other information used by the authenticator to inform its UI. For example, this might include the user's
{{displayName}}.

The [=authenticatorMakeCredential=] operation creates a [=public key credential source=] bound to a <dfn for="public key
credential source">managing authenticator</dfn> and returns the [=credential public key=] associated with its [=credential
private key=]. The [=[RP]=] can use this [=credential public key=] to verify the [=authentication assertions=] created by
this [=public key credential source=].

: <dfn>Public Key Credential</dfn>

:: Generically, a *credential* is data one entity presents to another in order to *authenticate* the former to the latter
[[RFC4949]]. The term [=public key credential=] refers to one of: a [=public key credential source=], the
possibly-[=attestation|attested=] [=credential public key=] corresponding to a [=public key credential source=], or an
[=authentication assertion=]. Which one is generally determined by context.

<div class="note">
Note: This is a [=willful violation=] of [[RFC4949]]. In English, a "credential" is both a) the thing presented to prove
a statement and b) intended to be used multiple times. It's impossible to achieve both criteria securely with a single
piece of data in a public key system. [[RFC4949]] chooses to define a credential as the thing that can be used multiple
times (the public key), while this specification gives "credential" the English term's flexibility. This specification
uses more specific terms to identify the data related to an [[RFC4949]] credential:

: "Authentication information" (possibly including a private key)
:: [=Public key credential source=]
: "Signed value"
:: [=Authentication assertion=]
: [[RFC4949]] "credential"
:: [=Credential public key=] or [=attestation object=]
</div>

At [=registration=] time, the [=authenticator=] creates an asymmetric key pair, and stores its [=credential private
key|private key portion=] and information from the [=[RP]=] into a [=public key credential source=]. The [=credential public
key|public key portion=] is returned to the [=[RP]=], who then stores it in conjunction with the present user's account.
Subsequently, only that [=[RP]=], as identified by its [=RP ID=], is able to employ the [=public key credential=] in
[=authentication|authentication ceremonies=], via the {{CredentialsContainer/get()}} method. The [=[RP]=] uses its stored
copy of the [=credential public key=] to verify the resultant [=authentication assertion=].

: <dfn>Rate Limiting</dfn>
:: The process (also known as throttling) by which an authenticator implements controls against brute force attacks by limiting
the number of consecutive failed authentication attempts within a given period of time. If the limit is reached, the
Expand Down Expand Up @@ -391,17 +451,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
[=document.domain=]'s setter provides.
</div>

: <dfn>Public Key Credential</dfn>
:: Generically, a <em>credential</em> is data one entity presents to another in order to <em>authenticate</em> the former to the
latter [[RFC4949]]. A WebAuthn <em>[=public key credential=]</em> is a <code>{ identifier, type }</code> 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 [=credential public key|public key portion=] is
returned to the [=[RP]=], who then stores it in conjunction with the present user's account. The [=authenticator=] maps the
[=credential private key|private key portion=] to the [=[RP]=]'s [=RP ID=] and stores it. Subsequently, only that [=[RP]=],
as identified by its [=RP ID=], is able to employ the [=public key credential=] in [=authentication|authentication
ceremonies=], via the {{CredentialsContainer/get()}} method. The [=[RP]=] uses its stored copy of the [=credential public
key=] to verify the resultant [=authentication assertion=].

: <dfn>Test of User Presence</dfn>
:: A [=test of user presence=] is a simple form of [=authorization gesture=] and technical process where a user interacts with
an [=authenticator=] by (typically) simply touching it (other modalities may also exist), yielding a boolean result. Note
Expand Down Expand Up @@ -1022,7 +1071,7 @@ When this method is invoked, the user agent MUST execute the following algorithm
: <code><dfn for="assertionCreationData">credentialIdResult</code>
:: If |savedCredentialId| exists, set the value of [=credentialIdResult=] to be the bytes of
|savedCredentialId|. Otherwise, set the value of [=credentialIdResult=] to be the bytes of the
credential ID returned from the successful [=authenticatorGetAssertion=] operation, as defined in
[=credential ID=] returned from the successful [=authenticatorGetAssertion=] operation, as defined in
[[#op-get-assertion]].
: <code><dfn for="assertionCreationData">clientDataJSONResult</dfn></code>
Expand Down Expand Up @@ -1188,7 +1237,7 @@ during registration.
: <dfn>attestationObject</dfn>
:: This attribute contains an [=attestation object=], which is opaque to, and cryptographically protected against
tampering by, the client. The [=attestation object=] contains both [=authenticator data=] and an [=attestation
statement=]. The former contains the AAGUID, a unique credential ID, and the [=credential public key=]. The
statement=]. The former contains the AAGUID, a unique [=credential ID=], and the [=credential public key=]. The
contents of the [=attestation statement=] are determined by the [=attestation statement format=] used by the
[=authenticator=]. 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 [=authenticator data=] along with the
Expand Down Expand Up @@ -1332,11 +1381,15 @@ associated.
<div dfn-type="dict-member" dfn-for="PublicKeyCredentialEntity">
: <dfn>name</dfn>
:: A human-friendly identifier for the entity. For example, this could be a company name for a [=[RP]=], or a
user's name. This identifier is intended for display.
user's name. This identifier is intended for display. [=Authenticators=] MUST accept and store a 64 byte minimum length
for a name members's value. Authenticators MAY truncate a
name member's value to a length equal to or greater than 64 bytes.

: <dfn>icon</dfn>
:: A [=URL serializer|serialized=] URL which resolves to an image associated with the entity. For example, this could be
a user's avatar or a [=[RP]=]'s logo. This URL MUST be an [=a priori authenticated URL=].
a user's avatar or a [=[RP]=]'s logo. This URL MUST be an [=a priori authenticated URL=]. [=Authenticators=] MUST
accept and store a 128 byte minimum length for a icon members's value.
Authenticators MAY ignore a icon members's value if its length is greater than 128 byes.
</div>


Expand Down Expand Up @@ -1373,7 +1426,9 @@ credential.
:: The [=user handle=] of the user account entity.

: <dfn>displayName</dfn>
:: A friendly name for the user account (e.g., "John P. Smith").
:: A friendly name for the user account (e.g., "John P. Smith"). [=Authenticators=] MUST accept and store a 64 byte minimum
length for a displayName members's value. Authenticators MAY truncate a
displayName member's value to a length equal to or greater than 64 bytes.
</div>


Expand Down Expand Up @@ -1862,8 +1917,11 @@ When this operation is invoked, the authenticator must perform the following pro
1. Check if at least one of the specified combinations of {{PublicKeyCredentialType}} and cryptographic parameters in
|credTypesAndPubKeyAlgs| is supported.
If not, return an error code equivalent to "{{NotSupportedError}}" and terminate the operation.
1. Check if a credential matching an [=list/item=] of |excludeCredentialDescriptorList| is present on this authenticator. If
so, return an error code equivalent to "{{NotAllowedError}}" and terminate the operation.
1. Check if any credential bound to this authenticator matches an [=list/item=] of |excludeCredentialDescriptorList|. A match
occurs if a credential matches <code>|rpEntity|.{{PublicKeyCredentialRpEntity/id}}</code> and an |excludeCredentialDescriptorList|
item's <code>|excludeCredentialDescriptorList|.{{PublicKeyCredentialDescriptor/id}}</code> and
<code>|excludeCredentialDescriptorList|.{{PublicKeyCredentialDescriptor/type}}</code>.
If so, return an error code equivalent to "{{NotAllowedError}}" and terminate the operation.
1. If |requireResidentKey| is |true| and the authenticator cannot store a [=Client-side-resident Credential
Private Key=], return an error code equivalent to "{{ConstraintError}}" and terminate the operation.
1. If |requireUserVerification| is |true| and the authenticator cannot perform user verification,
Expand Down Expand Up @@ -1929,7 +1987,9 @@ When this method is invoked, the [=authenticator=] must perform the following pr
equivalent to "{{UnknownError}}" and terminate the operation.
1. If |allowCredentialDescriptorList| was not supplied, set it to a list of all credentials stored for |rpId| (as determined by
an exact match of |rpId|).
1. Remove any items from |allowCredentialDescriptorList| that are not present on this [=authenticator=].
1. Remove any items from |allowCredentialDescriptorList| that do not match a credential bound to this authenticator. A match
occurs if a credential matches <code>|rpId|</code> and an |allowCredentialDescriptorList| item's <code>|allowCredentialDescriptorList|
{{PublicKeyCredentialDescriptor/id}}</code> and <code>|allowCredentialDescriptorList|{{PublicKeyCredentialDescriptor/type}}</code>.
1. If |allowCredentialDescriptorList| is now empty, return an error code equivalent to "{{NotAllowedError}}" and terminate the
operation.
1. Prompt the user to select a [=public key credential|credential=] |selectedCredential| from |allowCredentialDescriptorList|.
Expand Down Expand Up @@ -1959,12 +2019,12 @@ When this method is invoked, the [=authenticator=] must perform the following pr

<li id='authenticatorGetAssertion-return-values'>
Return to the user agent:
- |selectedCredential|'s credential ID, if either a list of credentials of length 2 or greater was supplied by the
- |selectedCredential|'s [=credential ID=], if either a list of credentials of length 2 or greater was supplied by the
client, or no such list was supplied. Otherwise, return only the below values.

Note: If the client supplies a list of exactly one credential and it was successfully employed, then its credential
ID is not returned since the client already knows it. This saves transmitting these bytes over what may be
a constrained connection in what is likely a common case.
Note: If the client supplies a list of exactly one credential and it was successfully employed, then its
[=credential ID=] is not returned since the client already knows it. This saves transmitting these bytes over
what may be a constrained connection in what is likely a common case.

- |authenticatorData|
- |signature|
Expand Down Expand Up @@ -2070,7 +2130,7 @@ object=] for a given credential. It has the following format:
<tr>
<td><dfn>credentialId</dfn></td>
<td>L</td>
<td>Credential ID</td>
<td>[=Credential ID=]</td>
</tr>
<tr>
<td><dfn>credentialPublicKey</dfn></td>
Expand Down Expand Up @@ -2321,7 +2381,7 @@ When registering a new credential, represented by a {{AuthenticatorAttestationRe
14. If the attestation statement |attStmt| successfully verified but is not trustworthy per step 12 above, the [=[RP]=] SHOULD fail
the registration ceremony.

NOTE: However, if permitted by policy, the [=[RP]=] MAY register the credential ID and credential public key but treat the
NOTE: However, if permitted by policy, the [=[RP]=] MAY register the [=credential ID=] and credential public key but treat the
credential as one with [=self attestation=] (see [[#sctn-attestation-types]]). If doing so, the [=[RP]=] is asserting there
is no cryptographic proof that the [=public key credential=] has been generated by a particular [=authenticator=] model.
See [[FIDOSecRef]] and [[UAFProtocol]] for a more detailed discussion.
Expand Down Expand Up @@ -2848,7 +2908,7 @@ This attestation statement format is used with FIDO U2F authenticators using the

Generate a Registration Response Message as specified in [[FIDO-U2F-Message-Formats]] section 4.3, with the application parameter set to the
SHA-256 hash of the [=RP ID=] associated with the given credential, the challenge parameter set to |tbsHash|, and the key handle
parameter set to the credential ID of the given credential. Set the raw signature part of this Registration Response Message (i.e., without the user public key,
parameter set to the [=credential ID=] of the given credential. Set the raw signature part of this Registration Response Message (i.e., without the user public key,
key handle, and attestation certificates) as |sig| and set the attestation certificates of
the attestation public key as |x5c|.

Expand Down Expand Up @@ -3630,7 +3690,7 @@ In this flow, the [=[RP]=] does not have a preference for [=platform authenticat
such as attestation regarding the provenance and characteristics of the authenticator.
- The server stores the [=credential public key=] in its database and associates it with the user as well as with the
characteristics of authentication indicated by attestation, also storing a friendly name for later use.
- The script may store data such as the credential ID in local storage, to improve future UX by narrowing the choice of
- The script may store data such as the [=credential ID=] in local storage, to improve future UX by narrowing the choice of
credential for the user.

The sample code for generating and registering a new key follows:
Expand Down Expand Up @@ -3753,10 +3813,10 @@ credential.

9. If an assertion was successfully generated and returned,
- The script sends the assertion to the server.
- The server examines the assertion, extracts the credential ID, looks up the registered
- The server examines the assertion, extracts the [=credential ID=], looks up the registered
credential public key it is database, and verifies the assertion's authentication signature.
If valid, it looks up the identity associated with the assertion's credential ID; that
identity is now authenticated. If the credential ID is not recognized by the server (e.g.,
If valid, it looks up the identity associated with the assertion's [=credential ID=]; that
identity is now authenticated. If the [=credential ID=] is not recognized by the server (e.g.,
it has been deregistered due to inactivity) then the authentication has failed; each [=[RP]=]
will handle this in its own way.
- The server now does whatever it would otherwise do upon successful authentication -- return a success page, set
Expand Down Expand Up @@ -3974,6 +4034,13 @@ Axel Nennker, Kimberly Paulhamus, Adam Powers, Yaron Sheffer, Mike West, Jeffrey
"status": "FIDO Alliance Review Draft"
},

"FIDO-UAF-AUTHNR-CMDS": {
"authors": ["R. Lindemann", "J. Kemp"],
"title": "FIDO UAF Authenticator Commands",
"href": "https://fidoalliance.org/specs/fido-uaf-v1.1-id-20170202/fido-uaf-authnr-cmds-v1.1-id-20170202.html",
"status": "FIDO Alliance Implementation Draft"
},

"CDDL": {
"authors": ["C. Vigano", "H. Birkholz"],
"title": "CBOR data definition language (CDDL): a notational convention to express CBOR data structures",
Expand Down

0 comments on commit e645370

Please sign in to comment.