Skip to content

Commit a133711

Browse files
authored
Substitute enum types in dictionaries with DOMStrings (#1392)
* Update PublicKeyCredentialCreationOptions * Update PublicKeyCredentialRequestOptions * Update for PublicKeyCredential/transports * Update for AuthenticatorSelectionCriteria * Update for PublicKeyCredentialDescriptor * Update for TokenBinding * Update for PublicKeyCredentialParameters * Updates per @agl's review comments * Use the same 'ignore unknown values' language, which is used 8 times already in the document * Update ResidentKeyRequirement to be a DOMString, too. * Address @equalsJeffH's #1392 (comment) and fix linking to infra:map/exists (which was unused) * Address @equalsJeffH - Add 2.1.1 "Enumerations as DOMString Types" Addresses #1392 (review) by adding a new conformance section and referring to it at the description of each enumeration type.
1 parent f10427d commit a133711

File tree

1 file changed

+43
-21
lines changed

1 file changed

+43
-21
lines changed

‎index.bs

+43-21
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,7 @@ spec:html; type:dfn; for:environment settings object; text:global object
302302
spec:infra; type:dfn; for:/; text:set
303303
spec:infra; type:dfn; text:list
304304
spec:infra; type:dfn; for:struct; text:item
305-
spec:infra; type:dfn; for:map-exists; text:exists
305+
spec:infra; type:dfn; for:map; text:exists
306306
spec:url; type:dfn; text:domain
307307
spec:url; type:dfn; for:url; text:host
308308
spec:url; type:dfn; text:valid domain;
@@ -806,6 +806,16 @@ would be obtained by the specification's algorithms.
806806
A conforming User Agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the
807807
“Web IDL” specification. [[!WebIDL]]
808808

809+
### Enumerations as DOMString types ### {#sct-domstring-backwards-compatibility}
810+
811+
Enumeration types are not referenced by other parts of the Web IDL because that
812+
would preclude other values from being used without updating this specification
813+
and its implementations. It is important for backwards compatibility that
814+
[=client platforms=] and [=[RPS]=] handle unknown values. Enumerations for this
815+
specification exist here for documentation and as a registry. Where the
816+
enumerations are represented elsewhere, they are typed as {{DOMString}}s, for
817+
example in {{PublicKeyCredentialDescriptor/transports}}.
818+
809819
## Authenticators ## {#sctn-conforming-authenticators}
810820

811821
A [=[WAA]=] MUST provide the operations defined by [[#sctn-authenticator-model]], and those operations MUST behave as
@@ -1826,7 +1836,7 @@ a numbered step. If outdented, it (today) is rendered either as a bullet in the
18261836
:: |attestationObject|
18271837

18281838
: {{AuthenticatorAttestationResponse/[[transports]]}}
1829-
:: A sequence of zero or more unique {{DOMString}}s, in lexicographical order, that the |authenticator| is believed to support. The values SHOULD be members of {{AuthenticatorTransport}}.
1839+
:: A sequence of zero or more unique {{DOMString}}s, in lexicographical order, that the |authenticator| is believed to support. The values SHOULD be members of {{AuthenticatorTransport}}, but [=client platforms=] MUST ignore unknown values.
18301840

18311841
If a user agent does not wish to divulge this information it MAY substitute an arbitrary sequence designed to preserve privacy. This sequence MUST still be valid, i.e. lexicographically sorted and free of duplicates. For example, it may use the empty sequence. Either way, in this case the user agent takes the risk that [=[RP]=] behavior may be suboptimal.
18321842

@@ -2354,7 +2364,7 @@ during registration.
23542364
:: This operation returns the {{COSEAlgorithmIdentifier}} of the new credential. See [[#sctn-public-key-easy]].
23552365

23562366
: <dfn>\[[transports]]</dfn>
2357-
:: This [=internal slot=] contains a sequence of zero or more unique {{DOMString}}s in lexicographical order. These values are the transports that the [=authenticator=] is believed to support, or an empty sequence if the information is unavailable. The values SHOULD be members of {{AuthenticatorTransport}} but [=[RPS]=] MUST accept unknown values.
2367+
:: This [=internal slot=] contains a sequence of zero or more unique {{DOMString}}s in lexicographical order. These values are the transports that the [=authenticator=] is believed to support, or an empty sequence if the information is unavailable. The values SHOULD be members of {{AuthenticatorTransport}} but [=[RPS]=] MUST ignore unknown values.
23582368
</div>
23592369

23602370
#### Easily accessing credential data #### {#sctn-public-key-easy}
@@ -2413,7 +2423,7 @@ optionally evidence of [=user consent=] to a specific transaction.
24132423

24142424
<xmp class="idl">
24152425
dictionary PublicKeyCredentialParameters {
2416-
required PublicKeyCredentialType type;
2426+
required DOMString type;
24172427
required COSEAlgorithmIdentifier alg;
24182428
};
24192429
</xmp>
@@ -2422,7 +2432,7 @@ optionally evidence of [=user consent=] to a specific transaction.
24222432
This dictionary is used to supply additional parameters when creating a new credential.
24232433

24242434
: <dfn>type</dfn>
2425-
:: This member specifies the type of credential to be created.
2435+
:: This member specifies the type of credential to be created. The value SHOULD be a member of {{PublicKeyCredentialType}} but [=client platforms=] MUST ignore unknown values, ignoring any {{PublicKeyCredentialParameters}} with an unknown {{PublicKeyCredentialParameters/type}}.
24262436

24272437
: <dfn>alg</dfn>
24282438
:: This member specifies the cryptographic signature algorithm with which the newly generated credential will be used, and
@@ -2493,7 +2503,7 @@ optionally evidence of [=user consent=] to a specific transaction.
24932503
: <dfn>attestation</dfn>
24942504
:: This member is intended for use by [=[RPS]=] that wish to express their preference for [=attestation conveyance=].
24952505
Its values SHOULD be members of {{AttestationConveyancePreference}}.
2496-
[=Client platforms=] MUST ignore unknown values.
2506+
[=Client platforms=] MUST ignore unknown values, treating an unknown value as if the [=map/exist|member does not exist=].
24972507
Its default value is "none".
24982508

24992509
: <dfn>extensions</dfn>
@@ -2620,17 +2630,17 @@ attributes.
26202630

26212631
<xmp class="idl">
26222632
dictionary AuthenticatorSelectionCriteria {
2623-
AuthenticatorAttachment authenticatorAttachment;
2633+
DOMString authenticatorAttachment;
26242634
boolean requireResidentKey = false;
2625-
ResidentKeyRequirement residentKey;
2626-
UserVerificationRequirement userVerification = "preferred";
2635+
DOMString residentKey;
2636+
DOMString userVerification = "preferred";
26272637
};
26282638
</xmp>
26292639

26302640
<div dfn-type="dict-member" dfn-for="AuthenticatorSelectionCriteria">
26312641
: <dfn>authenticatorAttachment</dfn>
26322642
:: If this member is [=present|present=], eligible authenticators are filtered to only authenticators attached with the
2633-
specified [[#enum-attachment]].
2643+
specified [[#enum-attachment]]. The value SHOULD be a member of {{AuthenticatorAttachment}} but [=client platforms=] MUST ignore unknown values, treating an unknown value as if the [=map/exist|member does not exist=].
26342644

26352645
: <dfn>requireResidentKey</dfn>
26362646
:: Note: This member is retained for backwards compatibility with WebAuthn Level 1 but is deprecated in favour of {{residentKey}}.
@@ -2645,12 +2655,12 @@ attributes.
26452655
:: Note: This member supersedes {{requireResidentKey}}. If both are present and the [=client=] understands {{residentKey}}, then
26462656
{{residentKey}} is used and {{requireResidentKey}} is ignored.
26472657

2648-
See {{ResidentKeyRequirement}} for the description of {{residentKey}}'s values and semantics.
2658+
The value SHOULD be a member of {{ResidentKeyRequirement}} but [=client platforms=] MUST ignore unknown values, treating an unknown value as if the [=map/exist|member does not exist=]. See {{ResidentKeyRequirement}} for the description of {{residentKey}}'s values and semantics.
26492659

26502660
: <dfn>userVerification</dfn>
26512661
:: This member describes the [=[RP]=]'s requirements regarding [=user verification=] for the
26522662
{{CredentialsContainer/create()}} operation. Eligible authenticators are filtered to only those capable of satisfying this
2653-
requirement.
2663+
requirement. The value SHOULD be a member of {{UserVerificationRequirement}} but [=client platforms=] MUST ignore unknown values, treating an unknown value as if the [=map/exist|member does not exist=].
26542664
</div>
26552665

26562666

@@ -2668,6 +2678,8 @@ to [[#sctn-createCredential|create a credential]].
26682678
};
26692679
</xmp>
26702680

2681+
Note: The {{AuthenticatorAttachment}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
2682+
26712683
<div dfn-type="enum-value" dfn-for="AuthenticatorAttachment">
26722684
: <dfn>platform</dfn>
26732685
:: This value indicates [=platform attachment=].
@@ -2694,6 +2706,8 @@ credential|credentials=]. The [=client=] and user will then use whichever is ava
26942706
};
26952707
</xmp>
26962708

2709+
Note: The {{ResidentKeyRequirement}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
2710+
26972711
This enumeration's values describe the [=[RP]=]'s requirements for [=client-side discoverable credentials=] (formerly known as [=resident credentials=] or [=resident keys=]):
26982712

26992713
<div dfn-type="enum-value" dfn-for="ResidentKeyRequirement">
@@ -2731,6 +2745,8 @@ during credential generation.
27312745
};
27322746
</xmp>
27332747

2748+
Note: The {{AttestationConveyancePreference}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
2749+
27342750
<div dfn-type="enum-value" dfn-for="AttestationConveyancePreference">
27352751
: <dfn>none</dfn>
27362752
:: This value indicates that the [=[RP]=] is not interested in [=authenticator=] [=attestation=]. For example, in order to
@@ -2770,7 +2786,7 @@ an assertion. Its {{PublicKeyCredentialRequestOptions/challenge}} member MUST be
27702786
unsigned long timeout;
27712787
USVString rpId;
27722788
sequence<PublicKeyCredentialDescriptor> allowCredentials = [];
2773-
UserVerificationRequirement userVerification = "preferred";
2789+
DOMString userVerification = "preferred";
27742790
AuthenticationExtensionsClientInputs extensions;
27752791
};
27762792
</xmp>
@@ -2796,8 +2812,7 @@ an assertion. Its {{PublicKeyCredentialRequestOptions/challenge}} member MUST be
27962812

27972813
: <dfn>userVerification</dfn>
27982814
:: This OPTIONAL member describes the [=[RP]=]'s requirements regarding [=user verification=] for the
2799-
{{CredentialsContainer/get()}} operation. Eligible authenticators are filtered to only those capable of satisfying this
2800-
requirement.
2815+
{{CredentialsContainer/get()}} operation. The value SHOULD be a member of {{UserVerificationRequirement}} but [=client platforms=] MUST ignore unknown values, treating an unknown value as if the [=map/exist|member does not exist=]. Eligible authenticators are filtered to only those capable of satisfying this requirement.
28012816

28022817
: <dfn>extensions</dfn>
28032818
:: This OPTIONAL member contains additional parameters requesting additional processing by the client and authenticator.
@@ -2896,7 +2911,7 @@ Note: The {{CollectedClientData}} may be extended in the future. Therefore it's
28962911
};
28972912

28982913
dictionary TokenBinding {
2899-
required TokenBindingStatus status;
2914+
required DOMString status;
29002915
DOMString id;
29012916
};
29022917

@@ -2927,7 +2942,7 @@ Note: The {{CollectedClientData}} may be extended in the future. Therefore it's
29272942

29282943
<div dfn-type="dict-member" dfn-for="TokenBinding">
29292944
: <dfn>status</dfn>
2930-
:: This member is one of the following:
2945+
:: This member SHOULD be a member of {{TokenBindingStatus}} but [=client platforms=] MUST ignore unknown values, treating an unknown value as if the {{CollectedClientData/tokenBinding}} [=map/exist|member does not exist=]. When known, this member is one of the following:
29312946

29322947
<div dfn-type="enum-value" dfn-for="TokenBindingStatus">
29332948
: <dfn>supported</dfn>
@@ -2938,6 +2953,8 @@ Note: The {{CollectedClientData}} may be extended in the future. Therefore it's
29382953
{{TokenBinding/id}} member MUST be present.
29392954
</div>
29402955

2956+
Note: The {{TokenBindingStatus}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
2957+
29412958
: <dfn>id</dfn>
29422959
:: This member MUST be present if {{TokenBinding/status}} is {{TokenBindingStatus/present}}, and MUST be a [=base64url
29432960
encoding=] of the [=Token Binding ID=] that was used when communicating with the [=[RP]=].
@@ -3055,20 +3072,23 @@ If additional fields are added to {{CollectedClientData}} then verifiers that em
30553072
};
30563073
</xmp>
30573074

3075+
Note: The {{PublicKeyCredentialType}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
3076+
30583077
<div dfn-type="enum-value" dfn-for="PublicKeyCredentialType">
30593078
This enumeration defines the valid credential types. It is an extension point; values can be added to it in the future, as
30603079
more credential types are defined. The values of this enumeration are used for versioning the Authentication Assertion and
30613080
attestation structures according to the type of the authenticator.
30623081

30633082
Currently one credential type is defined, namely "<dfn>public-key</dfn>".
3083+
30643084
</div>
30653085

30663086

30673087
### Credential Descriptor (dictionary <dfn dictionary>PublicKeyCredentialDescriptor</dfn>) ### {#dictionary-credential-descriptor}
30683088

30693089
<xmp class="idl">
30703090
dictionary PublicKeyCredentialDescriptor {
3071-
required PublicKeyCredentialType type;
3091+
required DOMString type;
30723092
required BufferSource id;
30733093
sequence<DOMString> transports;
30743094
};
@@ -3080,7 +3100,7 @@ parameter to the {{CredentialsContainer/create()}} or {{CredentialsContainer/get
30803100

30813101
<div dfn-type="dict-member" dfn-for="PublicKeyCredentialDescriptor">
30823102
: <dfn>type</dfn>
3083-
:: This member contains the type of the [=public key credential=] the caller is referring to.
3103+
:: This member contains the type of the [=public key credential=] the caller is referring to. The value SHOULD be a member of {{PublicKeyCredentialType}} but [=client platforms=] MUST ignore any {{PublicKeyCredentialDescriptor}} with an unknown {{PublicKeyCredentialDescriptor/type}}.
30843104

30853105
: <dfn>id</dfn>
30863106
:: This member contains the [=credential ID=] of the [=public key credential=] the caller is referring to.
@@ -3109,15 +3129,15 @@ parameter to the {{CredentialsContainer/create()}} or {{CredentialsContainer/get
31093129
};
31103130
</xmp>
31113131

3132+
Note: The {{AuthenticatorTransport}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
3133+
31123134
<div dfn-type="enum-value" dfn-for="AuthenticatorTransport">
31133135
[=Authenticators=] may implement various [[#enum-transport|transports]] for communicating with [=clients=]. This enumeration
31143136
defines hints as to how clients might communicate with a particular authenticator in order to obtain an assertion for a
31153137
specific credential. Note that these hints represent the [=[WRP]=]'s best belief as to how an authenticator may be reached. A
31163138
[=[RP]=] will typically learn of the supported transports for a [=public key credential=] via
31173139
{{AuthenticatorAttestationResponse/getTransports()}}.
31183140

3119-
Note: The {{AuthenticatorTransport}} enumeration is not referenced by other parts of the Web IDL because that would preclude other values from being used without updating this specification and its implementations. It is important for backwards compatibility that [=client platforms=] and [=[RPS]=] handle unknown values. Therefore it exists here for documentation and as a registry. Where transports are represented elsewhere, they are typed as {{DOMString}}s, for example in {{PublicKeyCredentialDescriptor/transports}}.
3120-
31213141
: <dfn>usb</dfn>
31223142
:: Indicates the respective [=authenticator=] can be contacted over removable USB.
31233143

@@ -3160,6 +3180,8 @@ parameter to the {{CredentialsContainer/create()}} or {{CredentialsContainer/get
31603180
A [=[WRP]=] may require [=user verification=] for some of its operations but not for others, and may use this type to express its
31613181
needs.
31623182

3183+
Note: The {{UserVerificationRequirement}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].
3184+
31633185
<div dfn-type="enum-value" dfn-for="UserVerificationRequirement">
31643186
: <dfn>required</dfn>
31653187
:: This value indicates that the [=[RP]=] requires [=user verification=] for the operation and will fail the operation if the

0 commit comments

Comments
 (0)