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

[Matt Miller <[e-mail]>]

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

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

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

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

> 
> 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:[e-mail]] On Behalf Of Karen ODonoghue Sent:
> Wednesday, July 23, 2014 7:42 AM To: [e-mail] 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
> 
> [e-mail] <mailto:[e-mail]>
> 
> https://www.ietf.org/mailman/listinfo/jose
> 


- -- 
- - m&m

Matt Miller < [e-mail] >
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-----