Subject: [OAUTH-WG] Barry Leiba's No Objection on draft-ietf-oauth-proof-of-possession-09: (with COMMENT)

From: "Barry Leiba" <[email-masked]>
Date: Tue, 15 Dec 2015 14:22:09 -0800

Barry Leiba has entered the following ballot position for
draft-ietf-oauth-proof-of-possession-09: No Objection

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 https://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:
https://datatracker.ietf.org/doc/draft-ietf-oauth-proof-of-possession/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

The Abstract and Introduction both say something like this:

   This specification defines how a JSON Web Token (JWT) [JWT] can
   declare that the presenter of the JWT possesses a key and that the
   recipient can cryptographically confirm that the presenter possesses
   that key.

The JWT doesn't declare that the presenter possesses the key; it declares
that the presenter *must* possess the key... yes?  Shouldn't this say
that?:

NEW
   This specification defines how a JSON Web Token (JWT) [JWT] can
   declare that the presenter of the JWT must possess a key and how
   the recipient can cryptographically confirm that the presenter
   possesses that key.
END

(Also notice change from "that" to "how".)

   This
   specification defines how to communicate key confirmation key
   information in JWTs.

"key confirmation key information" seems odd and hard to follow.  I think
"key information used in key confirmation" is a better way to say it. 
But perhaps the sentence as a whole could be better phrased.  Does
something like this work?:

NEW
   This specification defines how to imbed into the JWT the key
   information that is used in key confirmation.
END

-- Section 2 --
Minor, very unimportant point: There's no reason to put, for example,
"(JWT)", when the citation "[JWT]" immediately follows it.  I suggest
just using the citation to provide the abbreviation, and eliminating
"(JWT)", "(JWK)", and "(JWE)".  But very unimportant; do, or don't, and
no need to respond to this item.

-- Section 3 --

   The issuer of a JWT declares that the presenter possesses a
   particular key and that the recipient can cryptographically confirm
   proof-of-possession of the key by the presenter by including a "cnf"
   (confirmation) claim in the JWT whose value is a JSON object.

I was convinced that this wasn't right until I read it for about the
eighth time.  It sounds like the recipient includes the "cnf" claim in
the JWT, when it's actually the issuer.  That happens when long sentences
have too many qualifiers strung together.  How about this?:

NEW
   By including a "cnf" (confirmation) claim in a JWT, the issuer
   of the JWT declares that the presenter possesses a particular key,
   and that the recipient can cryptographically confirm that the
   presenter has proof-of-possession of that key.  The value in the
   cnf claim is a JSON object, and members in that object identify
   the proof-of-possession key.
END

-- Section 3.5 --

   The protocol used to acquire the resource MUST provide integrity
   protection; an HTTP GET request to retrieve the JWK Set MUST use
   Transport Layer Security (TLS) [RFC5246]; and the identity of the
   server MUST be validated, as per Section 6 of RFC 6125 [RFC6125].

Little editorial punctuational nonsense: I would make the first semicolon
a colon instead (or perhaps a period), and I would then make the second
semicolon a comma.

-- Section 4 --
In the last paragraph, can you provide a reference for "audience
restriction"?

-- Section 6 --
Can we get this fixed in all the OAuth and JOSE documents?  It's getting
old having to make the same comment for every document:  We should not be
trying to set up IANA processes in our IANA Considerations.  The fourth
and sixth paragraphs aren't appropriate here: IANA coordinates and tracks
registration requests, and all requests should go to IANA.  IANA will
contact the DEs, not the other way around.  The authors have seen this
comment from me before....

---

From: Mike Jones <[email-masked]>
Date: Wed, 16 Dec 2015 23:53:57 +0000

Hi Barry,

Thanks for your review.  Please see my responses inline below...

> -----Original Message-----
> From: Barry Leiba [mailto:[email-masked]]
> Sent: Tuesday, December 15, 2015 11:22 PM
> To: The IESG <[email-masked]>
> Cc: [email-masked]; [email-masked];
> [email-masked]; [email-masked]
> Subject: Barry Leiba's No Objection on draft-ietf-oauth-proof-of-possession-
> 09: (with COMMENT)
> 
> 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.)
> 
> 

How about this version instead?

"This specification defines how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of-possession key and that the recipient can cryptographically confirm proof-of-possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key."

The proposed "must possess" wording for some reason sounds awkward to my ear and the "must" is redundant, since for the statement "the recipient can cryptographically confirm proof-of-possession of the key" to be true, the presenter must possess the key.

A change from "that" to "how" would imply something that isn't true - that this spec says *how* the recipient conforms proof of possession.  The conformation protocol message(s) used for particular applications are explicitly out of scope for this specification.  If we said "how", readers would later feel cheated. Thus, I haven't made this change.

>    information that is used in key confirmation.

I agree that the sentence you cited is awkward.  How about this instead?

"This specification defines how to communicate information about the proof-of-possession key using a claim in a JWT."

> "(JWT)", when the citation "[JWT]" immediately follows it.  I suggest just
> using the citation to provide the abbreviation, and eliminating "(JWT)",
> "(JWK)", and "(JWE)".  But very unimportant; do, or don't, and no need to
> respond to this item.

OK

> I was convinced that this wasn't right until I read it for about the eighth time.
> It sounds like the recipient includes the "cnf" claim in the JWT, when it's
> actually the issuer.  That happens when long sentences have too many
> qualifiers strung together.  How about this?:
> 
> NEW

Sounds good

> Little editorial punctuational nonsense: I would make the first semicolon a
> colon instead (or perhaps a period), and I would then make the second
> semicolon a comma.

I agree this is currently overly fussy.  I'll change the first semicolon to a period and remove the second.

> -- Section 4 --
> In the last paragraph, can you provide a reference for "audience restriction"?

Sure - I'll cite JWT 4.1.3 - the "aud" claim.

> -- Section 6 --
> Can we get this fixed in all the OAuth and JOSE documents?  It's getting old
> having to make the same comment for every document:  We should not be
> trying to set up IANA processes in our IANA Considerations.  The fourth and
> sixth paragraphs aren't appropriate here: IANA coordinates and tracks
> registration requests, and all requests should go to IANA.  IANA will contact
> the DEs, not the other way around.  The authors have seen this comment
> from me before....

Fair enough.  I'll delete these paragraphs, moving the 21-day time period sentence to another location. 

I'll now work on applying these resolutions to the specification and then will republish.

				Thanks again!
				-- Mike

---

From: Barry Leiba <[email-masked]>
Date: Wed, 16 Dec 2015 22:02:41 -0500

> Thanks for your review.  Please see my responses inline below...

And thanks for your responses.  All OK, including the alternatives you
gave to my suggestions.  Thanks, as always, for addressing my
comments.

Barry

---

From: Mike Jones <[email-masked]>
Date: Thu, 17 Dec 2015 03:13:05 +0000

Draft -10 is posted, which addresses your ballot comments.

				Thanks again,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Barry Leiba
Sent: Thursday, December 17, 2015 4:03 AM
To: Mike Jones <[email-masked]>
Cc: The IESG <[email-masked]>; [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: Barry Leiba's No Objection on draft-ietf-oauth-proof-of-possession-09: (with COMMENT)

> Thanks for your review.  Please see my responses inline below...

And thanks for your responses.  All OK, including the alternatives you gave to my suggestions.  Thanks, as always, for addressing my comments.

Barry