Subject: [OAUTH-WG] Review comments to PoP document

From: "Kepeng Li" <[email-masked]>
Date: Wed, 07 Oct 2015 22:29:54 +0800

Hello all,

Please find my review comments to PoP document:
http://tools.ietf.org/html/draft-ietf-oauth-proof-of-possession-04
 
1、        Title:

Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)
[Kepeng] Should we add OAuth 2.0 in the title? Also, in the whole document,
we use JWT, but in the title, we use “JWTs”. Is there a reason for this?
 
2、        Abstract：

1) This specification defines how to express a declaration in a JSON Web
Token (JWT) that the presenter of the JWT possesses a particular key and
that the recipient can cryptographically confirm proof-of-possession of the
key by the presenter.
[Kepeng] Add reference to JWT.
 
2) This property is also sometimes described as the presenter being a
holder-of-key.
[Kepeng] I am not sure what is “this property”. Do you mean “the key”? If
yes, just use the key. And change the sentence to something like: This key
is also sometimes described as a holder-of-key by the presenter.
 
3. Introduction
1) The first paragraph is the same as the abstract. I suggest to reword it a
little bit or remove it, to avoid the redundancy.
 
2) See [I-D.ietf-oauth-pop-architecture] for a further discussion of key
confirmation.
[Kepeng] I suggest to mention a little bit more about the relationship
between PoP architecture document and this document. In my understanding, in
PoP architecture document, it mentions several mechanisms: confidentiality
protection, key confirmation and sender constraint. This document introduces
the key semantics for the key confirmation mechanism.
 
3) About the two use cases, it will be useful to use two diagrams or flows
to indicate how it works. Maybe put these two flows in a separate section.
Also it will be useful to mention which step is in scope, and which is out
of scope, e.g. how to convey symmetric key from the issuer to the presenter.
 
4. Section 3:
1) It will be useful to put a reference to "sub" (subject) claim, and "iss"
(issuer) claim.
 
2) Note that if an application needs to represent multiple proof-of-
  possession keys in the same JWT, one way for it to achieve this is to
   use other claim names, in addition to "cnf", to hold the additional
  proof-of-possession key information.
[Kepeng] It is not clear, what are the other claim names?

Kind Regards
Kepeng

---

From: Mike Jones <[email-masked]>
Date: Thu, 8 Oct 2015 17:58:34 +0000

Thanks for the useful review, Kepeng.  Responses inline…

From: OAuth [mailto:[email-masked]] On Behalf Of Kepeng Li
Sent: Wednesday, October 07, 2015 7:30 AM
To: [email-masked]
Subject: [OAUTH-WG] Review comments to PoP document

Hello all,

Please find my review comments to PoP document:
http://tools.ietf.org/html/draft-ietf-oauth-proof-of-possession-04<https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2ftools.ietf.org%2fhtml%2fdraft-ietf-oauth-proof-of-possession-04&data=01%7c01%7cMichael.Jones%40microsoft.com%7c39fc367bfc044fe9243c08d2cf23d95b%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=XNX89l21GzCoKDzkQufdN1vF9VsGqOpNpWp9M6yyqAQ%3d>

1、          Title:
Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)
[Kepeng] Should we add OAuth 2.0 in the title? Also, in the whole document, we use JWT, but in the title, we use “JWTs”. Is there a reason for this?

I wouldn’t suggest adding “OAuth 2.0” to the title, in part, because JWTs are used in contexts outside of OAuth.  As for why JWTs is plural here, the title is saying that PoP keys can be communicated in JSON Web Tokens.  If it were singular, it would sound like you could only use PoP keys in a single JWT, which isn’t right.

2、          Abstract：
1) This specification defines how to express a declaration in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular key and that the recipient can cryptographically confirm proof-of-possession of the key by the presenter.
[Kepeng] Add reference to JWT.

I’ve been told when editing other drafts to remove references that I’d placed in abstracts, since IETF abstracts don’t include references.

2) This property is also sometimes described as the presenter being a holder-of-key.
[Kepeng] I am not sure what is “this property”. Do you mean “the key”? If yes, just use the key. And change the sentence to something like: This key is also sometimes described as a holder-of-key by the presenter.

I can change “This property” to “Being able to prove possession of a key”.

3. Introduction
1) The first paragraph is the same as the abstract. I suggest to reword it a little bit or remove it, to avoid the redundancy.

The rest of the introduction builds on the ideas introduced in the first two sentences (the content of the abstract). If they were to be removed, it would make the introduction confusing, as many people won’t start by reading the abstract, but will read the introduction independently.  (The introduction does add references, which cannot be present in the abstract.)  I’ll work with the other editors to see if they want to reword the first two sentences of the introduction and/or abstract to make them different from one another.

2) See [I-D.ietf-oauth-pop-architecture] for a further discussion of key confirmation.
[Kepeng] I suggest to mention a little bit more about the relationship between PoP architecture document and this document. In my understanding, in PoP architecture document, it mentions several mechanisms: confidentiality protection, key confirmation and sender constraint. This document introduces the key semantics for the key confirmation mechanism.

OK – we can say that [I-D.ietf-oauth-pop-architecture] describes key confirmation, among other conformation mechanisms, and that this specification defines how to communicate key confirmation key information in JWTs.

3) About the two use cases, it will be useful to use two diagrams or flows to indicate how it works. Maybe put these two flows in a separate section. Also it will be useful to mention which step is in scope, and which is out of scope, e.g. how to convey symmetric key from the issuer to the presenter.

