From 1fc8906a20bb0698d68de3fbe55ebd109617b3bd Mon Sep 17 00:00:00 2001 From: Mike Jones Date: Wed, 31 Jan 2018 10:34:05 -0800 Subject: [PATCH] Strongly type client extension inputs and outputs (#765) * Strongly type client extension inputs and outputs * Remove the unused AuthenticationExtensionsAuthenticatorOutputs typedef * Capitalize typedef names UvmEntry and UvmEntries --- index.bs | 270 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 141 insertions(+), 129 deletions(-) diff --git a/index.bs b/index.bs index 9c03ae0ae..e34b7b510 100644 --- a/index.bs +++ b/index.bs @@ -598,7 +598,7 @@ that are returned to the caller when a new credential is created, or a new asser interface PublicKeyCredential : Credential { [SameObject] readonly attribute ArrayBuffer rawId; [SameObject] readonly attribute AuthenticatorResponse response; - AuthenticationExtensions getClientExtensionResults(); + AuthenticationExtensionsClientOutputs getClientExtensionResults(); };
@@ -928,7 +928,7 @@ When this method is invoked, the user agent MUST execute the following algorithm :: whose value is the value of |options|.{{MakePublicKeyCredentialOptions/attestation}}. : clientExtensionResults - :: whose value is an {{AuthenticationExtensions}} object containing [=extension identifier=] → + :: whose value is an {{AuthenticationExtensionsClientOutputs}} object containing [=extension identifier=] → [=client extension output=] entries. The entries are created by running each extension's [=client extension processing=] algorithm to create the [=client extension outputs=], for each [=client extension=] in {{AuthenticatorResponse/clientDataJSON}}.clientExtensions. @@ -1288,7 +1288,7 @@ When this method is invoked, the user agent MUST execute the following algorithm the returned [=user handle=]. Otherwise, set the value of [=userHandleResult=] to null. : clientExtensionResults - :: whose value is an {{AuthenticationExtensions}} object containing [=extension identifier=] → + :: whose value is an {{AuthenticationExtensionsClientOutputs}} object containing [=extension identifier=] → [=client extension output=] entries. The entries are created by running each extension's [=client extension processing=] algorithm to create the [=client extension outputs=], for each [=client extension=] in {{AuthenticatorResponse/clientDataJSON}}.clientExtensions. @@ -1536,7 +1536,7 @@ optionally evidence of [=user consent=] to a specific transaction. sequence excludeCredentials = []; AuthenticatorSelectionCriteria authenticatorSelection; AttestationConveyancePreference attestation = "none"; - AuthenticationExtensions extensions; + AuthenticationExtensionsClientInputs extensions; };
@@ -1790,7 +1790,7 @@ an assertion. Its {{PublicKeyCredentialRequestOptions/challenge}} member MUST be USVString rpId; sequence allowCredentials = []; UserVerificationRequirement userVerification = "preferred"; - AuthenticationExtensions extensions; + AuthenticationExtensionsClientInputs extensions; }; @@ -1853,15 +1853,33 @@ SHOULD be aborted. See [WHATWG HTML WG Issue #2711](https://github.com/whatwg/html/issues/2711) for more details. -## Authentication Extensions (typedef AuthenticationExtensions) ## {#iface-authentication-extensions} +## Authentication Extensions Client Inputs (typedef AuthenticationExtensionsClientInputs) ## {#iface-authentication-extensions-client-inputs} -
-    typedef record<DOMString, any>       AuthenticationExtensions;
-
+ + dictionary AuthenticationExtensionsClientInputs { + }; + + +This is a dictionary containing the [=client extension input=] values for zero or more WebAuthn extensions, as defined in [[#extensions]]. + + +## Authentication Extensions Client Outputs (typedef AuthenticationExtensionsClientOutputs) ## {#iface-authentication-extensions-client-outputs} + + + dictionary AuthenticationExtensionsClientOutputs { + }; + + +This is a dictionary containing the [=client extension output=] values for zero or more WebAuthn extensions, as defined in [[#extensions]]. -This is a dictionary containing zero or more WebAuthn extensions, as defined in [[#extensions]]. -An AuthenticationExtensions instance can contain either [=client extensions=] or [=authenticator extensions=], depending upon -context. + +## Authentication Extensions Authenticator Inputs (typedef AuthenticationExtensionsAuthenticatorInputs) ## {#iface-authentication-extensions-authenticator-inputs} + + + typedef record<DOMString, DOMString> AuthenticationExtensionsAuthenticatorInputs; + + +This is a dictionary containing the [=authenticator extension input=] values for zero or more WebAuthn extensions, as defined in [[#extensions]]. ## Supporting Data Structures ## {#supporting-data-structures} @@ -1882,8 +1900,8 @@ following Web IDL. required DOMString challenge; required DOMString origin; DOMString tokenBindingId; - AuthenticationExtensions clientExtensions; - AuthenticationExtensions authenticatorExtensions; + AuthenticationExtensionsClientInputs clientExtensions; + AuthenticationExtensionsAuthenticatorInputs authenticatorExtensions; }; @@ -3538,63 +3556,6 @@ identifiers=] as keys, and the [=CBOR=] authenticator extension output - var assertionPromise = - navigator.credentials.get({ - publicKey: { - // The challenge must be produced by the server, see the Security Considerations - challenge: new Uint8Array([11,103,35 /* 29 more random bytes generated by the server */]), - allowCredentials: [], /* Empty filter */ - extensions: { 'webauthnExample_geo': true } - } - }); - - -The extension also requires the client to set the authenticator parameter to the fixed value `true`. - -The extension requires the authenticator to specify its geolocation in the [=authenticator extension output=], if known. The -extension e.g. specifies that the location shall be encoded as a two-element array of floating point numbers, encoded with CBOR. -An authenticator does this by including it in the [=authenticator data=]. As an example, [=authenticator data=] might be as -follows (notation taken from [[RFC7049]]): - -
-    81 (hex)                                    -- Flags, ED and UP both set.
-    20 05 58 1F                                 -- Signature counter
-    A1                                          -- CBOR map of one element
-        73                                      -- Key 1: CBOR text string of 19 bytes
-            77 65 62 61 75 74 68 6E 45 78 61
-            6D 70 6C 65 5F 67 65 6F             -- "webauthnExample_geo" [=UTF-8 encoded=] string
-        82                                      -- Value 1: CBOR array of two elements
-            FA 42 82 1E B3                      -- Element 1: Latitude as CBOR encoded float
-            FA C1 5F E3 7F                      -- Element 2: Longitude as CBOR encoded float
-
- -The extension defines the [=client extension output=] to be the geolocation information, if known, as a GeoJSON [[GeoJSON]] -point. The client constructs the following [=client data=]: - -
-    {
-        ...,
-        'extensions': {
-            'webauthnExample_geo': {
-                'type': 'Point',
-                'coordinates': [65.059962, -13.993041]
-            }
-        }
-    }
-
- # Defined Extensions # {#sctn-defined-extensions} @@ -3621,6 +3582,11 @@ JavaScript APIs. : Client extension input :: A single USVString specifying a FIDO |AppID|. + + partial dictionary AuthenticationExtensionsClientInputs { + USVString appid; + }; + : Client extension processing :: 1. If present in a {{CredentialsContainer/create()}} call, return a @@ -3641,7 +3607,12 @@ JavaScript APIs. parameter of [=authenticatorGetAssertion=]. : Client extension output -:: Returns the JSON value `true` to indicate to the RP that the extension was acted upon. +:: Returns the value `true` to indicate to the RP that the extension was acted upon. + + partial dictionary AuthenticationExtensionsClientOutputs { + boolean appid; + }; + : Authenticator extension input :: None. @@ -3663,12 +3634,22 @@ This [=registration extension=] and [=authentication extension=] allows for a si : Client extension input :: A single USVString prompt. + + partial dictionary AuthenticationExtensionsClientInputs { + USVString txAuthSimple; + }; + : Client extension processing :: None, except creating the authenticator extension input from the client extension input. : Client extension output -:: Returns the authenticator extension output string UTF-8 decoded into a USVString +:: Returns the authenticator extension output string UTF-8 decoded into a USVString. + + partial dictionary AuthenticationExtensionsClientOutputs { + USVString txAuthSimple; + }; + : Authenticator extension input :: The client extension input encoded as a CBOR text string (major type 3). @@ -3690,18 +3671,27 @@ as well. This allows authenticators without a font rendering engine to be used a : Client extension input :: A JavaScript object defined as follows: - 
+    
     dictionary txAuthGenericArg {
         required USVString contentType;    // MIME-Type of the content, e.g., "image/png"
         required ArrayBuffer content;
     };
-    </pre>
+
+    partial dictionary AuthenticationExtensionsClientInputs {
+      txAuthGenericArg txAuthGeneric;
+    };
+    
 
 : Client extension processing
 :: None, except creating the authenticator extension input from the client extension input.
 
 : Client extension output
-:: Returns the base64url encoding of the authenticator extension output value as a USVString
+:: Returns the authenticator extension output value as an ArrayBuffer.
+    
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      ArrayBuffer txAuthGeneric;
+    };
+    
 
 : Authenticator extension input
 :: The client extension input encoded as a CBOR map.
@@ -3729,17 +3719,22 @@ creation.
 :: A sequence of AAGUIDs:
 
     
-        typedef sequence<AAGUID>      AuthenticatorSelectionList;
+    typedef sequence<AAGUID> AuthenticatorSelectionList;
+
+    partial dictionary AuthenticationExtensionsClientInputs {
+      AuthenticatorSelectionList authnSel;
+    };
     
 
+
     Each AAGUID corresponds to an authenticator model that is acceptable to the [=[RP]=] for this credential creation. The
     list is ordered by decreasing preference.
 
     An AAGUID is defined as an array containing the globally unique identifier of the authenticator model being sought.
 
-    
+    
         typedef BufferSource      AAGUID;
-    </pre>
+    
 
 : Client extension processing
 :: This extension can only be used during {{CredentialsContainer/create()}}. If the client supports the Authenticator Selection
@@ -3748,7 +3743,12 @@ creation.
     available authenticators to generate the credential.
 
 : Client extension output
-:: Returns the JSON value `true` to indicate to the RP that the extension was acted upon
+:: Returns the value `true` to indicate to the RP that the extension was acted upon.
+    
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      boolean authnSel;
+    };
+    
 
 : Authenticator extension input
 :: None.
@@ -3768,12 +3768,24 @@ This [=registration extension=] enables the [=[RP]=] to determine which extensio
 
 : Client extension input
 :: The Boolean value `true` to indicate that this extension is requested by the [=[RP]=].
+    
+    partial dictionary AuthenticationExtensionsClientInputs {
+      boolean exts;
+    };
+    
 
 : Client extension processing
 :: None, except creating the authenticator extension input from the client extension input.
 
 : Client extension output
-:: Returns the list of supported extensions as a JSON array of [=extension identifier=] strings
+:: Returns the list of supported extensions as an array of [=extension identifier=] strings.
+    
+    typedef sequence<USVString> AuthenticationExtensionsSupported;
+
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      AuthenticationExtensionsSupported exts;
+    };
+    
 
 : Authenticator extension input
 :: The Boolean value `true`, encoded in CBOR (major type 7, value 21).
