Skip to main content

Last Call Review of draft-ietf-jose-cookbook-06

Request Review of draft-ietf-jose-cookbook
Requested revision No specific revision (document currently at 08)
Type Last Call Review
Team Security Area Directorate (secdir)
Deadline 2014-11-28
Requested 2014-11-20
Authors Matthew A. Miller
I-D last updated 2014-11-27
Completed reviews Secdir Last Call review of -06 by Yaron Sheffer (diff)
Opsdir Last Call review of -06 by Jouni Korhonen (diff)
Assignment Reviewer Yaron Sheffer
State Completed
Review review-ietf-jose-cookbook-06-secdir-lc-sheffer-2014-11-27
Reviewed revision 06 (document currently at 08)
Result Has Issues
Completed 2014-11-27
I have reviewed this document as part of the security directorate's
ongoing effort to review all IETF documents being processed by the IESG.
These comments were written primarily for the benefit of the security
area directors.  Document editors and WG chairs should treat these
comments just like any other last call comments.

This document contains a large set of examples of JOSE objects: JWK, JWS 

and JWE. The document is purely informational, though in "real life", I 

would expect developers to use it as an authoritative source.


The document is ready to be published, with some issues.

By the way, I really appreciate the large effort that surely went into 

creating this document.


• Unless I missed it, the document does not mention a machine readable 

repository of these examples, which I am sure the author has created 

while writing the draft. Making such a repository publicly available 

would result in a much more useful resource than the current document, 

which essentially requires testers to scrape the document when creating 

their test cases.

• (Not a comment to the current document:) I wonder why there is nothing 

explicit to distinguish a public key from a private key, and they are 

only distinguished by the presence or absence of several parameters, 

something that will not be natural to most developers. PEM is doing it 

very well: "-----BEGIN RSA PRIVATE KEY-----".

• 3.4: the text is contradictory re: zero-padding of the value "d". Is 

it using the minimum number of octets, or exactly 256 octets (for a 

2048-bit key)?

• Why invent a new term "octet key", for a simple "symmetric key"?

• 4.2: the first sentence discusses PS256, the actual example is PS384.

• 4.7: "only the JSON serialization" - please clarify which of the three 

serializations is meant. Ditto top of 4.8.

• 5.1.1: since this is a "cookbook", we should be using the public key, 

not the private key. A private key would only be used in rare cases. 

Similarly 5.2.1.

• 5.3.1: the "plaintext content" is a list of keys, which is either 

confusing to the reader, or an actual error in the document.

• 5.3.5: In the General Serialization version, I don't understand why 

only the encrypted key is per-recipient. I would expect the PBES2 

parameters too (e.g., the salt)  to be per-recipient. Presumably each of 

them is using a different password, and there's no reason to use a 

common salt. Similarly in 5.4.5.

• 5.7: same as above, it makes sense for the per-recipient key to have 

an ID, rather than the content encryption key (typically an ephemeral 

key). And then that ID should be in the per-recipient data in 5.7.5. And 

similarly for 5.8. The later Sec. 5.13 shows a syntax for multiple 

recipients that's inconsistent with the single-recipient case, which 

would make sense if we got rid of the array.

• 5.11: this example seems strange to me - why would anybody NOT want to 

integrity-protect the key ID and algorithm? I would prefer a more 

realistic example, or failing that, a recommendation to developers to 

avoid this practice. Similarly 5.12, which is an even worse idea.