Skip to content

Commit

Permalink
build on Adding a choice for RP to express preferences for attestatio…
Browse files Browse the repository at this point in the history 
…n types (#693)

* Adding a choice for RP to express preferences for attestation types

Adding a choice for RP to express preferences for attestation types. "low-cost" means don't bother the user to get the attestation, don't do a network roundtrip, etc., even if that means that we won't end up with a meaningful attestation (i.e., even if we only get self-attestation). "verifiable" means that the RP wants a verifiable attestation, even if that means that the user agent needs to connect to the Privacy CA, collect user consent, wait for ECDAA signatures to finish, etc.

* Update index.bs

* Update index.bs

* Added a third option

And changed "low-cost" to "none".

* adding client processing rules...

...for the attestation preferences.

* typo

* typos

* PR 636: rename several items and remove prescriptive wording about UI.

* Addressing akshayku's comments on previous change.

* attestationPresentationPreference -> attestationConveyancePreference

* refine/polich switch stmt

* more refining

* refining AttestationConveyancePreference section

* polish AttestationConveyancePreference section, plus make BS happy

* add issue

* make BS happy

* polish

* need to define 'blinding'

* editorial polish

* fix up MakePublicKeyCredentialOptions.attestation description, remove line-ending blanks

* make BS happy - no comments in <pre> blocks, define attestation conveyance

* adapt commit 825cce7 language

* move attestation conveyance \<dfn>

* address jyasskin comments, thx!
  • Loading branch information
@equalsJeffH
equalsJeffH committed Nov 22, 2017
1 parent cc94364 commit 81fdc9a
Showing 1 changed file with 75 additions and 3 deletions.
78 changes: 75 additions & 3 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ Boilerplate: omit conformance, omit feedback-header, omit abstract-header
Markup Shorthands: css off, markdown on
</pre>

<!-- spec: HTML; urlPrefix: https://html.spec.whatwg.org/multipage/ -->
<!-- L89: Remove these once Shepherd picks up the changes -->



<pre class="anchors">

spec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#
Expand All @@ -75,7 +80,6 @@ spec: TokenBinding; urlPrefix: https://tools.ietf.org/html/draft-ietf-tokbind-pr
text: Token Binding
text: Token Binding ID; url: section-3.2


spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/
type: dfn
text: recognized algorithm name
Expand Down Expand Up @@ -108,6 +112,8 @@ spec: WHATWG HTML; urlPrefix: https://html.spec.whatwg.org/
text: focus
</pre> <!-- class=anchors -->

<!-- L128 spec:webappsec-credential-management-1; type:dictionary; for:/; text:CredentialRequestOptions -->

<pre class="link-defaults">
spec:credential-management; type:dfn; text:credentials
spec:html; type:dfn; for:environment settings object; text:global object
Expand Down Expand Up @@ -286,7 +292,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
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
[=attestation statement=] is conveyed in an [=attestation object=] during [=registration=]. See also [[#sctn-attestation]]
and [Figure 3](#fig-attStructs).
and [Figure 3](#fig-attStructs). Whether or how the client platform conveys the [=attestation statement=] and [=AAGUID=]
portions of the [=attestation object=] to the [=[RP]=] is described by [=attestation conveyance=].

: <dfn>Attestation Certificate</dfn>
:: A X.509 Certificate for the <dfn>attestation key pair</dfn> used by an [=authenticator=] to attest to its manufacture
Expand Down Expand Up @@ -822,7 +829,6 @@ When this method is invoked, the user agent MUST execute the following algorithm
1. [=While=] |issuedRequests| [=list/is not empty=], perform the following actions depending upon
|lifetimeTimer| and responses from the authenticators:
<dl class="switch">

: If |lifetimeTimer| expires,
:: [=set/For each=] |authenticator| in |issuedRequests| invoke the [=authenticatorCancel=] operation on |authenticator|
and [=set/remove=] |authenticator| from |issuedRequests|.
Expand Down Expand Up @@ -854,6 +860,9 @@ When this method is invoked, the user agent MUST execute the following algorithm
: <code><dfn for="credentialCreationData">clientDataJSONResult</dfn></code>
:: whose value is the bytes of |clientDataJSON|.

: <code><dfn for="credentialCreationData">attestationConveyancePreferenceOption</dfn></code>
:: whose value is the value of |options|.{{MakePublicKeyCredentialOptions/attestation}}.

: <code><dfn for="credentialCreationData">clientExtensionResults</dfn></code>
:: whose value is an {{AuthenticationExtensions}} object containing [=extension identifier=] →
[=client extension output=] entries. The entries are created by running each extension's
Expand All @@ -866,6 +875,28 @@ When this method is invoked, the user agent MUST execute the following algorithm
1. Let |attestationObject| be a new {{ArrayBuffer}}, created using |global|'s [=%ArrayBuffer%=], containing the
bytes of <code>|credentialCreationData|.[=attestationObjectResult=]</code>'s value.

1. If <code>|credentialCreationData|.[=attestationConveyancePreferenceOption=]</code>'s value is
<dl class="switch">
: "none"
:: Replace potentially uniquely identifying information (such as [=AAGUID=] and
[=attestation certificates=]) in the [=attested credential data=] and [=attestation statement=],
respectively, with blinded versions of the same data.

Issue(w3c/webauthn#694): need to define "blinding". See also
[#462](https://github.com/w3c/webauthn/issues/462).

: "indirect"
:: The client MAY replace the [=AAGUID=] and [=attestation statement=] with a more privacy-friendly
and/or more easily verifiable version of the same data (for example, by employing a [=Privacy CA=]).

: "direct"
:: Convey the [=authenticator=]'s [=AAGUID=] and [=attestation statement=], unaltered, to the RP.

Issue: @balfanz wishes to add to the "direct" case:
If the [=authenticator=] violates the privacy requirements of the [=attestation type=] it is using,
the client SHOULD terminate this algorithm with a "{{AttestationNotPrivateError}}".
</dl>

1. Let |id| be <code>|attestationObject|.authData.[=attestedCredentialData=].[=credentialId=]</code>.

1. Let |pubKeyCred| be a new {{PublicKeyCredential}} object associated with |global| whose fields are:
Expand Down Expand Up @@ -1400,6 +1431,7 @@ optionally evidence of [=user consent=] to a specific transaction.
unsigned long timeout;
sequence<PublicKeyCredentialDescriptor> excludeCredentials = [];
AuthenticatorSelectionCriteria authenticatorSelection;
AttestationConveyancePreference attestation = "none";
AuthenticationExtensions extensions;
};
</xmp>
Expand Down Expand Up @@ -1448,6 +1480,10 @@ optionally evidence of [=user consent=] to a specific transaction.
:: This member is intended for use by [=[RPS]=] that wish to select the appropriate authenticators to participate in
the {{CredentialsContainer/create()}} operation.

: <dfn>attestation</dfn>
:: This member is intended for use by [=[RPS]=] that wish to express their preference for [=attestation conveyance=].
The default is {{AttestationConveyancePreference/none}}.

: <dfn>extensions</dfn>
:: This member contains additional parameters requesting additional processing by the client and authenticator. For
example, the caller may request that only authenticators with certain capabilies be used to create the credential, or
Expand Down Expand Up @@ -1586,6 +1622,42 @@ example of the latter, when the user is accessing the [=[RP]=] from a given clie
use a [=roaming authenticator=] which was originally registered with the [=[RP]=] using a different client.


### <dfn>Attestation Conveyance</dfn> Preference enumeration (enum <dfn enum>AttestationConveyancePreference</dfn>) ### {#attestation-convey}

[=[RPS]=] may use {{AttestationConveyancePreference}} to specify their preference regarding [=attestation conveyance=]
during credential generation.

<pre class="idl">
enum AttestationConveyancePreference {
"none",
"indirect",
"direct"
};
</pre>

<div dfn-type="enum-value" dfn-for="AttestationConveyancePreference">
* <dfn>none</dfn> - indicates that the [=[RP]=] is not interested in [=authenticator=] [=attestation=].
The client may replace the [=AAGUID=] and [=attestation statement=] generated
by the authenticator with meaningless client-generated values. For example, in order to avoid having to obtain
[=user consent=] to relay uniquely identifying information to the [=[RP]=], or to save a roundtrip to a Privacy CA.

This is the default value.

* <dfn>indirect</dfn> - indicates that the [=[RP]=] prefers an [=attestation=] conveyance yielding verifiable
[=attestation statements=], but allows the client to decide how to obtain such [=attestation statements=].
The client may replace the authenticator-generated [=attestation statements=] with [=attestation statements=] generated
by a [=Privacy CA=], in order to protect the user's privacy, or to assist [=[RPS]=] with attestation verification in a
heterogeneous ecosystem.

Note: There is no guarantee that the [=[RP]=] will obtain a verifiable [=attestation statement=] in this case.
For example, in the case that the authenticator employs [=self attestation=].

* <dfn>direct</dfn> - indicates that the [=[RP]=] wants to receive the [=attestation statement=] as generated by
the [=authenticator=].

</div>


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

The {{PublicKeyCredentialRequestOptions}} dictionary supplies {{CredentialsContainer/get()}} with the data it needs to generate
Expand Down

0 comments on commit 81fdc9a

Please sign in to comment.