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