Re: [jose] Working Group Last Call (WGLC) for draft-ietf-jose-cookbook-03

Responses inline...

-----Original Message-----
From: Matt Miller [mailto:mamille2@cisco.com]
Sent: Wednesday, August 06, 2014 7:46 AM
To: Mike Jones; jose@ietf.org
Cc: Karen O'Donoghue
Subject: Re: [jose] Working Group Last Call (WGLC) for draft-ietf-jose-cookbook-03

-----BEGIN PGP SIGNED MESSAGE-----

Hash: SHA512

Thank you for your feedback, Mike.

More comments inline.

On 8/5/14, 7:21 PM, Mike Jones wrote:

> COMMENTS ON NORMATIVE CONTENT

>

>

>

> 1.  This document contains a wealth of useful JWS and JWE examples

> using a broad selection of algorithms.  My review primary review

> comment is that it should also contain a section with illustrative JWK

> examples. These examples should intentionally illustrate corner cases

> that will actually occur that developers might get wrong.  I would

> suggest adding these JWK examples:

>

>

>

> 1a.  JWK with "kty": "RSA", e=65537, and 2048 bit "n".  I would point

> out that neither can legally be prefixed by with extra zero bytes.

> (Examples have been found in the wild in which developers mistakenly

> represent "n" values by encoding an extra leading byte - the extra

> byte being zero - rather than encoding the specified number of bytes -

> the highest-order bit of which is always 1 for a correctly generated

> key. For instance, such mis-representations encode 257 bytes for a

> 2048 bit key, rather than 256 bytes.)

>

>

>

> 1b.  JWK with "kty": "EC", "crv": "P-256", and for which the

> high-order byte of one of "x" or "y" are zero.  I would point out that

> the high-order bytes are required to be represented, even if zero.  I

> would also point out that extra zero bytes are not permitted.

>

>

>

> 1c.  JWK with "kty": "EC", "crv": "P-521", and for which the

> high-order (521^st ) bit of one of "x" or "y" are zero (and because

> only one significant bit is used to represent the 521^st bit in the

> high-order byte, consequently the corresponding high-order byte is

> zero).    I would point out that the high-order bytes are required

> to be represented, even if zero.  I would also point out that extra

> zero bytes are not permitted.

>

>

>

> 1d.  JWK with "kty": "oct" and 128 bit "k" value in which the

> high-order byte is zero.  I would point out that the high-order bytes

> are required to be represented, even if zero.  I would also point out

> that extra zero bytes are not permitted.

>

>

>

> This will also necessitate revising some descriptive text at various

> locations in the specification.  For instance, a new sentence at the

> end of the Abstract should added "This document also illustrates a

> sampling of JSON Web Key (JWK) representations".

>

>

The document includes all of the above, but does not call them out specifically.  I can add a section that copies a representative sample of JWKs from elsewhere in the document.

That would be good - thanks.  I would specifically call out the particulars like the high-order bit of one of the 521-bit values being zero, the high-order byte of one of the 256-bit values being zero, no extra leading zeroes being included for RSA "n" values, etc.  Particularly in the base64url encoding, most people won't know that AAAA represents a zero byte.

>

> 2.  Terminology usage throughout the document:  You should replace

> uses of the term "Protected JWS Header" with "JWS Protected Header",

> to match the JWS spec.  Likewise, you should replace "Protected JWE

> Header" with "JWE Protected Header", "Unprotected

> JW* Header" with "JW* Unprotected Header", etc.

>

>

>

> The terms "JWS Header" and "JWE Header" were replaced with the term

> "JOSE Header" in the -29 versions.  You need to apply this change as

> well.

>

>

>

> I'd likewise check other terms to make sure the ones you're using

> match the other JOSE specs.

>

>

I'll make the appropriate changes.  We better be done changing our dictionary (-:

I sure hope so too! :)

>

> 3.  Section 3.1.2 (Signing Operation):  You show the JOSE header value

> as containing line breaks and whitespace, but the base64url encoded

> version of it does not contain these characters.  You need to say that

> the unencoded form is shown with extra whitespace for readability but

> that, for brevity, the cookbook omits these formatting characters that

> don't change the meaning of the JSON in the base64url encoded

