Normalize RFC2119 langugage #470

AngeloKai · 2017-05-22T18:20:01Z

Address issue #182

jyasskin · 2017-05-22T18:22:25Z

index.bs

@@ -102,7 +102,7 @@ the existence, of credentials scoped to other [RPS].

 [RPS] employ the [=Web Authentication API=] during two distinct, but related, [=ceremonies=] involving a user. The first
 is [=Registration=], where a [=public key credential=] is created on an [=authenticator=], and associated by a [=[RP]=]
-with the present user's account (the account may already exist or may be created at this time). The second is
+with the present user's account (the account MAY already exist or MAY be created at this time). The second is


Please read through the changes you're making here and check that you actually intend the RFC 2119 meanings. This change is in a non-normative section, so it's definitely not right.

equalsJeffH · 2017-12-06T21:55:43Z

please merge-from-master (into this branch) and fix build errors, to facilitate further reviews, thx.

selfissued

Most of these changes are good but some are in descriptive, rather than normative contexts. In descriptive contexts, RFC 2119 language is not appropriate.

Also, I believe that master needs to be merged into this branch.

selfissued · 2017-12-08T17:39:39Z

index.bs

@@ -373,8 +373,8 @@ operations with an existing credential. All such operations are performed in the
 and/or platform on the user's behalf. At no point does the script get access to the credentials themselves; it only gets
 information about the credentials in the form of objects.

-In addition to the above script interface, the authenticator may implement (or come with client software that implements) a user
-interface for management. Such an interface may be used, for example, to reset the authenticator to a clean state or to inspect
+In addition to the above script interface, the authenticator MAY implement (or come with client software that implements) a user


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T17:40:16Z

index.bs

-In addition to the above script interface, the authenticator may implement (or come with client software that implements) a user
-interface for management. Such an interface may be used, for example, to reset the authenticator to a clean state or to inspect
+In addition to the above script interface, the authenticator MAY implement (or come with client software that implements) a user
+interface for management. Such an interface MAY be used, for example, to reset the authenticator to a clean state or to inspect


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T17:41:27Z

index.bs

@@ -678,7 +678,7 @@ authorizing an authenticator.
 The <dfn for="PublicKeyCredential" method>\[[DiscoverFromExternalSource]](options)</dfn> method is used to discover and use an
 existing [=public key credential=], with the user's consent. The script optionally specifies some criteria to indicate what
 credentials are acceptable to it. The user agent and/or platform locates credentials matching the specified criteria, and guides
-the user to pick one that the script will be allowed to use. The user may choose not to provide a credential even if one is
+the user to pick one that the script will be allowed to use. The user MAY choose not to provide a credential even if one is


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T17:41:30Z

index.bs

@@ -678,7 +678,7 @@ authorizing an authenticator.
 The <dfn for="PublicKeyCredential" method>\[[DiscoverFromExternalSource]](options)</dfn> method is used to discover and use an
 existing [=public key credential=], with the user's consent. The script optionally specifies some criteria to indicate what
 credentials are acceptable to it. The user agent and/or platform locates credentials matching the specified criteria, and guides
-the user to pick one that the script will be allowed to use. The user may choose not to provide a credential even if one is
+the user to pick one that the script will be allowed to use. The user MAY choose not to provide a credential even if one is


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T17:42:07Z

index.bs

