Subject: [secdir] SecDir review of draft-ietf-jose-cookbook-06

From: Yaron Sheffer <[email-masked]>
Date: Sat, 22 Nov 2014 21:39:57 +0200

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.

Summary

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.

Details

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

Thanks,
	Yaron