@@ -3783,7 +3795,7 @@ This [=registration extension=] enables the [=[RP]=] to determine which extensio
     defined below. This extension can be added to attestation objects.
 
 : Authenticator extension output
-:: The SupportedExtensions extension is a list (CBOR array) of [=extension identifier=] ([=UTF-8 encoded=] strings).
+:: The SupportedExtensions extension is a list (CBOR array) of [=extension identifier=] ([=UTF-8 encoded=]) strings.
 
 
 ## User Verification Index Extension (uvi) ## {#sctn-uvi-extension}
@@ -3795,12 +3807,22 @@ This [=registration extension=] and [=authentication extension=] enables use of
 
 : Client extension input
 :: The Boolean value `true` to indicate that this extension is requested by the [=[RP]=].
+    
+    partial dictionary AuthenticationExtensionsClientInputs {
+      boolean uvi;
+    };
+    
 
 : Client extension processing
 :: None, except creating the authenticator extension input from the client extension input.
 
 : Client extension output
-:: Returns a USVString containing the base64url encoding of the authenticator extension output
+:: Returns the authenticator extension output as an ArrayBuffer.
+    
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      ArrayBuffer uvi;
+    };
+    
 
 : Authenticator extension input
 :: The Boolean value `true`, encoded in CBOR (major type 7, value 21).