@@ -872,8 +872,8 @@ during registration.
 <div dfn-type="attribute" dfn-for="AuthenticatorAttestationResponse">
    :   {{AuthenticatorResponse/clientDataJSON}}
    ::  This attribute, inherited from {{AuthenticatorResponse}}, contains the [=JSON-serialized client data=] (see
-        [[#sctn-attestation]]) passed to the authenticator by the client in order to generate this credential. The
-        exact JSON serialization must be preserved, as the [=hash of the serialized client data=] has been computed
+        [[#cred-attestation]]) passed to the authenticator by the client in order to generate this credential. The


Looks like merging master into this branch is needed.

just merged. thank you for noticing :)

selfissued · 2017-12-08T19:44:52Z

index.bs

 `myCompany_extension`.

 All extension identifiers MUST be a maximum of 32 octets in length and MUST consist only of printable USASCII characters,
 excluding backslash and doublequote, i.e., VCHAR as defined in [[!RFC5234]] but without %x22 and %x5c. Implementations MUST
 match WebAuthn extension identifiers in a case-sensitive fashion.

-Extensions that may exist in multiple versions should take care to include a version in their identifier. In effect, different
+Extensions that MAY exist in multiple versions SHOULD take care to include a version in their identifier. In effect, different


Back out both of these.

selfissued · 2017-12-08T19:45:14Z

index.bs

@@ -2542,13 +2543,13 @@ input=]. For extensions that do not require input parameters and are defined as
 value set to `true`, this method SHOULD consist of passing an [=authenticator extension input=] value of `true` (CBOR major type
 7, value 21).

-Note: Extensions should aim to define authenticator arguments that are as small as possible. Some authenticators communicate
+Note: Extensions SHOULD aim to define authenticator arguments that are as small as possible. Some authenticators communicate


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T19:45:40Z

index.bs

@@ -2601,7 +2602,7 @@ The extension also requires the client to set the authenticator parameter to the

 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=] may be as
+An authenticator does this by including it in the [=authenticator data=]. As an example, [=authenticator data=] MAY be as


Change this one to "might"

done. good catch :)

selfissued · 2017-12-08T19:46:29Z

index.bs

@@ -3095,7 +3096,7 @@ platform to enumerate all the authenticator's credentials so that the client can

 This is the first-time flow, in which a new credential is created and registered with the server.

-1. The user visits example.com, which serves up a script. At this point, the user must already be logged in using a legacy
+1. The user visits example.com, which serves up a script. At this point, the user MUST already be logged in using a legacy


This is descriptive - not normative language. Please back this individual change out.

selfissued · 2017-12-08T19:46:47Z

index.bs

@@ -3176,7 +3177,7 @@ credential.
 1. The user visits example.com, which serves up a script.

 2. The script asks the client platform for an Authentication Assertion, providing as much information as possible to narrow
-    the choice of acceptable credentials for the user. This may be obtained from the data that was stored locally after
+    the choice of acceptable credentials for the user. This MAY be obtained from the data that was stored locally after


Change this one to "can"

equalsJeffH

I support @selfissued's feedback.

nadalin · 2017-12-20T18:53:42Z

@AngeloKai Can you please apply Mike's changes and merge ?

selfissued

Angelo, I believe this is now ready to merge after the merge conflicts are resolved. Can you please resolve them and merge? Thanks.

Normalize RFC langugages

bdf050a

jyasskin reviewed May 22, 2017

View reviewed changes

Angelo Liao added 2 commits May 22, 2017 11:33

Merge branch 'master' into normalize

a6effcb

Minor tweak to not accidentally change things

579403b

AngeloKai requested a review from equalsJeffH May 22, 2017 18:36

selfissued self-assigned this May 24, 2017

equalsJeffH changed the title ~~Normalize RFC langugages~~ Normalize RFC2119 langugage May 24, 2017

equalsJeffH added this to the CR milestone Jun 9, 2017

selfissued requested changes Dec 8, 2017

View reviewed changes

equalsJeffH reviewed Dec 15, 2017

View reviewed changes

AngeloKai added 3 commits January 2, 2018 12:40

merged with upstream master

498db32

update based on review

2ce39c2

fixed travis build issue

b379e3d

selfissued approved these changes Jan 8, 2018

View reviewed changes

resolve conflicts

5552c19

AngeloKai merged commit 3cfaeba into w3c:master Jan 9, 2018

WebAuthnBot pushed a commit that referenced this pull request Jan 9, 2018

Built by Travis-CI: 3cfaeba Normalize RFC2119 langugage (#470)

8369664

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Normalize RFC2119 langugage #470

Normalize RFC2119 langugage #470

AngeloKai commented May 22, 2017 •

edited by pr-preview bot

Loading

jyasskin May 22, 2017

equalsJeffH commented Dec 6, 2017

selfissued left a comment

selfissued Dec 8, 2017

selfissued Dec 8, 2017

selfissued Dec 8, 2017

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

AngeloKai Jan 2, 2018

selfissued Dec 8, 2017

equalsJeffH left a comment

nadalin commented Dec 20, 2017

selfissued left a comment

Normalize RFC2119 langugage #470

Normalize RFC2119 langugage #470

Conversation

AngeloKai commented May 22, 2017 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

equalsJeffH commented Dec 6, 2017

selfissued left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

equalsJeffH left a comment

Choose a reason for hiding this comment

nadalin commented Dec 20, 2017

selfissued left a comment

Choose a reason for hiding this comment

AngeloKai commented May 22, 2017 •

edited by pr-preview bot

Loading