Convert `makeCredential()`'s parameters into a dictionary. #399

mikewest · 2017-04-12T13:00:54Z

Passing a single dictionary parameter into makrCredential() provides
for greater forward compatibility, as new data can be flexibly added
to the method invocation without restructuring the existing
structure. It also helps developers understand what they're passing
in, as each parameter will be labeled.

This patch restructures the data passed into makeCredential()
substantially, moving from four parameters to a single dictionary,
and merging some existing types into a simpler structure. Most of
it is straightforward; the only bit I know will be controversial is
dropping RelyingPartyUserInfo in favor of two instances of a
simpler ScopedCredentialEntity object: one for the RP, one for the
user.

Let's chat about how (un)reasonable this approach might be.

This patch adds an 'AuthenticatorResponse' interface, representing the generic attributes of responses from authenticators. It then redefines 'ScopedCredentialInfo' and 'AuthenticatorAssertion' to derive from this interface, and renames them to 'AuthenticatorAttestionResponse' and 'AuthenticatorAssertionResponse' respectively. These new interfaces are a drop-in replacement for the old interfaces, no normative changes are intended in this patch, other than the renaming.

Passing a single dictionary parameter into `getAssertion()` provides for greater forward compatibility, as new data can be flexibly added to the method invocation without restructuring the existing structure. It also helps developers understand what they're passing in. This is less important for `getAssertion()` than it is for `makeCredential()`, obviously, but aligning both in a similar structure seems like a good change to make.

Passing a single dictionary parameter into `makrCredential()` provides for greater forward compatibility, as new data can be flexibly added to the method invocation without restructuring the existing structure. It also helps developers understand what they're passing in, as each parameter will be labeled. This patch restructures the data passed into `makeCredential()` substantially, moving from four parameters to a single dictionary, and merging some existing types into a simpler structure. Most of it is straightforward; the only bit I know will be controversial is dropping `RelyingPartyUserInfo` in favor of two instances of a simpler `ScopedCredentialEntity` object: one for the RP, one for the user. Let's chat about how (un)reasonable this approach might be.

mikewest · 2017-04-12T13:01:43Z

As @vijaybh suggeted in #2 of https://lists.w3.org/Archives/Public/public-webauthn/2017Apr/0158.html, moving getAssertion() and makeCredential() to dictionary-based invocation rather than list-of-parameter-based invocation seems pretty reasonable. This patch migrates makeCredential(), and makes some potentially controversial suggestions in doing so. I've kept it separate from the getAssertion() migration in #398 for that reason.

vijaybh · 2017-04-12T15:55:59Z

index.bs

