Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE)
draft-ietf-jose-cookbook-08

[Ballot comment]
The authors engaged in the discussion with the OPS-DIR reviewer Jouni on the points below. Thanks

Few minor nits & comments:

o IDnits spits out warnings. I recon all of them are of kind that will be corrected by t he RFC Editor -> no worries.

o The document uses example domains "hobbiton.example" and alike. According to RFC2606 & 6761 the example domains are "example.com" etc. These should be corrected UNLESS they cause too much trouble regenerating outputs into examples...

o line 325 "coordiates" should probably be "coordinates".

o I would take acronyms (e.g. "(JWS)") away from the abstract.

[Ballot comment]
Note: I have personally validated the examples in Sections 3.1, 3.3, 4.1, 4.2, and 4.3.  I used them in tests for a JWK/JWS library.  (The only difference between the text and the test case is that I had to add a "jwk" header field, because my code doesn't support lookup based on "kid".)

https://github.com/bifurcation/gose/blob/master/jose_test.go#L36

Now we just need RosettaCode entries for JOSE operations :)

http://rosettacode.org/wiki/HTTP

Section 1.1.:

"""
  Unless otherwise noted, the JWE plaintext or JWS payload content does
  include " " (U+0020 SPACE) characters.  Line breaks (U+000A LINE
  FEED) replace some " " (U+0020 SPACE) characters to improve
  readability but are not present in the JWE plaintext or JWS payload.
"""

I think Barry commented on this in his pre-review, but it would be good to clarify this.  Perhaps you could describe the examples as a sequence of quoted strings, which the user should concatenate?  For example, in Section 4:

"""
  "It\xe2\x80\x99s a dangerous business, Frodo, going out your "
  "door. You step onto the road, and if you don't keep your feet, "
  "there\xe2\x80\x99s no knowing where you might be swept off "
  "to."
"""

I agree with Alissa that "progenitor" is inapt.  "Private key corresponding to" is the typical phrasing.

[Ballot comment]


- 3.3, 1st para says private where it should say public

- thanks for addressing the (heroic:-) secdir review [1],
I think in the end you got everything rigth?

  [1] https://www.ietf.org/mail-archive/web/secdir/current/msg05249.html

[Ballot comment]
I would suggest using a simpler word than "progenitor" in 3.2 and 3.4 (unless it's a term of art, but it doesn't seem like it is).

[Ballot comment]
I've already made these comments by email, and discussed them with
Matt.  I'm quite satisfied that they're in hand, and no further response
is needed.

My experience is that any time there is a significant number of
examples, some of them will be wrong.  My experience is also that
readers will find those errors and will delight in filing errata
reports.  The shepherd writeup says that the compact encodings, at
least, have been checked for correctness, and I'm trusting that this
is adequate.  But please have pity on the Sec ADs and their
successors, who will have to deal with the inevitable errata, and
quadruple check things.  And make sure that errors are not introduced
during RFC Editor processing.  Do a more-careful-than-usual check
during AUTH48.

In particular, it is very importantant that the RFC Editor perform no
editing at all on the cleartext payloads.  For example:

  It\xe2\x80\x99s a dangerous business, Frodo, going out your
  door. You step onto the road, and if you don't keep your feet,
  there\xe2\x80\x99s no knowing where you might be swept off
  to.

If the RFC Editor's editing should double-space the sentences, your
examples based on the published cleartext would then be wrong.
Please make sure the the RFC Editor understands that they must
not alter that text in any way... and then please check that during AUTH48.

-- Appendix A --
Not that it matters terribly, but during AUTH48, you might coordinate
with the RFC Editor to make sure that single spacing (not double, as
now) is used after the periods in "J. R. R. Tolkien".  Kathleen might
put this into an RFC Editor note.

IESG/Authors/WG Chairs:

IANA has reviewed draft-ietf-jose-cookbook-06, which is currently in Last Call, and has the following comments:

We understand that this document doesn't require any IANA actions.

While it is helpful for the IANA Considerations section of the document to remain in place upon publication, if the authors prefer to remove it, IANA doesn't object.

If this assessment is not accurate, please respond as soon as possible.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Examples of Protecting Content using JavaScript Object Signing and Encryption (JOSE)) to Informational RFC


The IESG has received a request from the Javascript Object Signing and
Encryption WG (jose) to consider the following document:
- 'Examples of Protecting Content using JavaScript Object Signing and
  Encryption (JOSE)'
  as Informational RFC

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2014-11-28. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This document contains a set of examples using JavaScript Object
  Signing and Encryption (JOSE) technology to protect data.  These
  examples present a representative sampling JSON Web Key (JWK)
  objects, as well as various JSON Web Signature (JWS) and JSON Web
  Encryption (JWE) results given similar inputs.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-jose-cookbook/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-jose-cookbook/ballot/


No IPR declarations have been submitted directly on this I-D.

Only the Compact Serialization examples have been validated.

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) This is an Informational RFC request

(2) Approval Announcement:

