Re: [OAUTH-WG] Barry Leiba's Discuss on draft-ietf-oauth-json-web-token-27: (with DISCUSS and COMMENT)

[Mike Jones <[e-mail]>]

Thanks for your review, Barry.  I'm adding the working group so they’re aware of these comments.  At Stephen Farrell's request, I'm responding with "> " line prefixes on previous thread content.  I'm also repeating (and in the first case, augmenting) my previous responses to the DISCUSS comments in this consolidated message.

> -----Original Message-----
> From: Barry Leiba [mailto:[e-mail]]
> Sent: Wednesday, October 01, 2014 8:54 AM
> To: The IESG
> Cc: [e-mail]; draft-ietf-oauth-json-web-
> [e-mail]
> Subject: Barry Leiba's Discuss on draft-ietf-oauth-json-web-token-27: (with
> DISCUSS and COMMENT)
> 
> Barry Leiba has entered the following ballot position for
> draft-ietf-oauth-json-web-token-27: Discuss
> 
> When responding, please keep the subject line intact and reply to all email
> addresses included in the To and CC lines. (Feel free to cut this introductory
> paragraph, however.)
> 
> 
> Please refer to http://www.ietf.org/iesg/statement/discuss-criteria.html
> for more information about IESG DISCUSS and COMMENT positions.
> 
> 
> The document, along with other ballot positions, can be found here:
> http://datatracker.ietf.org/doc/draft-ietf-oauth-json-web-token/
> 
> 
> 
> ----------------------------------------------------------------------
> DISCUSS:
> ----------------------------------------------------------------------
> 
> I have two points that I'd like to get resolved before happily approving this fine
> document:
> 
> -- Section 7.1 --
> 
> The comparison you specify is as specified in RFC 7159, Section 8.3, which is to
> "transform the textual representation into sequences of Unicode code units and
> then perform the comparison numerically, code unit by code unit".  This has no
> regard for text case, and so it's a case-sensitive comparison.
> 
> And, yet, Sections 5.1 and 5.2 specify that the values of typ and cty are case-
> insensitive, and specify using upper case as a SHOULD, for "compatibility with
> legacy implementations".
> 
> It doesn't seem that "legacy" has anything to do with this: someone conforming
> to *this* specification will compare the values of typ and cty Unicode-character
> by Unicode-character, and will fail to match "JWT" with "jwt".
> 
> Is there not a problem here?

We can update the text to clarify that MIME type comparisons are an exception to the “code unit by code unit” comparison rule.  The drafts will also be scrutinized for other possible occurrences of exceptions to the default string comparison instructions.  Finally, we can add language to 7.1 about "unless otherwise noted for a particular kind of string" so that it's clear that there are exceptions to the rule.

> -- Section 10.3.1 --
> 
> Nice that you cite 2046 for media types, but the *registration* of media types is
> documented in RFC 6838, and this document doesn't quite conform to that.  The
> only thing missing in the doc is "Fragment identifier considerations" in the
> registration template, but 6838 also strongly suggests review of the media-type
> registration on the media-types mailing list.  Given that this will not get expert
> review (because it's an IETF-stream RFC), I'd like to ask for an explicit review on
> the media-types list to make sure that the registration information is complete
> and makes sense.

Thanks for the 6833 reference.  We’ll use that.  I know that Kathleen already initiated the review on the media-types list.
 
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
> 
> -- Abstract --
> 
>    The suggested pronunciation of JWT is the same as the English word
>    "jot".
> 
> I have no objection (well, I do, but it's not for me to say how you want to
> pronounce it) to having this sentence in the Introduction, but it seems out of
> place in the Abstract, which is meant to be concise.

OK - We can remove it from the Abstract.

> -- Section 4.1 --
> 
> It appears that all claims defined here are OPTIONAL, and each one says so in its
> subsection.  Given that they *all* are, it might be useful to say that up front,
> maybe with a sentence that says, "All claims defined in this section are
> OPTIONAL to use."  (I don't feel strongly about this; it's just a suggestion, so do
> with it as you see best.)  See also my comment on 10.1.1, below.

Editorially, we decided to describe the optionality of each claim in the claim definition so that when used as a reference without reading the whole thing, the optionality will still be obvious to the reader.

> -- Section 4.1.2 --
> 
>    The subject value MAY be scoped to be locally
>    unique in the context of the issuer or MAY be globally unique.
> 
> Or it MAY be anything else, including not unique at all.  Is that what you mean?
> Or are these meant to be two options, one of which has to be true?  If so, you
> need to re-do this, perhaps like this:
> 
> NEW
>   The subject value MUST either be globally unique, or be scoped
>   to be locally unique in the context of the issuer.
> END

Your new language matches the intent.  I'll plan to revise accordingly.

> -- Section 10.1.1 --
> 
> Given that the descriptions of the claims include a statement that their use is
> OPTIONAL, should there not be an entry in the table that says whether the claim
> is OPTIONAL or REQUIRED ?  Or is it the intent that
> *all* of them always be OPTIONAL ?  Or is it sufficient to have that indication in
> the reference documentation ?

What claims are required by applications will be specified by applications.  For instance, some applications using JWTs require that the issuer, subject, and audience be present.  Therefore, I don't think that adding a table entry would help a great deal, and it could even confuse some developers.

				-- Mike