Both are in scope, which is why they’re both described in the introduction.  I’ll work with the other editors on trying to create appropriate diagrams.

4. Section 3:
1) It will be useful to put a reference to "sub" (subject) claim, and "iss" (issuer) claim.

OK

Fair point.  We can say that those claim names would be defined by applications and could be registered in the JWT Claims Registry.

Kind Regards
Kepeng

                                                            Thanks again!
                                                            -- Mike

---

From: "Kepeng Li" <[email-masked]>
Date: Fri, 09 Oct 2015 09:04:00 +0800

Hi Mike,

Thanks for your responses.

About the first paragraph in the introduction, I would prefer to make it
different from the same one in the abstract.

I am fine with others.

Kind Regards
Kepeng

发件人:  Mike Jones <[email-masked]>
日期:  Friday, 9 October, 2015 1:58 am
至:  Li Kepeng <[email-masked]>, "[email-masked]"
<[email-masked]>
主题:  RE: Review comments to PoP document

Hello all,

http://tools.ietf.org/html/draft-ietf-oauth-proof-of-possession-04
<https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2ftools.ietf.
org%2fhtml%2fdraft-ietf-oauth-proof-of-possession-04&data=01%7c01%7cMichael.
Jones%40microsoft.com%7c39fc367bfc044fe9243c08d2cf23d95b%7c72f988bf86f141af9
1ab2d7cd011db47%7c1&sdata=XNX89l21GzCoKDzkQufdN1vF9VsGqOpNpWp9M6yyqAQ%3d>

1、         Title:

I wouldn’t suggest adding “OAuth 2.0” to the title, in part, because JWTs
are used in contexts outside of OAuth.  As for why JWTs is plural here, the
title is saying that PoP keys can be communicated in JSON Web Tokens.  If it
were singular, it would sound like you could only use PoP keys in a single
JWT, which isn’t right.
 
2、         Abstract：

I’ve been told when editing other drafts to remove references that I’d
placed in abstracts, since IETF abstracts don’t include references.

 
3. Introduction
 
The rest of the introduction builds on the ideas introduced in the first two
sentences (the content of the abstract). If they were to be removed, it
would make the introduction confusing, as many people won’t start by reading
the abstract, but will read the introduction independently.  (The
introduction does add references, which cannot be present in the abstract.)
I’ll work with the other editors to see if they want to reword the first two
sentences of the introduction and/or abstract to make them different from
one another.

OK – we can say that [I-D.ietf-oauth-pop-architecture] describes key
confirmation, among other conformation mechanisms, and that this
specification defines how to communicate key confirmation key information in
JWTs.

Both are in scope, which is why they’re both described in the introduction.
I’ll work with the other editors on trying to create appropriate diagrams.
 
4. Section 3:
 
OK

Fair point.  We can say that those claim names would be defined by
applications and could be registered in the JWT Claims Registry.
 
Kind Regards
Kepeng
 
                                                            Thanks again!
                                                            -- Mike

---

From: Mike Jones <[email-masked]>
Date: Mon, 19 Oct 2015 23:02:23 +0000

Hi Kepeng,

Draft -05 addresses all your review comments as agreed below, other than adding the diagrams that you requested.  I’ll plan on working on those between now and Yokohama and submitting an updated draft with the diagrams when the submission period opens.

Thanks again for your useful review of this draft.  I added you to the acknowledgements.

                                                            Best wishes,
                                                            -- Mike

From: Kepeng Li [mailto:[email-masked]]
Sent: Thursday, October 08, 2015 6:04 PM
To: Mike Jones; [email-masked]
Subject: Re: Review comments to PoP document

Hi Mike,

About the first paragraph in the introduction, I would prefer to make it different from the same one in the abstract.

I am fine with others.

Kind Regards
Kepeng

发件人: Mike Jones <[email-masked]<mailto:[email-masked]>>
日期: Friday, 9 October, 2015 1:58 am
至: Li Kepeng <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
主题: RE: Review comments to PoP document

From: OAuth [mailto:[email-masked]] On Behalf Of Kepeng Li
Sent: Wednesday, October 07, 2015 7:30 AM
To: [email-masked]<mailto:[email-masked]>
Subject: [OAUTH-WG] Review comments to PoP document

Hello all,

1、          Title:

2、          Abstract：

3. Introduction

4. Section 3:

OK

Kind Regards
Kepeng

                                                            Thanks again!
                                                            -- Mike

---

From: Mike Jones <[email-masked]>
Date: Mon, 19 Oct 2015 23:29:11 +0000

FYI, I posted about the availability of the new draft at http://self-issued.info/?p=1468 and as @selfissued<https://twitter.com/selfissued>.

From: OAuth [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Monday, October 19, 2015 4:02 PM
To: Kepeng Li; [email-masked]
Subject: Re: [OAUTH-WG] Review comments to PoP document

Hi Kepeng,

                                                            Best wishes,
                                                            -- Mike

From: Kepeng Li [mailto:[email-masked]]
Sent: Thursday, October 08, 2015 6:04 PM
To: Mike Jones; [email-masked]<mailto:[email-masked]>
Subject: Re: Review comments to PoP document

Hi Mike,

I am fine with others.

Kind Regards
Kepeng

Hello all,

1、          Title:

2、          Abstract：

3. Introduction

4. Section 3:

OK

Kind Regards
Kepeng

                                                            Thanks again!
                                                            -- Mike