Technical Summary

  This document provides a set of examples for the standards
  created by the JOSE (JavaScript Object Signing And Encryption)
  working group.  The document includes examples of JOSE being
  used for signing, encrypting, and authenticating texts, as
  well as how public key pairs and symmetric keys can be encoded.

  Examples are given for both the Compact and JSON serialization
  formats.

Working Group Summary

  The document was completely non-controversial.  The only discussions on the document dealt with which cases were missing from the document.

Document Quality

  All of the Compact serializations have been validated by
  at least two people.  The JSON serializations are equivalent
  to the compact serializations, but have not had the same
  testing level.

Personnel

  The document shepherd is Jim Schaad, the AD is Kathleen Moriarty.

(3) I have read the document from front to back twice looking for awkwardness in the working, missing cases and other such items.  The -05 version should have all of my feedback incorporated in it and that is the version that should be reviewed.

The document is a constructed document from boilerplate, thus I have done a detailed check on one instance of each boilerplate and just scanned the rest.

I have not yet done an implementation to check the JSON encodings, however I have looked that the compact encodings and the JSON encodings look to have the same values and the JSON encoding has the correct set of fields.  The compact encodings have been independently checked for correctness.

(4) It would be nice to have programmatic validation of the JSON serialization examples.  However, the compact and JSON serializations were generated at the same time and from the same data so that the mathmatics are known to be correct.  It is possible to do visual checks that the strings are the same, I have done this in a spot check manner and have found no issues.

(5) The document should not need to have any broader review than it currently has gotten.  The only suggestion that has occurred during review has been a request to have an example that includes a password that needs to have more complicated processing done to it, that is to include PRECIS processing.

(6) I have no concerns about this document that either the AD or IESG need to be made aware of.

(7) Question has not been asked of the authors yet.  Will do when final version is published.
    The expected answer is no.
Has each author confirmed that any and all appropriate IPR
disclosures required for full conformance with the provisions of BCP 78
and BCP 79 have already been filed. If not, explain why.

(8) No IPR disclosures have been filed on this document.

(9) The document has been non-controversial and has wide support for release.

(10) There has been no controversy for this document.

(11) There re no nits in the -03 version, but a final check on the final document needs to be done.

(12) No external formal review is required for this document.

(13) All references are informative.  This is appropriate for the document.

(14) All references from this document are informative.  No normative references exist.

(15) There are no normative references.

(16) This is first time document and will not change the status of any other document.

(17) The document has no IANA considerations.  I have verified that this is appropriate.

(18) The document has no IANA considerations. 

(19) There are no formal language sections of the document.

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) This is an Informational RFC request

(2) Approval Announcement:

Technical Summary

  This document provides a set of examples for the standards
  created by the JOSE (JavaScript Object Signing And Encryption)
  working group.  The document includes examples of JOSE being
  used for signing, encrypting, and authenticating texts, as
  well as how public key pairs and symmetric keys can be encoded.

  Examples are given for both the Compact and JSON serialization
  formats.

Working Group Summary

 
  Was there anything in WG process that is worth noting? For
  example, was there controversy about particular points or
  were there decisions where the consensus was particularly
  rough?

Document Quality

  All of the Compact serializations have been validated by
  at least two people.  The JSON serializations are equivalent
  to the compact serializations, but have not had the same
  testing level.

Personnel

  The document shepherd is Jim Schaad, the AD is Kathleen Moriarty.

(3) I have read the document from front to back twice looking for awkwardness in the working, missing cases and other such items.  The -05 version should have all of my feedback incorporated in it and that is the version that should be reviewed.

The document is a constructed document from boilerplate, thus I have done a detailed check on one instance of each boilerplate and just scanned the rest.

I have not yet done an implementation to check the JSON encodings, however I have looked that the compact encodings and the JSON encodings look to have the same values and the JSON encoding has the correct set of fields.  The compact encodings have been independently checked for correctness.

(4) It would be nice to have programmatic validation of the JSON serialization examples.  However, the compact and JSON serializations were generated at the same time and from the same data so that the mathmatics are known to be correct.  It is possible to do visual checks that the strings are the same, I have done this in a spot check manner and have found no issues.

(5) The document should not need to have any broader review than it currently has gotten.  The only suggestion that has occurred during review has been a request to have an example that includes a password that needs to have more complicated processing done to it, that is to include PRECIS processing.

(6) I have no concerns about this document that either the AD or IESG need to be made aware of.

(7) Question has not been asked of the authors yet.  Will do when final version is published.
    The expected answer is no.
Has each author confirmed that any and all appropriate IPR
disclosures required for full conformance with the provisions of BCP 78
and BCP 79 have already been filed. If not, explain why.

(8) No IPR disclosures have been filed on this document.

(9) The document has been non-controversial and has wide support for release.

(10) There has been no controversy for this document.

(11) There re no nits in the -03 version, but a final check on the final document needs to be done.

(12) No external formal review is required for this document.

(13) All references are informative.  This is appropriate for the document.

(14) All references from this document are informative.  No normative references exist.

(15) There are no normative references.

(16) This is first time document and will not change the status of any other document.

(17) The document has no IANA considerations.  I have verified that this is appropriate.

(18) The document has no IANA considerations. 

(19) There are no formal language sections of the document.