@@ -889,6 +792,102 @@ user consent to a specific transaction. The structure of these signatures is def
    [[#op-get-assertion]].
 </div>

+## Additional options for Attestation (dictionary <dfn dictionary>MakeCredentialOptions</dfn>) ## {#dictionary-makecredentialoptions}


Editorial: this isn't "additional options" any more, it's all the options. Maybe say something like "Parameters for credential creation" instead?

Picked up in 6dca154.

yeah, as i noted in review of PR #398 maybe these are not "options" but are parameters, some of which are optional ?

leshi · 2017-04-14T15:43:06Z

index.bs

-            BufferSource                         attestationChallenge,
-            optional ScopedCredentialOptions     options
-        );
+        Promise<ScopedCredentialInfo> makeCredential(MakeCredentialOptions options);


<bikeshed> I like the request terminology that you had in PR #398. Maybe also rename MakeCredentialOptions to MakeRequest or CredentialRequest? </bikeshed>

But, I do not like the term request here because that dict instance is not a "request" in an of itself. I much prefer just using options or parameters here (see #398 (comment)). If I were to implement, I'd find request misleading/confusing.

I'm fine with whatever term we use, as long as it's consistent

I think we agreed that we're running with options for both.

leshi · 2017-04-14T15:47:39Z

index.bs

+
+        // Attestation configuration:
+        required BufferSource                         challenge;
+        required sequence<ScopedCredentialParameters> parameters;


I don't think these are the attestation parameters -- they're the parameters for the type of credential. We don't have parameters that allow an RP to request a particular type of attestation, though maybe we should.

Hm. the challenge is not a part of attestation per-se -- it provides per-protocol-run roundtrip integrity whether the protocol run is a registration operation or an authn operation.

ScopedCredentialParameters are params for the creation of the underlying credential key pair, which then is attested. see #404

If y'all have suggestions for both parameters and Attestation configuration, I'm all ears. I don't have strong opinions about either.

I think we agreed on the call to drop the comment, and leave the names.

i think "drop the comment, and leave the names" is fine for now", thx.

leshi · 2017-04-14T15:49:36Z

index.bs

+<xmp class="idl">
+    dictionary MakeCredentialOptions {
+        // Relying Party / User Metadata:
+        required ScopedCredentialEntity rp;


Interesting, so we now have the same data for an rp and the user. Cool!

leshi · 2017-04-14T15:50:56Z

index.bs

+
+<xmp class="idl">
+    dictionary ScopedCredentialEntity {
+        DOMString id;


In RelyingPartyUserInfo some of these were required, why the change?

+1 to @leshi's question "In RelyingPartyUserInfo some of these were required, why the change?"

Suggest making id and name required.

On the call, Jeffrey & Mike mentioned that requiring developers to set RP is a bad idea and the params that were required in RelyingPartyUserInfo can be enforced in the algorithm.

equalsJeffH

Overall I am fine with these changes. there's some modest items to fix before merging. thanks @mikewest !

equalsJeffH · 2017-04-14T16:10:50Z

index.bs

+1. If the {{ScopedCredentialEntity/id}} member of {{options}}.{{MakeCredentialOptions/rp}} is [=present|not present=], then set
+    |rpId| to |callerOrigin|.
+
+   Otherwise:


unfortunately, the as-rendered indent of this "otherwise" block is now lost and so it is visually confusing that this is a block of substeps. we need to fix this.

equalsJeffH · 2017-04-14T16:14:12Z

index.bs


-1. Let |normalizedParameters| be a new [=list=] whose [=list/items=] are pairs of ScopedCredentialType and a [=dictionary=] type
-    (as returned by [=normalizing an algorithm=]).
+1. Let |normalizedParameters| be a new [=list=] whose [=list/items=] are pairs of {{ScopedCredentialType}} and a [=dictionary=]


unfortunately, now the as-rendered step numbering is re-started here, rather than properly continuing.

equalsJeffH · 2017-04-14T16:27:40Z

index.bs

+
+        // Attestation configuration:
+        required BufferSource                         challenge;
+        required sequence<ScopedCredentialParameters> parameters;


Hm. the challenge is not a part of attestation per-se -- it provides per-protocol-run roundtrip integrity whether the protocol run is a registration operation or an authn operation.

ScopedCredentialParameters are params for the creation of the underlying credential key pair, which then is attested. see #404

equalsJeffH · 2017-04-14T16:29:59Z

index.bs

@@ -889,6 +792,102 @@ user consent to a specific transaction. The structure of these signatures is def
    [[#op-get-assertion]].
 </div>

+## Parameters for Credential Creation (dictionary <dfn dictionary>MakeCredentialOptions</dfn>) ## {#dictionary-makecredentialoptions}


nominally, I think I'm ok with this overall restructuring of the makeCredential parameters/options, tho I have detail-level comments below.

equalsJeffH · 2017-04-14T16:34:49Z

index.bs

+
+        // Optional constraints:
+        unsigned long                        timeout;
+        sequence<ScopedCredentialDescriptor> exclude;


I would keep the name of this as excludeList. I note that the other PRs do not alter allowList's name.

equalsJeffH · 2017-04-14T16:44:37Z

index.bs

+
+        Its value's {{ScopedCredentialEntity/id}} member is required, and contains an identifier for the account, specified by
+        the [=relying party=]. This is not meant to be displayed to the user, but is used by the relying party to control the
+        number of credentials - an authenticator will never contain more than one credential for a given relying party under the


aside: see #403

equalsJeffH · 2017-04-14T16:45:38Z

index.bs

+    ::  This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete. This is
+        treated as a hint, and may be overridden by the platform.
+
+    :   <dfn>exclude</dfn>


s/exclude/excludeList/

equalsJeffH · 2017-04-14T16:47:34Z

index.bs

+        same {{ScopedCredentialEntity/id}}.
+
+    :   <dfn>challenge</dfn>
+    ::  This member contains a channelge intended to be used for generating the newly created credential's [=attestation object=].


s/channelge/challenge/ :)

need to expand the explanation (but not necessarily now) -- challenge is used in both regstn and authn protocol runs and has security implications. have submitted #404

equalsJeffH · 2017-04-14T16:50:11Z

index.bs

+
+<xmp class="idl">
+    dictionary ScopedCredentialEntity {
+        DOMString id;


+1 to @leshi's question "In RelyingPartyUserInfo some of these were required, why the change?"

mikewest · 2017-04-14T20:02:42Z

Addressed the comments based on my understanding of what we agreed to in the call via 8058917, and merged in #398 (and therefore #397) via ae33b14. Land those two before you land this one. :)

equalsJeffH · 2017-04-14T20:26:13Z

LGTM, thx @mikewest !

leshi

Thank you, @mikewest!

…onary-makecredential

mikewest added 3 commits April 12, 2017 09:26

vijaybh reviewed Apr 12, 2017

View reviewed changes

mikewest added 2 commits April 12, 2017 18:40

fixup drop 'additional'

0039a13

fixup 'additional'

6dca154

equalsJeffH added subtype:algorithms/WebIDL type:technical labels Apr 12, 2017

fixup AssertionRequest

3a5fefb

equalsJeffH added this to the WD-05 milestone Apr 12, 2017

leshi requested changes Apr 14, 2017

View reviewed changes

jcjones approved these changes Apr 14, 2017

View reviewed changes

equalsJeffH suggested changes Apr 14, 2017

View reviewed changes

mikewest added 5 commits April 14, 2017 21:31

fixup @equalsJeffH

3cdf1bf

fixup revert AssertionRequest.

4f4b79f

fixup merge 'AuthenticatorResponse'

705ecab

fixup @equalsJeffH

8058917

fixup merge 'getAssertion()'

ae33b14

equalsJeffH approved these changes Apr 14, 2017

View reviewed changes

leshi approved these changes Apr 14, 2017

View reviewed changes

equalsJeffH merged commit 275a552 into w3c:master Apr 14, 2017

WebAuthnBot pushed a commit that referenced this pull request Apr 14, 2017

Built by Travis-CI: 275a552 Merge pull request #399 from battre/dicti…

e6608d7

…onary-makecredential

equalsJeffH mentioned this pull request Apr 14, 2017

adopt definition list markdown notation for <div dfn-type="foo" dfn-for="bar"> blocks #405

Closed

mikewest deleted the dictionary-makecredential branch April 18, 2017 07:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert `makeCredential()`'s parameters into a dictionary. #399

Convert `makeCredential()`'s parameters into a dictionary. #399

mikewest commented Apr 12, 2017

mikewest commented Apr 12, 2017 •

edited

vijaybh Apr 12, 2017

mikewest Apr 12, 2017

equalsJeffH Apr 12, 2017

leshi Apr 14, 2017

equalsJeffH Apr 14, 2017

leshi Apr 14, 2017

mikewest Apr 14, 2017

leshi Apr 14, 2017

equalsJeffH Apr 14, 2017 •

edited

mikewest Apr 14, 2017

mikewest Apr 14, 2017

equalsJeffH Apr 14, 2017

leshi Apr 14, 2017

leshi Apr 14, 2017

equalsJeffH Apr 14, 2017

leshi Apr 14, 2017

leshi Apr 14, 2017

equalsJeffH left a comment

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017 •

edited

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

equalsJeffH Apr 14, 2017

mikewest commented Apr 14, 2017

equalsJeffH commented Apr 14, 2017

leshi left a comment

Convert makeCredential()'s parameters into a dictionary. #399

Convert makeCredential()'s parameters into a dictionary. #399

Conversation

mikewest commented Apr 12, 2017

mikewest commented Apr 12, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

equalsJeffH Apr 14, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

equalsJeffH left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

equalsJeffH Apr 14, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikewest commented Apr 14, 2017

equalsJeffH commented Apr 14, 2017

leshi left a comment

Choose a reason for hiding this comment

Convert `makeCredential()`'s parameters into a dictionary. #399

Convert `makeCredential()`'s parameters into a dictionary. #399

mikewest commented Apr 12, 2017 •

edited

equalsJeffH Apr 14, 2017 •

edited

equalsJeffH Apr 14, 2017 •

edited