From 59ecbf3b0cd11720e647db7f4eba031c5a8a1d31 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Feb 2022 14:54:37 -0800 Subject: [PATCH 01/27] Add sections for new API methods --- index.bs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/index.bs b/index.bs index 06bcd0af9..7617ecf37 100644 --- a/index.bs +++ b/index.bs @@ -2387,6 +2387,30 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic +### Deserialize Registration and Authentication ceremony options - PublicKeyCredential's `optionsFromJSON()` Method ### {#sctn-optionsFromJSON} + +
+ +[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for {{CredentialsContainer/create()|navigator.credentials.create()}} to {{PublicKeyCredentialCreationOptions}}, or JSON-compatible serialized representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} to {{PublicKeyCredentialRequestOptions}}. + +This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. + +Upon invocation, the [=client=] takes the provided options and returns an identically-structured object with specific strings encoded with [=base64url encoding=] decoded to {{ArrayBuffer}} values according to the corresponding type definition. + +
+ +### Serialize Registration and Authentication ceremony responses - PublicKeyCredential's `toJSON()` Method ### {#sctn-toJSON} + +
+ +[=[WRPS]=] use this method to convert the instance of {{PublicKeyCredential}} returned from {{CredentialsContainer/create()|navigator.credentials.create()}} or {{CredentialsContainer/get()|navigator.credentials.get()}} to a JSON-serialized representations suitable for submission to a [=[RP]=] server as a payload with `application/json` mimetype. + +This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. + +Upon invocation, the [=client=] returns an object with the same structure as the instance of the {{PublicKeyCredential}} with {{ArrayBuffer}} values encoded with [=base64url encoding=]. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's `response` property, which will either be {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. + +
+ ## Authenticator Responses (interface AuthenticatorResponse) ## {#iface-authenticatorresponse} [=Authenticators=] respond to [=[RP]=] requests by returning an object derived from the From 493095fc51d99cc3c1bfbd0b8aa515fc5d2fc2fb Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Tue, 1 Mar 2022 16:32:29 -0800 Subject: [PATCH 02/27] Migrate toJSON to instance method defs --- index.bs | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/index.bs b/index.bs index 7617ecf37..1601ce534 100644 --- a/index.bs +++ b/index.bs @@ -1407,6 +1407,7 @@ that are returned to the caller when a new credential is created, or a new asser [SameObject] readonly attribute AuthenticatorResponse response; [SameObject] readonly attribute DOMString? authenticatorAttachment; AuthenticationExtensionsClientOutputs getClientExtensionResults(); + TBD toJSON(); };
@@ -1450,6 +1451,13 @@ that are returned to the caller when a new credential is created, or a new asser [=extension identifier=] → [=client extension output=] entries produced by the extension's [=client extension processing=]. + : {{PublicKeyCredential/toJSON()}} + :: This operation returns a JSON-serialized representation of the instance of {{PublicKeyCredential}} suitable for submission + to a [=[RP]=] server as a payload with `application/json` mimetype. The [=client=] returns an object with the same structure + as the instance of the {{PublicKeyCredential}} with {{ArrayBuffer}} values encoded with [=base64url encoding=]. {{ArrayBuffer}} + values to be encoded are identified according to the detected type of the instance's `response` property, which will either be + {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. + : \[[type]] :: The {{PublicKeyCredential}} [=interface object=]'s {{Credential/[[type]]}} [=internal slot=]'s value is the string "`public-key`". @@ -2399,18 +2407,6 @@ Upon invocation, the [=client=] takes the provided options and returns an identi -### Serialize Registration and Authentication ceremony responses - PublicKeyCredential's `toJSON()` Method ### {#sctn-toJSON} - -
- -[=[WRPS]=] use this method to convert the instance of {{PublicKeyCredential}} returned from {{CredentialsContainer/create()|navigator.credentials.create()}} or {{CredentialsContainer/get()|navigator.credentials.get()}} to a JSON-serialized representations suitable for submission to a [=[RP]=] server as a payload with `application/json` mimetype. - -This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. - -Upon invocation, the [=client=] returns an object with the same structure as the instance of the {{PublicKeyCredential}} with {{ArrayBuffer}} values encoded with [=base64url encoding=]. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's `response` property, which will either be {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. - -
- ## Authenticator Responses (interface AuthenticatorResponse) ## {#iface-authenticatorresponse} [=Authenticators=] respond to [=[RP]=] requests by returning an object derived from the From e87c96d89b7cbd452b4c6139de242ea7f5a8a8bf Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Tue, 1 Mar 2022 16:46:51 -0800 Subject: [PATCH 03/27] Add notes --- index.bs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 1601ce534..70a06bd15 100644 --- a/index.bs +++ b/index.bs @@ -1458,6 +1458,10 @@ that are returned to the caller when a new credential is created, or a new asser values to be encoded are identified according to the detected type of the instance's `response` property, which will either be {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. +
+ Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. +
+ : \[[type]] :: The {{PublicKeyCredential}} [=interface object=]'s {{Credential/[[type]]}} [=internal slot=]'s value is the string "`public-key`". @@ -2401,10 +2405,11 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic [=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for {{CredentialsContainer/create()|navigator.credentials.create()}} to {{PublicKeyCredentialCreationOptions}}, or JSON-compatible serialized representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} to {{PublicKeyCredentialRequestOptions}}. -This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. - Upon invocation, the [=client=] takes the provided options and returns an identically-structured object with specific strings encoded with [=base64url encoding=] decoded to {{ArrayBuffer}} values according to the corresponding type definition. +Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries to handle this +deseraili + ## Authenticator Responses (interface AuthenticatorResponse) ## {#iface-authenticatorresponse} From bec86b509cc6c61ed160ff24b11e8bc8ae6d257e Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Tue, 1 Mar 2022 16:47:04 -0800 Subject: [PATCH 04/27] Add placeholder IDL for optionsFromJSON --- index.bs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/index.bs b/index.bs index 70a06bd15..04be3b153 100644 --- a/index.bs +++ b/index.bs @@ -2407,6 +2407,12 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic Upon invocation, the [=client=] takes the provided options and returns an identically-structured object with specific strings encoded with [=base64url encoding=] decoded to {{ArrayBuffer}} values according to the corresponding type definition. + + partial interface PublicKeyCredential { + static TBD optionsFromJSON(); + }; + + Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries to handle this deseraili From 002d0f5a89f97e329c3b2caade0485c4352ea47b Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Tue, 1 Mar 2022 17:13:31 -0800 Subject: [PATCH 05/27] Take a stab at toJSON IDL definitions --- index.bs | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 04be3b153..7154379e9 100644 --- a/index.bs +++ b/index.bs @@ -1407,7 +1407,7 @@ that are returned to the caller when a new credential is created, or a new asser [SameObject] readonly attribute AuthenticatorResponse response; [SameObject] readonly attribute DOMString? authenticatorAttachment; AuthenticationExtensionsClientOutputs getClientExtensionResults(); - TBD toJSON(); + PublicKeyCredentialJSON toJSON(); };
@@ -1458,6 +1458,37 @@ that are returned to the caller when a new credential is created, or a new asser values to be encoded are identified according to the detected type of the instance's `response` property, which will either be {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. + + typedef DOMString Base64URLString; + typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON; + + dictionary RegistrationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAttestationResponseJSON response; + DOMString type; + }; + + dictionary AuthenticationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAssertionResponseJSON response; + DOMString type; + }; + + dictionary AuthenticatorAttestationResponseJSON { + Base64URLString clientDataJSON; + Base64URLString attestationObject; + }; + + dictionary AuthenticatorAssertionResponseJSON { + Base64URLString clientDataJSON; + Base64URLString authenticatorData; + Base64URLString signature; + Base64URLString? userHandle; + }; + +
Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries.
From a476667f051e7bcc4d0cc0367933a935d8725d43 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 2 Mar 2022 09:50:10 -0800 Subject: [PATCH 06/27] Clarify toJSON behavior --- index.bs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 7154379e9..d2d8aae95 100644 --- a/index.bs +++ b/index.bs @@ -1452,11 +1452,10 @@ that are returned to the caller when a new credential is created, or a new asser [=client extension processing=]. : {{PublicKeyCredential/toJSON()}} - :: This operation returns a JSON-serialized representation of the instance of {{PublicKeyCredential}} suitable for submission - to a [=[RP]=] server as a payload with `application/json` mimetype. The [=client=] returns an object with the same structure - as the instance of the {{PublicKeyCredential}} with {{ArrayBuffer}} values encoded with [=base64url encoding=]. {{ArrayBuffer}} - values to be encoded are identified according to the detected type of the instance's `response` property, which will either be - {{AuthenticatorAttestationResponse}} or {{AuthenticatorAssertionResponse}}. + :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, a JSON-serialized representation of the instance of + {{PublicKeyCredential}} suitable for submission to a [=[RP]=] server as a payload with `application/json` mimetype. The [=client=] is in + charge of encoding any {{ArrayBuffer}} values using [=base64url encoding=] to generate strings compatible with JSON syntax. {{ArrayBuffer}} + values to be encoded are identified according to the detected type of the instance's `response` property. typedef DOMString Base64URLString; From 161e102d7d9b40d0def2f736503aa1782fd575b9 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Wed, 2 Mar 2022 09:50:24 -0800 Subject: [PATCH 07/27] Group related IDL defs together --- index.bs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index d2d8aae95..860731af5 100644 --- a/index.bs +++ b/index.bs @@ -1468,6 +1468,11 @@ that are returned to the caller when a new credential is created, or a new asser DOMString type; }; + dictionary AuthenticatorAttestationResponseJSON { + Base64URLString clientDataJSON; + Base64URLString attestationObject; + }; + dictionary AuthenticationResponseJSON { Base64URLString id; Base64URLString rawId; @@ -1475,11 +1480,6 @@ that are returned to the caller when a new credential is created, or a new asser DOMString type; }; - dictionary AuthenticatorAttestationResponseJSON { - Base64URLString clientDataJSON; - Base64URLString attestationObject; - }; - dictionary AuthenticatorAssertionResponseJSON { Base64URLString clientDataJSON; Base64URLString authenticatorData; From 16aab08c659a31a57f592e2261c78705b43b1f1d Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Wed, 2 Mar 2022 11:24:20 -0800 Subject: [PATCH 08/27] Define IDLs for optionsFromJSON() --- index.bs | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 860731af5..11741f081 100644 --- a/index.bs +++ b/index.bs @@ -2439,7 +2439,52 @@ Upon invocation, the [=client=] takes the provided options and returns an identi <xmp class="idl"> partial interface PublicKeyCredential { - static TBD optionsFromJSON(); + static PublicKeyCredentialCreationOptions optionsFromJSON(CreationOptionsJSON creationOptions); + }; + + partial interface PublicKeyCredential { + static PublicKeyCredentialRequestOptions optionsFromJSON(RequestOptionsJSON requestOptions); + }; + + dictionary CreationOptionsJSON { + DOMString method = "create"; + PublicKeyCredentialCreationOptionsJSON options; + }; + + dictionary RequestOptionsJSON { + DOMString method = "get"; + PublicKeyCredentialRequestOptionsJSON options; + }; + + dictionary PublicKeyCredentialCreationOptionsJSON { + PublicKeyCredentialRpEntity rp; + PublicKeyCredentialUserEntityJSON user; + Base64URLString challenge; + sequence<PublicKeyCredentialDescriptorJSON> excludeCredentials = []; + AuthenticatorSelectionCriteria authenticatorSelection; + DOMString attestation = "none"; + AuthenticationExtensionsClientInputs extensions; + }; + + dictionary PublicKeyCredentialRequestOptionsJSON { + Base64URLString challenge; + unsigned long timeout; + DOMString rpId; + sequence<PublicKeyCredentialDescriptorJSON> allowCredentials = []; + DOMString userVerification = "preferred"; + AuthenticationExtensionsClientInputs extensions; + }; + + dictionary PublicKeyCredentialUserEntityJSON { + Base64URLString id; + DOMString name; + DOMString displayName; + }; + + dictionary PublicKeyCredentialDescriptorJSON { + Base64URLString id; + DOMString type; + sequence<DOMString> transports; }; From d264b61d50f9c241d683ee9632fc61e705c5c433 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 2 Mar 2022 11:24:32 -0800 Subject: [PATCH 09/27] Finish a thought --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 11741f081..7a8d97c7d 100644 --- a/index.bs +++ b/index.bs @@ -2489,7 +2489,7 @@ Upon invocation, the [=client=] takes the provided options and returns an identi Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries to handle this -deseraili +deserialization. From c1aef2768cf74d82c2053baf7f8e6894df85a1f6 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 2 Mar 2022 12:12:05 -0800 Subject: [PATCH 10/27] Mark arguments required --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 7a8d97c7d..90487c895 100644 --- a/index.bs +++ b/index.bs @@ -2447,13 +2447,13 @@ Upon invocation, the [=client=] takes the provided options and returns an identi }; dictionary CreationOptionsJSON { - DOMString method = "create"; - PublicKeyCredentialCreationOptionsJSON options; + required DOMString method = "create"; + required PublicKeyCredentialCreationOptionsJSON options; }; dictionary RequestOptionsJSON { - DOMString method = "get"; - PublicKeyCredentialRequestOptionsJSON options; + required DOMString method = "get"; + required PublicKeyCredentialRequestOptionsJSON options; }; dictionary PublicKeyCredentialCreationOptionsJSON { From e11e51832514c8acde3c902c6465d4a5222a3ab0 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 12:44:35 -0700 Subject: [PATCH 11/27] Remove notes rationalizing new API existence --- index.bs | 7 ------- 1 file changed, 7 deletions(-) diff --git a/index.bs b/index.bs index 90487c895..4725017ac 100644 --- a/index.bs +++ b/index.bs @@ -1488,10 +1488,6 @@ that are returned to the caller when a new credential is created, or a new asser }; -
- Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries. -
- : \[[type]] :: The {{PublicKeyCredential}} [=interface object=]'s {{Credential/[[type]]}} [=internal slot=]'s value is the string "`public-key`". @@ -2488,9 +2484,6 @@ Upon invocation, the [=client=] takes the provided options and returns an identi }; -Note: This method is intended to make WebAuthn API consumption tenable without requiring the use of third-party libraries to handle this -deserialization. - ## Authenticator Responses (interface AuthenticatorResponse) ## {#iface-authenticatorresponse} From 91161a27bf6673f849c86a9fa5563495e796cfb4 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 12:44:51 -0700 Subject: [PATCH 12/27] Try to take care of fatal build errors --- index.bs | 62 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/index.bs b/index.bs index 4725017ac..febe42aa2 100644 --- a/index.bs +++ b/index.bs @@ -1457,36 +1457,38 @@ that are returned to the caller when a new credential is created, or a new asser charge of encoding any {{ArrayBuffer}} values using [=base64url encoding=] to generate strings compatible with JSON syntax. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's `response` property. - - typedef DOMString Base64URLString; - typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON; - - dictionary RegistrationResponseJSON { - Base64URLString id; - Base64URLString rawId; - AuthenticatorAttestationResponseJSON response; - DOMString type; - }; - - dictionary AuthenticatorAttestationResponseJSON { - Base64URLString clientDataJSON; - Base64URLString attestationObject; - }; - - dictionary AuthenticationResponseJSON { - Base64URLString id; - Base64URLString rawId; - AuthenticatorAssertionResponseJSON response; - DOMString type; - }; - - dictionary AuthenticatorAssertionResponseJSON { - Base64URLString clientDataJSON; - Base64URLString authenticatorData; - Base64URLString signature; - Base64URLString? userHandle; - }; - +
+ + typedef DOMString Base64URLString; + typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON; + + dictionary RegistrationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAttestationResponseJSON response; + DOMString type; + }; + + dictionary AuthenticatorAttestationResponseJSON { + Base64URLString clientDataJSON; + Base64URLString attestationObject; + }; + + dictionary AuthenticationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAssertionResponseJSON response; + DOMString type; + }; + + dictionary AuthenticatorAssertionResponseJSON { + Base64URLString clientDataJSON; + Base64URLString authenticatorData; + Base64URLString signature; + Base64URLString? userHandle; + }; + +
: \[[type]] :: The {{PublicKeyCredential}} [=interface object=]'s {{Credential/[[type]]}} [=internal slot=]'s value is the string From 1161328c54c6609cc0dd70345c68a217976e45cb Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 13:10:29 -0700 Subject: [PATCH 13/27] Define AuthenticationExtensionsClientInputsJSON --- index.bs | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index febe42aa2..c450f36b6 100644 --- a/index.bs +++ b/index.bs @@ -2461,7 +2461,7 @@ Upon invocation, the [=client=] takes the provided options and returns an identi sequence excludeCredentials = []; AuthenticatorSelectionCriteria authenticatorSelection; DOMString attestation = "none"; - AuthenticationExtensionsClientInputs extensions; + AuthenticationExtensionsClientInputsJSON extensions; }; dictionary PublicKeyCredentialRequestOptionsJSON { @@ -2470,7 +2470,7 @@ Upon invocation, the [=client=] takes the provided options and returns an identi DOMString rpId; sequence allowCredentials = []; DOMString userVerification = "preferred"; - AuthenticationExtensionsClientInputs extensions; + AuthenticationExtensionsClientInputsJSON extensions; }; dictionary PublicKeyCredentialUserEntityJSON { @@ -2483,6 +2483,19 @@ Upon invocation, the [=client=] takes the provided options and returns an identi Base64URLString id; DOMString type; sequence transports; + + dictionary AuthenticationExtensionsClientInputsJSON { + DOMString appid; + DOMString appidExclude; + boolean uvm; + boolean credProps; + AuthenticationExtensionsLargeBlobInputsJSON largeBlob; + }; + + dictionary AuthenticationExtensionsLargeBlobInputsJSON { + DOMString support; + boolean read; + Base64URLString write; }; From f13cb3580015ddb76dbf196d2722b087bdb2284a Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 13:11:38 -0700 Subject: [PATCH 14/27] Add required and align properties --- index.bs | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/index.bs b/index.bs index c450f36b6..d668218ab 100644 --- a/index.bs +++ b/index.bs @@ -2455,34 +2455,37 @@ Upon invocation, the [=client=] takes the provided options and returns an identi }; dictionary PublicKeyCredentialCreationOptionsJSON { - PublicKeyCredentialRpEntity rp; - PublicKeyCredentialUserEntityJSON user; - Base64URLString challenge; - sequence excludeCredentials = []; - AuthenticatorSelectionCriteria authenticatorSelection; - DOMString attestation = "none"; - AuthenticationExtensionsClientInputsJSON extensions; + required PublicKeyCredentialRpEntity rp; + required PublicKeyCredentialUserEntityJSON user; + required Base64URLString challenge; + required sequence pubKeyCredParams; + unsigned long timeout; + required sequence excludeCredentials = []; + AuthenticatorSelectionCriteria authenticatorSelection; + DOMString attestation = "none"; + AuthenticationExtensionsClientInputsJSON extensions; }; dictionary PublicKeyCredentialRequestOptionsJSON { - Base64URLString challenge; - unsigned long timeout; - DOMString rpId; - sequence allowCredentials = []; - DOMString userVerification = "preferred"; - AuthenticationExtensionsClientInputsJSON extensions; + required Base64URLString challenge; + unsigned long timeout; + DOMString rpId; + sequence allowCredentials = []; + DOMString userVerification = "preferred"; + AuthenticationExtensionsClientInputsJSON extensions; }; dictionary PublicKeyCredentialUserEntityJSON { - Base64URLString id; - DOMString name; - DOMString displayName; + required Base64URLString id; + required DOMString name; + required DOMString displayName; }; dictionary PublicKeyCredentialDescriptorJSON { - Base64URLString id; - DOMString type; - sequence transports; + required Base64URLString id; + required DOMString type; + sequence transports; + }; dictionary AuthenticationExtensionsClientInputsJSON { DOMString appid; From bfa21b07280c5988a8dd85206062c76e8fbe3b38 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 13:12:05 -0700 Subject: [PATCH 15/27] Split up optionsFromJSON for simplicity's sake --- index.bs | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/index.bs b/index.bs index d668218ab..3cd6ab544 100644 --- a/index.bs +++ b/index.bs @@ -2437,21 +2437,11 @@ Upon invocation, the [=client=] takes the provided options and returns an identi partial interface PublicKeyCredential { - static PublicKeyCredentialCreationOptions optionsFromJSON(CreationOptionsJSON creationOptions); + static PublicKeyCredentialCreationOptions getCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); }; partial interface PublicKeyCredential { - static PublicKeyCredentialRequestOptions optionsFromJSON(RequestOptionsJSON requestOptions); - }; - - dictionary CreationOptionsJSON { - required DOMString method = "create"; - required PublicKeyCredentialCreationOptionsJSON options; - }; - - dictionary RequestOptionsJSON { - required DOMString method = "get"; - required PublicKeyCredentialRequestOptionsJSON options; + static PublicKeyCredentialRequestOptions getRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); }; dictionary PublicKeyCredentialCreationOptionsJSON { From 4a904af828443f74bed2759ef98fcb6d05429a8b Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Wed, 23 Mar 2022 13:27:22 -0700 Subject: [PATCH 16/27] Refine definition of `toJSON()` method --- index.bs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 3cd6ab544..b608217c1 100644 --- a/index.bs +++ b/index.bs @@ -1452,10 +1452,13 @@ that are returned to the caller when a new credential is created, or a new asser [=client extension processing=]. : {{PublicKeyCredential/toJSON()}} - :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, a JSON-serialized representation of the instance of - {{PublicKeyCredential}} suitable for submission to a [=[RP]=] server as a payload with `application/json` mimetype. The [=client=] is in - charge of encoding any {{ArrayBuffer}} values using [=base64url encoding=] to generate strings compatible with JSON syntax. {{ArrayBuffer}} - values to be encoded are identified according to the detected type of the instance's `response` property. + :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, that is a JSON-serialized + representation of the instance of {{PublicKeyCredential}} suitable for submission to a [=[RP]=] server as a DOMString + payload with `application/json` mimetype. The [=client=] is in charge of + [serializing values to JSON as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), but must take additional + steps to encode any {{ArrayBuffer}} values to {{DOMString}} values using [=base64url encoding=] to ensure compatibility + with JSON syntax. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's + `response` property. <dl dfn-for=""> <xmp class="idl"> From 078e432f332fb0147b3bd7471ba76ecd611ce998 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Wed, 23 Mar 2022 13:40:29 -0700 Subject: [PATCH 17/27] Move JSON xmp out of PublicKeyCredential dl --- index.bs | 64 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/index.bs b/index.bs index b608217c1..e9d8d0e2c 100644 --- a/index.bs +++ b/index.bs @@ -1459,40 +1459,40 @@ that are returned to the caller when a new credential is created, or a new asser steps to encode any {{ArrayBuffer}} values to {{DOMString}} values using [=base64url encoding=] to ensure compatibility with JSON syntax. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's `response` property. +</dl> - <dl dfn-for=""> - <xmp class="idl"> - typedef DOMString Base64URLString; - typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON; - - dictionary RegistrationResponseJSON { - Base64URLString id; - Base64URLString rawId; - AuthenticatorAttestationResponseJSON response; - DOMString type; - }; - - dictionary AuthenticatorAttestationResponseJSON { - Base64URLString clientDataJSON; - Base64URLString attestationObject; - }; - - dictionary AuthenticationResponseJSON { - Base64URLString id; - Base64URLString rawId; - AuthenticatorAssertionResponseJSON response; - DOMString type; - }; - - dictionary AuthenticatorAssertionResponseJSON { - Base64URLString clientDataJSON; - Base64URLString authenticatorData; - Base64URLString signature; - Base64URLString? userHandle; - }; - -
+ + typedef DOMString Base64URLString; + typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON; + + dictionary RegistrationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAttestationResponseJSON response; + DOMString type; + }; + + dictionary AuthenticatorAttestationResponseJSON { + Base64URLString clientDataJSON; + Base64URLString attestationObject; + }; + dictionary AuthenticationResponseJSON { + Base64URLString id; + Base64URLString rawId; + AuthenticatorAssertionResponseJSON response; + DOMString type; + }; + + dictionary AuthenticatorAssertionResponseJSON { + Base64URLString clientDataJSON; + Base64URLString authenticatorData; + Base64URLString signature; + Base64URLString? userHandle; + }; + + +
: \[[type]] :: The {{PublicKeyCredential}} [=interface object=]'s {{Credential/[[type]]}} [=internal slot=]'s value is the string "`public-key`". From c0c94545f1b58089ebce794786bbcacbb5b9396a Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 13:42:59 -0700 Subject: [PATCH 18/27] Remove required from property with default value --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index e9d8d0e2c..f38c598fe 100644 --- a/index.bs +++ b/index.bs @@ -2453,7 +2453,7 @@ Upon invocation, the [=client=] takes the provided options and returns an identi required Base64URLString challenge; required sequence pubKeyCredParams; unsigned long timeout; - required sequence excludeCredentials = []; + sequence excludeCredentials = []; AuthenticatorSelectionCriteria authenticatorSelection; DOMString attestation = "none"; AuthenticationExtensionsClientInputsJSON extensions; From 22a796cf6392194acafa9ff792deef7ce1e173bb Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Wed, 23 Mar 2022 14:00:27 -0700 Subject: [PATCH 19/27] Split up options methods into two sections --- index.bs | 53 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/index.bs b/index.bs index f38c598fe..3665eca41 100644 --- a/index.bs +++ b/index.bs @@ -2430,44 +2430,34 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic -### Deserialize Registration and Authentication ceremony options - PublicKeyCredential's `optionsFromJSON()` Method ### {#sctn-optionsFromJSON} +### Deserialize Registration ceremony options - PublicKeyCredential's `getCreationOptionsFromJSON()` Method ### {#sctn-getCreationOptionsFromJSON} -
+
-[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for {{CredentialsContainer/create()|navigator.credentials.create()}} to {{PublicKeyCredentialCreationOptions}}, or JSON-compatible serialized representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} to {{PublicKeyCredentialRequestOptions}}. +[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for +{{CredentialsContainer/create()|navigator.credentials.create()}} to {{PublicKeyCredentialCreationOptions}}. -Upon invocation, the [=client=] takes the provided options and returns an identically-structured object with specific strings encoded with [=base64url encoding=] decoded to {{ArrayBuffer}} values according to the corresponding type definition. +Upon invocation, the [=client=] must take the provided options and return an identically-structured object, +making sure to decode to {{ArrayBuffer}} those {{DOMString}} properties that are encoded with [=base64url encoding=] +but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCredentialCreationOptions}}. partial interface PublicKeyCredential { static PublicKeyCredentialCreationOptions getCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); }; - partial interface PublicKeyCredential { - static PublicKeyCredentialRequestOptions getRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); - }; - dictionary PublicKeyCredentialCreationOptionsJSON { required PublicKeyCredentialRpEntity rp; required PublicKeyCredentialUserEntityJSON user; required Base64URLString challenge; required sequence<PublicKeyCredentialParameters> pubKeyCredParams; unsigned long timeout; - sequence<PublicKeyCredentialDescriptorJSON> excludeCredentials = []; + sequence<PublicKeyCredentialDescriptorJSON> excludeCredentials = []; AuthenticatorSelectionCriteria authenticatorSelection; DOMString attestation = "none"; AuthenticationExtensionsClientInputsJSON extensions; }; - dictionary PublicKeyCredentialRequestOptionsJSON { - required Base64URLString challenge; - unsigned long timeout; - DOMString rpId; - sequence<PublicKeyCredentialDescriptorJSON> allowCredentials = []; - DOMString userVerification = "preferred"; - AuthenticationExtensionsClientInputsJSON extensions; - }; - dictionary PublicKeyCredentialUserEntityJSON { required Base64URLString id; required DOMString name; @@ -2497,6 +2487,33 @@ Upon invocation, the [=client=] takes the provided options and returns an identi </div> +### Deserialize Authentication ceremony options - PublicKeyCredential's `getRequestOptionsFromJSON()` Methods ### {#sctn-getRequestOptionsFromJSON} + +<div link-for-hint="WebAuthentication/getRequestOptionsFromJSON"> + +[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} to {{PublicKeyCredentialRequestOptions}}. + +Upon invocation, the [=client=] must take the provided options and return an identically-structured object, +making sure to decode to {{ArrayBuffer}} those {{DOMString}} properties that are encoded with [=base64url encoding=] +but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCredentialRequestOptions}}. + +<xmp class="idl"> + partial interface PublicKeyCredential { + static PublicKeyCredentialRequestOptions getRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); + }; + + dictionary PublicKeyCredentialRequestOptionsJSON { + required Base64URLString challenge; + unsigned long timeout; + DOMString rpId; + sequence<PublicKeyCredentialDescriptorJSON> allowCredentials = []; + DOMString userVerification = "preferred"; + AuthenticationExtensionsClientInputsJSON extensions; + }; + + +
+ ## Authenticator Responses (interface AuthenticatorResponse) ## {#iface-authenticatorresponse} [=Authenticators=] respond to [=[RP]=] requests by returning an object derived from the From 6fa0da70744e1388d058c99cc0ce953b1977765d Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Sun, 17 Apr 2022 10:28:29 -0700 Subject: [PATCH 20/27] Return authenticatorAttachment and transports --- index.bs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/index.bs b/index.bs index 3665eca41..4211d0c2d 100644 --- a/index.bs +++ b/index.bs @@ -1469,18 +1469,21 @@ that are returned to the caller when a new credential is created, or a new asser Base64URLString id; Base64URLString rawId; AuthenticatorAttestationResponseJSON response; + DOMString? authenticatorAttachment; DOMString type; }; dictionary AuthenticatorAttestationResponseJSON { Base64URLString clientDataJSON; Base64URLString attestationObject; + sequence transports; }; dictionary AuthenticationResponseJSON { Base64URLString id; Base64URLString rawId; AuthenticatorAssertionResponseJSON response; + DOMString? authenticatorAttachment; DOMString type; }; From 592271dc169f0f4538034bfff79728ca2a07c2c0 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Sun, 17 Apr 2022 10:29:05 -0700 Subject: [PATCH 21/27] Define clientExtensionResults in toJSON() --- index.bs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/index.bs b/index.bs index 4211d0c2d..68ca492c3 100644 --- a/index.bs +++ b/index.bs @@ -1459,6 +1459,10 @@ that are returned to the caller when a new credential is created, or a new asser steps to encode any {{ArrayBuffer}} values to {{DOMString}} values using [=base64url encoding=] to ensure compatibility with JSON syntax. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's `response` property. + :: |clientExtensionResults| below should be the output of {{PublicKeyCredential/getClientExtensionResults()}}, with any + {{ArrayBuffer}} values encoded to {{DOMString}} values using [=base64url encoding=]. This may include {{ArrayBuffer}} + values from extensions registered in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] + but not defined in [[#sctn-extensions]].
@@ -1470,6 +1474,7 @@ that are returned to the caller when a new credential is created, or a new asser Base64URLString rawId; AuthenticatorAttestationResponseJSON response; DOMString? authenticatorAttachment; + AuthenticationExtensionsClientOutputsJSON clientExtensionResults; DOMString type; }; @@ -1484,6 +1489,7 @@ that are returned to the caller when a new credential is created, or a new asser Base64URLString rawId; AuthenticatorAssertionResponseJSON response; DOMString? authenticatorAttachment; + AuthenticationExtensionsClientOutputsJSON clientExtensionResults; DOMString type; }; @@ -1493,6 +1499,9 @@ that are returned to the caller when a new credential is created, or a new asser Base64URLString signature; Base64URLString? userHandle; }; + + dictionary AuthenticationExtensionsClientOutputsJSON { + };
From 408b323a03168e4636519d769091b1df4fc5307a Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Sun, 17 Apr 2022 22:20:41 -0700 Subject: [PATCH 22/27] Try to support all extension inputs --- index.bs | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/index.bs b/index.bs index 68ca492c3..13474814b 100644 --- a/index.bs +++ b/index.bs @@ -2453,6 +2453,11 @@ Upon invocation, the [=client=] must take the provided options and return an ide making sure to decode to {{ArrayBuffer}} those {{DOMString}} properties that are encoded with [=base64url encoding=] but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCredentialCreationOptions}}. +{{AuthenticationExtensionsClientInputsJSON}} may include extensions registered in the IANA +"WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in [[#sctn-extensions]]. +In either case the [=client=] must decode to {{ArrayBuffer}} those {{DOMString}} values that are encoded with +[=base64url encoding=] but must be {{ArrayBuffer}} values according to the extension's definition. + partial interface PublicKeyCredential { static PublicKeyCredentialCreationOptions getCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); @@ -2483,17 +2488,6 @@ but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCre }; dictionary AuthenticationExtensionsClientInputsJSON { - DOMString appid; - DOMString appidExclude; - boolean uvm; - boolean credProps; - AuthenticationExtensionsLargeBlobInputsJSON largeBlob; - }; - - dictionary AuthenticationExtensionsLargeBlobInputsJSON { - DOMString support; - boolean read; - Base64URLString write; }; From 582b2e2014c7cac6d9582738c4d1758e82b4acf5 Mon Sep 17 00:00:00 2001 From: Matthew Miller Date: Thu, 9 Jun 2022 11:07:50 -0700 Subject: [PATCH 23/27] Incorporate Emil's feedback --- index.bs | 68 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/index.bs b/index.bs index 13474814b..24a548950 100644 --- a/index.bs +++ b/index.bs @@ -1425,7 +1425,7 @@ that are returned to the caller when a new credential is created, or a new asser {{CredentialsContainer/create()}}, this attribute's value will be an {{AuthenticatorAttestationResponse}}, otherwise, the {{PublicKeyCredential}} was created in response to {{CredentialsContainer/get()}}, and this attribute's value will be an {{AuthenticatorAssertionResponse}}. - + : authenticatorAttachment :: This attribute reports the [=authenticator attachment modality=] in effect at the time the {{CredentialsContainer/create()|navigator.credentials.create()}} or @@ -1452,17 +1452,19 @@ that are returned to the caller when a new credential is created, or a new asser [=client extension processing=]. : {{PublicKeyCredential/toJSON()}} - :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, that is a JSON-serialized - representation of the instance of {{PublicKeyCredential}} suitable for submission to a [=[RP]=] server as a DOMString - payload with `application/json` mimetype. The [=client=] is in charge of - [serializing values to JSON as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), but must take additional - steps to encode any {{ArrayBuffer}} values to {{DOMString}} values using [=base64url encoding=] to ensure compatibility - with JSON syntax. {{ArrayBuffer}} values to be encoded are identified according to the detected type of the instance's - `response` property. - :: |clientExtensionResults| below should be the output of {{PublicKeyCredential/getClientExtensionResults()}}, with any - {{ArrayBuffer}} values encoded to {{DOMString}} values using [=base64url encoding=]. This may include {{ArrayBuffer}} - values from extensions registered in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] - but not defined in [[#sctn-extensions]]. + :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, + which are [=JSON types=] mirroring {{PublicKeyCredential}}, suitable for submission to a + [=[RP]=] server as an `application/json` payload. The [=client=] is in charge of + [serializing values to JSON as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), + but MUST take additional steps to first encode any {{ArrayBuffer}} values to {{DOMString}} values + using [=base64url encoding=] to ensure compatibility with JSON syntax. + {{RegistrationResponseJSON/clientExtensionResults|RegistrationResponseJSON.clientExtensionResults}} or + {{AuthenticationResponseJSON/clientExtensionResults|AuthenticationResponseJSON.clientExtensionResults}} + members MUST be set to the output of {{PublicKeyCredential/getClientExtensionResults()}}, + with any {{ArrayBuffer}} values encoded to {{DOMString}} values using + [=base64url encoding=]. This MAY include {{ArrayBuffer}} values from extensions registered + in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not + defined in [[#sctn-extensions]].
@@ -2446,17 +2448,20 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic <div link-for-hint="WebAuthentication/getCreationOptionsFromJSON"> -[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for -{{CredentialsContainer/create()|navigator.credentials.create()}} to {{PublicKeyCredentialCreationOptions}}. +[=[WRPS]=] use this method to convert [=JSON type=] representations of options for +{{CredentialsContainer/create()|navigator.credentials.create()}} into +{{PublicKeyCredentialCreationOptions}}. -Upon invocation, the [=client=] must take the provided options and return an identically-structured object, -making sure to decode to {{ArrayBuffer}} those {{DOMString}} properties that are encoded with [=base64url encoding=] -but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCredentialCreationOptions}}. +Upon invocation, the [=client=] MUST convert the +{{PublicKeyCredential/getCreationOptionsFromJSON(options)/options}} argument into a new, +identically-structured {{PublicKeyCredentialCreationOptions}} object, using [=base64url encoding=] +to decode any {{DOMString}} attributes in {{PublicKeyCredentialCreationOptionsJSON}} that correspond +to [=buffer source type=] attributes in {{PublicKeyCredentialCreationOptions}}. This conversion MUST +extend to any [=client extension inputs=] processed by the [=client=]. -{{AuthenticationExtensionsClientInputsJSON}} may include extensions registered in the IANA -"WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in [[#sctn-extensions]]. -In either case the [=client=] must decode to {{ArrayBuffer}} those {{DOMString}} values that are encoded with -[=base64url encoding=] but must be {{ArrayBuffer}} values according to the extension's definition. +{{AuthenticationExtensionsClientInputsJSON}} MAY include extensions registered in the IANA +"WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in +[[#sctn-extensions]]. <xmp class="idl"> partial interface PublicKeyCredential { @@ -2497,11 +2502,20 @@ In either case the [=client=] must decode to {{ArrayBuffer}} those {{DOMString}} <div link-for-hint="WebAuthentication/getRequestOptionsFromJSON"> -[=[WRPS]=] use this method to convert JSON-compatible serialized representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} to {{PublicKeyCredentialRequestOptions}}. +[=[WRPS]=] use this method to convert [=JSON type=] representations of options for +{{CredentialsContainer/get()|navigator.credentials.get()}} into +{{PublicKeyCredentialRequestOptions}}. + +Upon invocation, the [=client=] MUST convert the +{{PublicKeyCredential/getRequestOptionsFromJSON(options)/options}} argument into a new, +identically-structured {{PublicKeyCredentialRequestOptions}} object, using [=base64url encoding=] +to decode any {{DOMString}} attributes in {{PublicKeyCredentialRequestOptionsJSON}} that correspond +to [=buffer source type=] attributes in {{PublicKeyCredentialRequestOptions}}. This conversion MUST +extend to any [=client extension inputs=] processed by the [=client=]. -Upon invocation, the [=client=] must take the provided options and return an identically-structured object, -making sure to decode to {{ArrayBuffer}} those {{DOMString}} properties that are encoded with [=base64url encoding=] -but must be {{ArrayBuffer}} values according to the definition of {{PublicKeyCredentialRequestOptions}}. +{{AuthenticationExtensionsClientInputsJSON}} MAY include extensions registered in the IANA +"WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in +[[#sctn-extensions]]. <xmp class="idl"> partial interface PublicKeyCredential { @@ -3223,7 +3237,7 @@ Note: The {{CollectedClientData}} may be extended in the future. Therefore it's required DOMString type; required DOMString challenge; required DOMString origin; - boolean crossOrigin; + boolean crossOrigin; }; dictionary TokenBinding { @@ -3255,7 +3269,7 @@ Note: The {{CollectedClientData}} may be extended in the future. Therefore it's : \[RESERVED] <dfn dfn>tokenBinding</dfn> :: This OPTIONAL member contains information about the state of the [=Token Binding=] protocol [[!TokenBinding]] used when communicating with the [=[RP]=]. Its absence indicates that the client doesn't support token binding - + Note: While [=Token Binding=] was present in Level 1 and Level 2 of WebAuthn, its use is not expected in Level 3. The {{CollectedClientData/tokenBinding}} field is reserved so that it will not be reused for a different purpose. <div dfn-type="dict-member" dfn-for="TokenBinding"> From ae3a7d43807f5fa979b5741048faf3ffc3d1e8a9 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Thu, 9 Jun 2022 12:34:26 -0700 Subject: [PATCH 24/27] Rename options methods from `get-` to `parse-` --- index.bs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/index.bs b/index.bs index 24a548950..ee7ee6cc8 100644 --- a/index.bs +++ b/index.bs @@ -2444,16 +2444,16 @@ Note: Invoking this method from a [=browsing context=] where the [=Web Authentic </div> -### Deserialize Registration ceremony options - PublicKeyCredential's `getCreationOptionsFromJSON()` Method ### {#sctn-getCreationOptionsFromJSON} +### Deserialize Registration ceremony options - PublicKeyCredential's `parseCreationOptionsFromJSON()` Method ### {#sctn-parseCreationOptionsFromJSON} -<div link-for-hint="WebAuthentication/getCreationOptionsFromJSON"> +<div link-for-hint="WebAuthentication/parseCreationOptionsFromJSON"> [=[WRPS]=] use this method to convert [=JSON type=] representations of options for {{CredentialsContainer/create()|navigator.credentials.create()}} into {{PublicKeyCredentialCreationOptions}}. Upon invocation, the [=client=] MUST convert the -{{PublicKeyCredential/getCreationOptionsFromJSON(options)/options}} argument into a new, +{{PublicKeyCredential/parseCreationOptionsFromJSON(options)/options}} argument into a new, identically-structured {{PublicKeyCredentialCreationOptions}} object, using [=base64url encoding=] to decode any {{DOMString}} attributes in {{PublicKeyCredentialCreationOptionsJSON}} that correspond to [=buffer source type=] attributes in {{PublicKeyCredentialCreationOptions}}. This conversion MUST @@ -2465,7 +2465,7 @@ extend to any [=client extension inputs=] processed by the [=client=]. <xmp class="idl"> partial interface PublicKeyCredential { - static PublicKeyCredentialCreationOptions getCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); + static PublicKeyCredentialCreationOptions parseCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); }; dictionary PublicKeyCredentialCreationOptionsJSON { @@ -2498,16 +2498,16 @@ extend to any [=client extension inputs=] processed by the [=client=]. </div> -### Deserialize Authentication ceremony options - PublicKeyCredential's `getRequestOptionsFromJSON()` Methods ### {#sctn-getRequestOptionsFromJSON} +### Deserialize Authentication ceremony options - PublicKeyCredential's `parseRequestOptionsFromJSON()` Methods ### {#sctn-parseRequestOptionsFromJSON} -<div link-for-hint="WebAuthentication/getRequestOptionsFromJSON"> +<div link-for-hint="WebAuthentication/parseRequestOptionsFromJSON"> [=[WRPS]=] use this method to convert [=JSON type=] representations of options for {{CredentialsContainer/get()|navigator.credentials.get()}} into {{PublicKeyCredentialRequestOptions}}. Upon invocation, the [=client=] MUST convert the -{{PublicKeyCredential/getRequestOptionsFromJSON(options)/options}} argument into a new, +{{PublicKeyCredential/parseRequestOptionsFromJSON(options)/options}} argument into a new, identically-structured {{PublicKeyCredentialRequestOptions}} object, using [=base64url encoding=] to decode any {{DOMString}} attributes in {{PublicKeyCredentialRequestOptionsJSON}} that correspond to [=buffer source type=] attributes in {{PublicKeyCredentialRequestOptions}}. This conversion MUST @@ -2519,7 +2519,7 @@ extend to any [=client extension inputs=] processed by the [=client=]. <xmp class="idl"> partial interface PublicKeyCredential { - static PublicKeyCredentialRequestOptions getRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); + static PublicKeyCredentialRequestOptions parseRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); }; dictionary PublicKeyCredentialRequestOptionsJSON { From b1b5fd1fd6ed629b4a65b9d143b25f4ade3ca6f4 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Thu, 9 Jun 2022 20:38:09 -0700 Subject: [PATCH 25/27] Incorporate @emlun's copy advice --- index.bs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index ee7ee6cc8..ee02c31b3 100644 --- a/index.bs +++ b/index.bs @@ -1455,16 +1455,21 @@ that are returned to the caller when a new credential is created, or a new asser :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, which are [=JSON types=] mirroring {{PublicKeyCredential}}, suitable for submission to a [=[RP]=] server as an `application/json` payload. The [=client=] is in charge of - [serializing values to JSON as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), + [serializing values to JSON types as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), but MUST take additional steps to first encode any {{ArrayBuffer}} values to {{DOMString}} values - using [=base64url encoding=] to ensure compatibility with JSON syntax. + using [=base64url encoding=]. + + The {{RegistrationResponseJSON/clientExtensionResults|RegistrationResponseJSON.clientExtensionResults}} or {{AuthenticationResponseJSON/clientExtensionResults|AuthenticationResponseJSON.clientExtensionResults}} - members MUST be set to the output of {{PublicKeyCredential/getClientExtensionResults()}}, + member MUST be set to the output of {{PublicKeyCredential/getClientExtensionResults()}}, with any {{ArrayBuffer}} values encoded to {{DOMString}} values using [=base64url encoding=]. This MAY include {{ArrayBuffer}} values from extensions registered in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in [[#sctn-extensions]]. + + The {{AuthenticatorAttestationResponseJSON/transports|AuthenticatorAttestationResponseJSON.transports}} + member MUST be set to the output of {{AuthenticatorAttestationResponse/getTransports()}}. </dl> <xmp class="idl"> @@ -2457,7 +2462,7 @@ Upon invocation, the [=client=] MUST convert the identically-structured {{PublicKeyCredentialCreationOptions}} object, using [=base64url encoding=] to decode any {{DOMString}} attributes in {{PublicKeyCredentialCreationOptionsJSON}} that correspond to [=buffer source type=] attributes in {{PublicKeyCredentialCreationOptions}}. This conversion MUST -extend to any [=client extension inputs=] processed by the [=client=]. +also apply to any [=client extension inputs=] processed by the [=client=]. {{AuthenticationExtensionsClientInputsJSON}} MAY include extensions registered in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in @@ -2511,7 +2516,7 @@ Upon invocation, the [=client=] MUST convert the identically-structured {{PublicKeyCredentialRequestOptions}} object, using [=base64url encoding=] to decode any {{DOMString}} attributes in {{PublicKeyCredentialRequestOptionsJSON}} that correspond to [=buffer source type=] attributes in {{PublicKeyCredentialRequestOptions}}. This conversion MUST -extend to any [=client extension inputs=] processed by the [=client=]. +also apply to any [=client extension inputs=] processed by the [=client=]. {{AuthenticationExtensionsClientInputsJSON}} MAY include extensions registered in the IANA "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in From 88bd8fbd8c8da7e8d15e2fe64f82af08f6a41f47 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Fri, 10 Jun 2022 11:23:26 -0700 Subject: [PATCH 26/27] Attempt to define rules for when encoding fails --- index.bs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index ee02c31b3..829125ab2 100644 --- a/index.bs +++ b/index.bs @@ -1453,7 +1453,7 @@ that are returned to the caller when a new credential is created, or a new asser : {{PublicKeyCredential/toJSON()}} :: This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}}, - which are [=JSON types=] mirroring {{PublicKeyCredential}}, suitable for submission to a + which are [=JSON type=] representations mirroring {{PublicKeyCredential}}, suitable for submission to a [=[RP]=] server as an `application/json` payload. The [=client=] is in charge of [serializing values to JSON types as usual](https://webidl.spec.whatwg.org/#idl-tojson-operation), but MUST take additional steps to first encode any {{ArrayBuffer}} values to {{DOMString}} values @@ -2468,6 +2468,10 @@ also apply to any [=client extension inputs=] processed by the [=client=]. "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in [[#sctn-extensions]]. +If the [=client=] encounters any issues parsing any of the [=JSON type=] representations then it +MUST return an error code equivalent to "{{EncodingError}}" with a description of the incompatible +value and terminate the operation. + <xmp class="idl"> partial interface PublicKeyCredential { static PublicKeyCredentialCreationOptions parseCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options); @@ -2522,6 +2526,10 @@ also apply to any [=client extension inputs=] processed by the [=client=]. "WebAuthn Extension Identifiers" registry [[!IANA-WebAuthn-Registries]] but not defined in [[#sctn-extensions]]. +If the [=client=] encounters any issues parsing any of the [=JSON type=] representations then it +MUST return an error code equivalent to "{{EncodingError}}" with a description of the incompatible +value and terminate the operation. + <xmp class="idl"> partial interface PublicKeyCredential { static PublicKeyCredentialRequestOptions parseRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options); From 12e50712a5a02b0ebab7a22c77e7a6760e160865 Mon Sep 17 00:00:00 2001 From: Matthew Miller <mmiller@duosecurity.com> Date: Mon, 20 Jun 2022 12:48:53 -0700 Subject: [PATCH 27/27] Incorporate feedback on wording for exceptions --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 829125ab2..bdac7ebdf 100644 --- a/index.bs +++ b/index.bs @@ -2469,7 +2469,7 @@ also apply to any [=client extension inputs=] processed by the [=client=]. [[#sctn-extensions]]. If the [=client=] encounters any issues parsing any of the [=JSON type=] representations then it -MUST return an error code equivalent to "{{EncodingError}}" with a description of the incompatible +MUST throw an "{{EncodingError}}" {{DOMException}} with a description of the incompatible value and terminate the operation. <xmp class="idl"> @@ -2527,7 +2527,7 @@ also apply to any [=client extension inputs=] processed by the [=client=]. [[#sctn-extensions]]. If the [=client=] encounters any issues parsing any of the [=JSON type=] representations then it -MUST return an error code equivalent to "{{EncodingError}}" with a description of the incompatible +MUST throw an "{{EncodingError}}" {{DOMException}} with a description of the incompatible value and terminate the operation. <xmp class="idl">