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

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 (521st) bit of one of "x" or "y" are zero (and because only one significant bit is used to represent the 521st 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".

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.

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.

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.

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.

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.

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.

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
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>

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