> versions. You should also say that they need not have been omitted, as

> they would have been legal in the base64url encoded JSON object.

>

>

>

> I first noticed this inconsistency in Section 3, but it happens

> everywhere you display a JOSE Header value.  You probably need to say

> something general about this, as well as say something specific about

> it the first time it occurs in an example.

Section 1.1 already contains the following paragraph:

All of the examples in this document have whitespace added to improve formatting and readability. Except for JWE plaintext or JWS payload content, whitespace is not part of the cryptographic operations.

Unless otherwise noted, the JWE plaintext or JWS payload content does include " " (U+0020 SPACE) characters; line breaks (U+000A LINE FEED) are added to improve readability but are not present in the JWE plaintext or JWS payload.

Do you have a suggestion for better wording?  Does the working group believe this needs to be repeated in very section?

I realized that the text in 1.1 was there but the problem is that many people use specs as a reference, rather than reading them cover-to-cover.  They'll skip what they consider to be boilerplate and go straight to the meat - the examples.

I don't know that people need to reminded in every example, but at a minimum, I'd remind them in the first example that the encoded JSON omits the whitespace shown in the displayed JSON.  And I'd remind them in the first example that the actual Compact Serialization doesn't include the whitespace shown.  You can do this with language like "As described in Section 1.1, ...".

>

>

>

> 4.  Section 3.1.2 (Signing Operation):  You refer to the "combined

> projected JWS header and payload content".  It might be useful to

> readers to elaborate more on the combination.  You could, for

> instance, say that they are "combined ... into the JWS Signing Input

> value, as described in Section 5.1 of [JWS]".  I might do this for at

> least the first signing example.  At the very least, the term "JWS

> Signing Input" describing this intermediate result should probably

> appear somewhere.

>

>

I can add the intermediate examples.

>

> 5.  Section 3.1.3 (Output Results):  You show a result using the JWS

> Compact Serialization but with line breaks in it.  You need to say

> that the line breaks within the output value are for display purposes

> only. For what it's worth, the JWS spec does this by including the

> phrases "(with line breaks for display purposes only)" or "(with line

> breaks within values for display purposes only)", where appropriate,

> in the description of the value.  This situation occurs throughout the

> specification.

>

>

See above regarding Section 1.1.

>

> 6.  Section 3.1.3 (Output Results):  You show a result using the JWS

> JSON Serialization with line breaks within some values.  This would be

> an appropriate place to use the "(with line breaks within values for

> display purposes only)" language.  This situation occurs throughout

> the specification.

>

See above regarding Section 1.1.

>

>

>

>

> EDITORIAL COMMENTS

>

>

>

> E0.  I would suggest taking the HTML output and running it through a

> grammar checker, such as the one in Microsoft Word.  This will catch a

> number of simple phrasing problems, omitted words, and repeated words.

> Some specific editorial comments follow.

>

>

I admittedly turned off my spell checkers once most of the examples were in place due to the rather high signal-to-noise ratio.

I know - it's moderately painful.  It takes me about 20 minutes to do the full spelling and grammar check of the concatenated JWS, JWE, JWK, JWA, and JWT specs when I do a release.  Use the keyboard shortcuts Alt-i for ignore a single instance of a grammar problem and Alt-g to ignore all instances of a word that's legal in the document but not legal English - like "alg", etc.  That will speed things up.

I'd do all your other edits, then do this at least once.  I think you'll be surprised how much you find.  In my experience, the grammar checking is often even more important than the spelling checking.

>

> E1.  In the Abstract, the first "sentence" is missing a verb, and so

> is actually a fragment.  I'd change it to "This specification contains

> set of examples using JavaScript Object Signing and Encryption (JOSE)

> functionality to protect data".

>

>

>

> E2.  In the Introduction, I would change the document order to JWS,

> JWE, JWK, JWA - as that is the standard order we usually talk about

> them in - in part, because if a developer uses only one of (JWS, JWE,

> and JWK), it tends to be JWS - so it makes sense to start with it.

> JWA is last because it's used by all the others.  JWE follows JWS

> because it makes sense to group encryption with signing.  Which leaves

> JWK in the third spot.

>

>

>

> E3.  In the Introduction, this sentence seems overly negative:

> "The full set of permutations is extremely large, and might be

> daunting to some".  I'd reword it to: "While the full set of

> permutations is large, and might be daunting to some, it is expected

> that most applications will choose a relatively constrained set of

> algorithms and combinations that meet their needs".

>

>

>

> E4.  Introduction: "compile together" -> "compile"

>

>

>

> E5.  Section 1.1:  "enough factors" -> "enough information"

>

>

>

> E6.  Section 1.1:  "or to validate or to validate" -> "or to validate"

>

>

>

> E7.  Section 1.1: "some algorithms inherently use random data and

> cannot be exactly replicated" -> "some algorithms inherently use

> random data and therefore computations employing them cannot be

> exactly replicated"

>

>

>

> E8.  In the Terminology section, use the document order JWS, JWE, JWK,

> JWA.

>

>

>

> E9.  Section 3: "the sequence "\xe2\x80\x99" substituted" -> "the

> sequence "\xe2\x80\x99" is substituted"

>

>

>

> E10.  Section 3: "line breaks (U+000A LINE FEED) replacing some " "

> (U+0020 SPACE)" -> "line breaks (U+000A LINE FEED) replace some

> instances of " " (U+0020 SPACE)"

>

>

>

> E11.  Section 4:  Apply the same editorial corrections to the second

> paragraph as E9 and E10 above.

>

>

>

> E12.  Acknowledgments: "quotes" -> "quotations"

>

>

>

> E13.  Acknowledgments: Uses of ";" should be changed to ",".

>

>

>

>

>

> -----Original Message----- From: jose

> [mailto:jose-bounces@ietf.org] On Behalf Of Karen ODonoghue Sent:

> Wednesday, July 23, 2014 7:42 AM To: jose@ietf.org<mailto:jose@ietf.org> Subject: [jose]

> Working Group Last Call (WGLC) for draft-ietf-jose-cookbook-03

>

>

>

> Folks,

>

>

>

> This message starts a two week working group last call for the jose

> cookbook document "Examples of Protecting Content using JavaScript

> Object Signing and Encryption (JOSE)"

>

> (https://tools.ietf.org/html/draft-ietf-jose-cookbook-03)

>

>

>

> Please review the document and send comments, questions to the Working

> Group mailing list < jose at ietf.org > or the co-chairs <jose-chairs

> at tools.ietf.org > before the end of the WGLC.

>

>

>

> Please note that suggested changes which include proposed text will be

> more strongly considered than those without. Additionally, even if you

> have no comments, statements to the effect that "I have read this

> document and believe it is ready for publication" are helpful.

>

>

>

> Regards,

>

> Karen and Jim

>

>

>

> _______________________________________________

>

> jose mailing list

>

> jose@ietf.org<mailto:jose@ietf.org> <mailto:jose@ietf.org>

>

> https://www.ietf.org/mailman/listinfo/jose

>

- --

- - m&m

Matt Miller < mamille2@cisco.com<mailto:mamille2@cisco.com> >

Cisco Systems, Inc.

-----BEGIN PGP SIGNATURE-----

Version: GnuPG/MacGPG2 v2.0.22 (Darwin)

Comment: GPGTools - https://gpgtools.org

Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCgAGBQJT4j+SAAoJEDWi+S0W7cO1Iy4H/Rt6W6n4abVcEbyIMrFe/zZP

QkJNe1bFBFFmytTz+Djp+gfEsd3ZhseaS8EiwozOWdrlkvcAUR3lIvOgt4LU4tTf

oVV94W41T5azuXavXNjVSgXR7vLtYkOpt991d5oqqU7VRPnA58EsJbCOaUkmrieA

Fi4MLqYKAq4qIHBZvGqRELFhqYhTG4yT9ueoCwpcsN2iEveEU0kjlF+eyEVFS8dn

7IF4kSy6HYyhWzFVfrQ0996Y/hv/50cpJEnGy4Mhlem41Gv3KhsqCV+EexNVrS46

NO1P0UzM/Hv6uYElAucvx6E249n2tQlFkQ+ZJqWJu1qhfsVGmrfQ0rZTwVZ8CXk=

=Km7Y

-----END PGP SIGNATURE-----