@@ -3835,11 +3857,10 @@ This [=registration extension=] and [=authentication extension=] enables use of
             63                                      -- Key 1: CBOR text string of 3 bytes
                 75 76 69                            -- "uvi" [=UTF-8 encoded=] string
             58 20                                   -- Value 1: CBOR byte string with 0x20 bytes
-                00 43 B8 E3 BE 27 95 8C             -- the UVI value itself
-                28 D5 74 BF 46 8A 85 CF
-                46 9A 14 F0 E5 16 69 31
-                DA 4B CF FF C1 BB 11 32
-                82
+                43 B8 E3 BE 27 95 8C 28             -- the UVI value itself
+                D5 74 BF 46 8A 85 CF 46
+                9A 14 F0 E5 16 69 31 DA
+                4B CF FF C1 BB 11 32 82
     

 
 ## Location Extension (loc) ## {#sctn-location-extension}
@@ -3852,6 +3873,11 @@ WebAuthn [=[RP]=].
 
 : Client extension input
 :: The Boolean value `true` to indicate that this extension is requested by the [=[RP]=].
+    
+    partial dictionary AuthenticationExtensionsClientInputs {
+      boolean loc;
+    };
+    
 
 : Client extension processing
 :: None, except creating the authenticator extension input from the client extension input.
