Skip to content

Commit

Permalink
Create a combined interface for authenticator responses.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikewest
mikewest committed Mar 16, 2017
1 parent 3b5138d commit 6c38d02
Showing 1 changed file with 92 additions and 78 deletions.
170 changes: 92 additions & 78 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
verification=].

: <dfn>Authentication Assertion</dfn>
:: The cryptographically signed {{AuthenticationAssertion}} object returned by an [=authenticator=] as the result of a
:: The cryptographically signed {{AuthenticatorAssertionResponse}} object returned by an [=authenticator=] as the result of a
[=authenticatorGetAssertion=] operation.

: <dfn>Authenticator</dfn>
Expand Down Expand Up @@ -372,14 +372,14 @@ The Web Authentication API is defined by the union of the Web IDL fragments pres
<xmp class="idl">
[SecureContext]
interface WebAuthentication {
Promise<ScopedCredentialInfo> makeCredential(
Promise<AuthenticatorAttestationResponse> makeCredential(
Account accountInformation,
sequence<ScopedCredentialParameters> cryptoParameters,
BufferSource attestationChallenge,
optional ScopedCredentialOptions options
);

Promise<AuthenticationAssertion> getAssertion(
Promise<AuthenticatorAssertionResponse> getAssertion(
BufferSource assertionChallenge,
optional AssertionOptions options
);
Expand All @@ -394,7 +394,7 @@ This interface has two methods, which are described in the following subsections
<div link-for-hint="WebAuthentication/makeCredential(accountInformation, cryptoParameters, attestationChallenge, options)">
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
approve this operation. On success, the promise will be resolved with a {{AuthenticatorAttestationResponse}} object describing the newly
created credential.

<div class="note">
Expand Down Expand Up @@ -531,10 +531,10 @@ When this method is invoked, the user agent MUST execute the following algorithm
<dt>If any |authenticator| indicates success,</dt>
<dd>
1. [=set/Remove=] |authenticator| from |issuedRequests|.
2. Using |global|, let |value| be a new {{ScopedCredentialInfo}} object whose fields are:
: {{ScopedCredentialInfo/clientDataJSON}}
2. Using |global|, let |value| be a new {{AuthenticatorAttestationResponse}} object whose fields are:
: {{AuthenticatorResponse/clientDataJSON}}
:: A new {{ArrayBuffer}} containing the bytes of |clientDataJSON|.
: {{ScopedCredentialInfo/attestationObject}}
: {{AuthenticatorAttestationResponse/attestationObject}}
:: A new {{ArrayBuffer}} containing the bytes of the value returned from the successful
[=authenticatorMakeCredential=] operation
3. [=set/For each=] remaining |authenticator| in |issuedRequests| invoke the [=authenticatorCancel=] operation on
Expand Down Expand Up @@ -670,18 +670,18 @@ When this method is invoked, the user agent MUST execute the following algorithm
<dt>If any |authenticator| indicates success,</dt>
<dd>
1. [=set/Remove=] |authenticator| from |issuedRequests|.
2. Using |global|, let |value| be a new {{AuthenticationAssertion}} object whose fields are:
: {{AuthenticationAssertion/credential}}
2. Using |global|, let |value| be a new {{AuthenticatorAssertionResponse}} object whose fields are:
: {{AuthenticatorAssertionResponse/credential}}
:: A new {{ScopedCredential}} object whose fields are:
1. {{ScopedCredential/type}} whose value is the {{ScopedCredentialType}} representing this [=scoped
credential=]'s type.
1. {{ScopedCredential/id}} whose value is a new {{ArrayBuffer}} containing the bytes of the credential ID
returned from the successful [=authenticatorGetAssertion=] operation.
: {{AuthenticationAssertion/clientDataJSON}}
: {{AuthenticatorResponse/clientDataJSON}}
:: A new {{ArrayBuffer}} containing the bytes of |clientDataJSON|
: {{AuthenticationAssertion/authenticatorData}}
: {{AuthenticatorAssertionResponse/authenticatorData}}
:: A new {{ArrayBuffer}} containing the bytes of the returned {{authenticatorData}}
: {{AuthenticationAssertion/signature}}
: {{AuthenticatorAssertionResponse/signature}}
:: A new {{ArrayBuffer}} containing the bytes of the returned {{signature}}
3. [=set/For each=] remaining |authenticator| in |issuedRequests| invoke the [=authenticatorCancel=] operation on
|authenticator| and [=set/remove=] it from |issuedRequests|.
Expand All @@ -695,34 +695,78 @@ During the above process, the user agent SHOULD show some UI to the user to guid
authorizing an authenticator with which to complete the operation.
</div>

### <dfn interface>AuthenticatorResponse</dfn> interfaces ### {#iface-authenticatorresponse}

## Information about Scoped Credential (interface <dfn interface>ScopedCredentialInfo</dfn>) ## {#iface-credentialInfo}
The {{AuthenticatorResponse}} interface and its derieved interfaces represent the data

<pre class="idl">
[SecureContext]
interface ScopedCredentialInfo {
readonly attribute ArrayBuffer clientDataJSON;
readonly attribute ArrayBuffer attestationObject;
};
</pre>
<xmp class="idl">
[SecureContext]
interface AuthenticatorResponse {
readonly attribute ArrayBuffer clientDataJSON;
};
</xmp>
<dl dfn-for="AuthenticatorResponse">
: <dfn attribute>clientDataJSON</dfn>
:: This attribute contains a representation of the data sent from the client to the authenticator in order to generate
a given response. The {{AuthenticatorAttestationResponse}} and {{AuthenticatorAssertionResponse}}
</dl>

<div dfn-type="attribute" dfn-for="ScopedCredentialInfo">
This interface represents a newly-created scoped credential. It contains information about the credential that can be used
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 <dfn>clientDataJSON</dfn> attribute contains the [=JSON-serialized client data=] (see [[#cred-attestation]]) passed to
the authenticator by the client in order to generate this credential. The exact JSON serialization must be preserved as the
[=hash of the serialized client data=] has been computed over it.

The <dfn>attestationObject</dfn> 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]].
</div>
#### <dfn interface>AuthenticatorAttestationResponse</dfn> interface ### {#iface-authenticatorattestationresponse}

This interface contains the [=authenticator=]'s response to a client's request to created a new scoped credential. It contains
information about the credential that can be used 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.

<xmp class="idl">
[SecureContext]
interface AuthenticatorAttestationResponse : AuthenticatorResponse {
readonly attribute ArrayBuffer attestationObject;
};
</xmp>
<dl dfn-for="AuthenticatorAttestationResponse">
: {{AuthenticatorResponse/clientDataJSON}}
:: Here, this attribute contains the [=JSON-serialized client data=] (see [[#cred-attestation]]) passed to the
authenticator by the client in order to generate this credential. The exact JSON serialization must be preserved
as the [=hash of the serialized client data=] has been computed over it.

: <dfn attribute>attestationObject</dfn>
:: This 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]].
</dl>

#### <dfn interface>AuthenticatorAssertionResponse</dfn> interface ### {#iface-authenticatorassertionresponse}

The {{AuthenticatorAttestationResponse}} interface contains the [=authenticator=]'s response to a client's request to

Scoped credentials produce a cryptographic signature that provides proof of possession of a private key as well as
evidence of user consent to a specific transaction. The structure of these signatures is defined as follows:

<xmp class="idl">
[SecureContext]
interface AuthenticatorAssertionResponse : AuthenticatorResponse {
readonly attribute ScopedCredential credential;
readonly attribute ArrayBuffer authenticatorData;
readonly attribute ArrayBuffer signature;
};
</xmp>
<dl dfn-for="AuthenticatorAssertionResponse">
: {{AuthenticatorResponse/clientDataJSON}}
:: Here, this 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.

: <dfn attribute>credential</dfn>
:: This attribute represents the credential that was used to generate this assertion.

: <dfn attribute>authenticatorData</dfn>
:: This attribute contains the [=authenticator data=] returned by the authenticator. See [[#sec-authenticator-data]].

: <dfn attribute>signature</dfn>
:: This attribute contains the raw signature returned from the authenticator. See [[#op-get-assertion]].
</dl>

## User Account Information (dictionary <dfn dictionary>Account</dfn>) ## {#iface-account}

Expand Down Expand Up @@ -849,36 +893,6 @@ a minimum of friction, e.g., the user will not have to dig around in their pocke
example of the latter, when the user is accessing the [RP] from a given client for the first time, they may be required to
use a [=roaming authenticator=] which was originally registered with the [RP] using a different client.


## Web Authentication Assertion (interface <dfn interface>AuthenticationAssertion</dfn>) ## {#iface-assertion}

<pre class="idl">
[SecureContext]
interface AuthenticationAssertion {
readonly attribute ScopedCredential credential;
readonly attribute ArrayBuffer clientDataJSON;
readonly attribute ArrayBuffer authenticatorData;
readonly attribute ArrayBuffer signature;
};
</pre>

Scoped credentials produce a cryptographic signature that provides proof of possession of a private key as well as evidence of
user consent to a specific transaction. The structure of these signatures is defined as follows.

<div dfn-type="attribute" dfn-for="AuthenticationAssertion">
The <dfn>credential</dfn> attribute represents the credential that was used to generate this assertion.

The <dfn>clientDataJSON</dfn> 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 <dfn>authenticatorData</dfn> attribute contains the [=authenticator data=] returned by the authenticator. See
[[#sec-authenticator-data]].

The <dfn>signature</dfn> attribute contains the raw signature returned from the authenticator. See
[[#op-get-assertion]].
</div>


## Additional options for Assertion Generation (dictionary <dfn dictionary>AssertionOptions</dfn>) ## {#assertion-options}

<xmp class="idl">
Expand Down Expand Up @@ -965,7 +979,7 @@ following Web IDL.

: <dfn dfn>JSON-serialized client data</dfn>
:: This is the [=UTF-8 encoding=] of the result of calling the initial value of {{JSON/stringify|JSON.stringify}} on a
{{ClientData}} dictionary. To avoid ambiguity, the {{ScopedCredentialInfo}} and {{AuthenticationAssertion}} structures
{{ClientData}} dictionary. To avoid ambiguity, the {{AuthenticatorAttestationResponse}} and {{AuthenticatorAssertionResponse}} structures
contain the actual serializations used by the client to generate them.

: <dfn dfn>Hash of the serialized client data</dfn>
Expand Down Expand Up @@ -1594,17 +1608,17 @@ should be specified in the attestation certificate itself, so that it can be ver
# [RP] Operations # {#rp-operations}

Upon successful execution of a {{makeCredential()}} or {{getAssertion()}} call, the [RP]'s script receives a
{{ScopedCredentialInfo}} or {{AuthenticationAssertion}} structure respectively from the client. It must then deliver the
{{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}} structure respectively from the client. It must then deliver the
contents of this structure to the [=[RP]=], using methods outside the scope of this specification. This section describes the
operations that the [RP] must perform upon receipt of these structures.


## Registering a new credential ## {#registering-a-new-credential}

When requested to register a new credential, represented by a {{ScopedCredentialInfo}} structure, as part of a registration
When requested to register a new credential, represented by a {{AuthenticatorAttestationResponse}} structure, as part of a registration
ceremony, a [RP] MUST proceed as follows:

1. Perform JSON deserialization on the {{ScopedCredentialInfo/clientDataJSON}} field of the {{ScopedCredentialInfo}} object to
1. Perform JSON deserialization on the {{AuthenticatorResponse/clientDataJSON}} field of the {{AuthenticatorAttestationResponse}} object to
extract the [=client data=] |C| claimed to have been used for the credential's attestation.

2. Verify that the {{ClientData/challenge}} in |C| matches the challenge that was sent to the authenticator in the
Expand All @@ -1617,10 +1631,10 @@ ceremony, a [RP] MUST proceed as follows:

5. Verify that the {{ClientData/extensions}} in |C| is a proper subset of the extensions requested by the RP.

6. Compute the hash of {{ScopedCredentialInfo/clientDataJSON}} using the algorithm identified by
6. Compute the hash of {{AuthenticatorResponse/clientDataJSON}} using the algorithm identified by
<code>|C|.{{ClientData/hashAlg}}</code>.

7. Perform CBOR decoding on the {{ScopedCredentialInfo/attestationObject}} field of the {{ScopedCredentialInfo}} structure to
7. Perform CBOR decoding on the {{AuthenticatorAttestationResponse/attestationObject}} field of the {{AuthenticatorAttestationResponse}} structure to
obtain the attestation statement format |fmt|, the [=authenticator data=] |authData|, and the attestation statement
|attStmt|.

Expand Down Expand Up @@ -1672,15 +1686,15 @@ or it MAY decide to accept the registration, e.g. while deleting the older regis

## Verifying an authentication assertion ## {#verifying-assertion}

When requested to authenticate a given {{AuthenticationAssertion}} structure as part of an authentication ceremony, the [RP]
When requested to authenticate a given {{AuthenticatorAssertionResponse}} structure as part of an authentication ceremony, the [RP]
MUST proceed as follows:

1. Using the {{ScopedCredential/id}} attribute contained in the {{AuthenticationAssertion/credential}} attribute of the given
{{AuthenticationAssertion}} structure, look up the corresponding credential public key.
1. Using the {{ScopedCredential/id}} attribute contained in the {{AuthenticatorAssertionResponse/credential}} attribute of the given
{{AuthenticatorAssertionResponse}} structure, look up the corresponding credential public key.

2. Let |cData|, |aData| and |sig| denote the {{AuthenticationAssertion/clientDataJSON}},
{{AuthenticationAssertion/authenticatorData}} and {{AuthenticationAssertion/signature}} attributes of the given
{{AuthenticationAssertion}} structure, respectively.
2. Let |cData|, |aData| and |sig| denote the {{AuthenticatorResponse/clientDataJSON}},
{{AuthenticatorAssertionResponse/authenticatorData}} and {{AuthenticatorAssertionResponse/signature}} attributes of the given
{{AuthenticatorAssertionResponse}} structure, respectively.

3. Perform JSON deserialization on |cData| to extract the [=client data=] |C| used for the signature.

Expand Down

0 comments on commit 6c38d02

Please sign in to comment.