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

From: Mike Jones <[email-masked]>
Date: Tue, 14 Oct 2014 12:47:25 +0000

The proposed resolutions have been applied to the -28 draft.  Hopefully this will enable to clear your DISCUSSes.  Thanks again for the careful read!

				-- Mike

> -----Original Message-----
> From: OAuth [mailto:[email-masked]] On Behalf Of Mike Jones
> Sent: Saturday, October 04, 2014 5:17 PM
> To: Barry Leiba; The IESG
> Cc: [email-masked]; draft-ietf-oauth-json-web-
> [email-masked]; [email-masked]
> Subject: Re: [OAUTH-WG] Barry Leiba's Discuss on draft-ietf-oauth-json-web-
> token-27: (with DISCUSS and COMMENT)
> 
> 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:[email-masked]]
> > Sent: Wednesday, October 01, 2014 8:54 AM
> > To: The IESG
> > Cc: [email-masked]; draft-ietf-oauth-json-web-
> > [email-masked]
> > 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
> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Mon, 20 Oct 2014 15:44:41 +0000

Hi Barry,

Could you take a look at the text changes made and responses to your DISCUSS positions in the next few days?  We’re down to a week left to submit new drafts and if we need to make further changes for you, it would be good to know what they are before that.

In response to your first DISCUSS, the string comparison rules at http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-29#section-7.3 have been revised to reference the rules in RFC 7159, to explicitly list the exceptions for “typ” and “cty”, and to include the new last paragraph about including case-insensitive values as part of case-sensitive fields.

In response to your second, the drafts now reference RFC 6838, now include fragment identifier considerations and provisional registration entries, and Kathleen initiated the [email-masked] review on October 1st, with no objections having been voiced during the review.

The proposed resolutions were applied in response to your COMMENT positions too.

                                                            Thanks,
                                                            -- Mike

-----Original Message-----
From: Mike Jones [mailto:[email-masked]] 
Sent: Tuesday, October 14, 2014 5:47 AM
To: Barry Leiba; The IESG
Cc: [email-masked]; [email-masked]; [email-masked]
Subject: RE: Barry Leiba's Discuss on draft-ietf-oauth-json-web-token-27: (with DISCUSS and COMMENT)

				-- Mike

> 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,
> > 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
> > 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".
> >
> > 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".
> >
> 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 --
> >
> > 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
> Thanks for the 6833 reference.  We’ll use that.  I know that Kathleen 
> already initiated the review on the media-types list.
> 
> > 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.
> 
> 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 --
> >
> > 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
> > 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
> 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
>