@@ -3859,52 +3885,25 @@ WebAuthn [=[RP]=].
 : Client extension output
 :: Returns a JavaScript object that encodes the location information in the authenticator extension output as a Coordinates value,
     as defined by [The W3C Geolocation API Specification](https://dev.w3.org/geo/api/spec-source.html#coordinates_interface).
+    
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      Coordinates loc;
+    };
+    
 
 : Authenticator extension input
 :: The Boolean value `true`, encoded in CBOR (major type 7, value 21).
 
 : Authenticator extension processing
-:: If the [=authenticator=] does not support the extension, then the authenticator MUST ignore the extension request.
-    If the [=authenticator=] accepts the extension, then the authenticator SHOULD only add this extension data to a packed
-    attestation or assertion.
+:: Determine the Geolocation value.
 
 : Authenticator extension output
-:: If the [=authenticator=] accepts the extension request, then [=authenticator extension output=] SHOULD provide location data
-    in the form of a CBOR-encoded map, with the first value being the [=extension identifier=] and the second being an array of
-    returned values. The array elements SHOULD be derived from (key,value) pairings for each location attribute that the
-    [=authenticator=] supports. The following is an example of [=authenticator data=] where the returned array is comprised of a
-    {longitude, latitude, altitude} triplet, following the coordinate representation defined in [The W3C Geolocation API
-    Specification](https://dev.w3.org/geo/api/spec-source.html#coordinates_interface).
-
-    
-    CDDL:
-      {
-       loc: positionCoordinates,
-      }    
-      positionCoordinates = [
-         latitude: float64,
-         longitude: float64,
-         altitude: float64
-         ]
-     CBOR Example:
-        ...                                         -- [=RP ID=] hash (32 bytes)
-        81                                          -- UP and ED set
-        00 00 00 01                                 -- (initial) signature counter
-        ...                                         -- all public key alg etc.
-        A1                                          -- extension: CBOR map of one element
-            63                                      -- Value 1: CBOR text string of 3 bytes
-                6C 6F 63                            -- "loc" [=UTF-8 encoded=] string
-            86                                      -- Value 2: array of 6 elements
-                68                  -- Element 1:  CBOR text string of 8 bytes
-                   6C 61 74 69 74 75 64 65          -- “latitude” [=UTF-8 encoded=] string
-                FB ...                  -- Element 2:  Latitude as CBOR encoded double-precision float
-                69                  -- Element 3:  CBOR text string of 9 bytes
-                   6C 6F 6E 67 69 74 75 64 65       -- “longitude” [=UTF-8 encoded=] string
-                FB ...                  -- Element 4:  Longitude as CBOR encoded double-precision float
-                68                  -- Element 5:  CBOR text string of 8 bytes
-                  61 6C 74 69 74 75 64 65           -- “altitude” [=UTF-8 encoded=] string
-                FB ...                  -- Element 6:  Altitude as CBOR encoded double-precision float
-    

+:: A 
+    [The W3C Geolocation API Specification](https://dev.w3.org/geo/api/spec-source.html#coordinates_interface)
+    Coordinates record encoded as a CBOR map.
+    Values represented by the "double" type in JavaScript are represented as 64-bit CBOR floating point numbers.
+    Per the Geolocation specification, the "latitude", "longitude", and "accuracy" values are required
+    and other values such as "altitude" are optional.
 
 ## User Verification Method Extension (uvm) ## {#sctn-uvm-extension}
 
@@ -3914,13 +3913,26 @@ This [=registration extension=] and [=authentication extension=] enables use of
 :: `uvm`
 
 : Client extension input
-:: The Boolean value true to indicate that this extension is requested by the WebAuthn Relying Party.
+:: The Boolean value `true` to indicate that this extension is requested by the [=[RP]=].
+    
+    partial dictionary AuthenticationExtensionsClientInputs {
+      boolean uvm;
+    };
+    
 
 : Client extension processing
 :: None, except creating the authenticator extension input from the client extension input.
 
 : Client extension output
-:: Returns a JSON array of 3-element arrays of numbers that encodes the factors in the authenticator extension output
+:: Returns a JSON array of 3-element arrays of numbers that encodes the factors in the authenticator extension output.
+    
+    typedef sequence<unsigned long> UvmEntry;
+    typedef sequence<UvmEntry> UvmEntries;
+
+    partial dictionary AuthenticationExtensionsClientOutputs {
+      UvmEntries uvm;
+    };
+    
 
 : Authenticator extension input
 :: The Boolean value `true`, encoded in CBOR (major type 7, value 21).