Subject: [jose] Pre-IESG-Evaluation notes on draft-ietf-jose-cookbook

From: Barry Leiba <[email-masked]>
Date: Fri, 5 Dec 2014 16:59:11 -0500

While I wait for Kathleen to put draft-ietf-jose-cookbook into IESG
Evaluation and issue a ballot, I'd like to send my comments:

I can't see how it's possible that all the JOSE documents and RFC 4648
are not normative references.  How can one possibly understand this
document without those?  And the JOSE documents are listed as defining
the terminology, so....

-- General --
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* put notes in the document to the RFC Editor wrapping each
instance of such text and making it clear that they must not alter the
text in any way... and then please check that during AUTH48.

-- 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 " " (U+0020 SPACE) characters to improve readability
   but are not present in the JWE plaintext or JWS payload.

Should that say that line breaks replace *some* space characters to
improve readability?  Not all of them were replaced, right?

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

Barry

---

From: ⌘ Matt Miller <[email-masked]>
Date: Tue, 9 Dec 2014 11:50:32 -0700

Hello Barry,

Thank you very much for your early review.  I have more comments inline.

On 12/5/14, 2:59 PM, Barry Leiba wrote:
> While I wait for Kathleen to put draft-ietf-jose-cookbook into
> IESG Evaluation and issue a ballot, I'd like to send my comments:
> 
> I can't see how it's possible that all the JOSE documents and RFC
> 4648 are not normative references.  How can one possibly understand
> this document without those?  And the JOSE documents are listed as
> defining the terminology, so....
> 

Good catch; I've put those references into a Normative References
section in -07.

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

I absolutely agree, and have been regularly soliciting people for
verifications and reviews.

> 
> 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* put notes in the document to the RFC Editor
> wrapping each instance of such text and making it clear that they
> must not alter the text in any way... and then please check that
> during AUTH48.
> 

I neglected this, but can add it to the next revision.  To be honest,
I feared sprinkling such notes throughout a document that is 50%-75%
example would have the opposite effect than that intended.  I have
been talking to RFC Editor folks about this document, and the
importance of leaving the importance of leaving the figures as-is.

> -- 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 " " (U+0020 SPACE) characters to improve
> readability but are not present in the JWE plaintext or JWS
> payload.
> 
> Should that say that line breaks replace *some* space characters
> to improve readability?  Not all of them were replaced, right?
> 

That is correct, and I have adjusted the text in -07 accordingly.

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

I will be sure to do so.  I could not get my installed version of
xml2rfc to cooperate with me, and I'm not inclined to modify the .txt
by hand (yet).

Thanks again!

- -- 
- - m&m

Matt Miller < [email-masked] >
Cisco Systems, Inc.

---

From: Barry Leiba <[email-masked]>
Date: Tue, 9 Dec 2014 15:00:12 -0500

Hey, Matt.

> verifications and reviews.

Groovy!

> importance of leaving the importance of leaving the figures as-is.

Ah, OK, that should be fine.  As long as the RFC Editor is aware of
where care needs to be taken, that should work... it's up to you
whether you think it needs to be marked in the text or whether your
conversations with the RFC Editor staff has been/will be sufficient.

Barry