Subject: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

From: Kathleen Moriarty <[email-masked]>
Date: Mon, 20 Apr 2015 15:23:41 -0400

Hi,

Thanks for your work on draft-ietf-jose-jwk-thumbprint-04.  This is the
last one, right?  Great job getting through the JOSE work!

I read through the draft and have mostly editorial comments that I'd like
to see if we can fix.

Section 2:
The definition needs some tweaking:

 JWK Thumbprint
      The digest value for a key that is the subject of this
      specification.

"the subject of this specification" should not part of text for a
definition.  The definition needs to clearly explain the term without
having to read the whole specification.  Can you suggest something else?

Section 4:

Can you break this sentence into 2:
However, if new JWK members are defined that use non-ASCII member
   names, their definitions should specify the exact Unicode code point
   sequences used to represent them, particularly in cases in which
   Unicode normalization could result in the transformation of one set
   of code points into another under any circumstances.

Can you get rid of the parens around the second sentence?
   Use of escaped characters in JWKs for which JWK Thumbprints will be
   computed should be avoided.  (Use of escaped characters in the hash
   input JWKs derived from these original JWKs is prohibited.)

Can you reword this sentence/paragraph?  I had to read it multiple times.
While I understand what you are saying, it could be easier to read.
   While there is a natural representation to use for numeric values
   that are integers, this specification does not attempt to define a
   standard representation for numbers that are not integers or that
   contain an exponent component.  This is not expected to be a problem
   in practice, as the required members of JWK representations are not
   expected to use numbers that are not integers.

General comment, the use of long sentences and frequency of parens make the
draft more difficult to read.

Thanks!

-- 

Best regards,
Kathleen

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 21 Apr 2015 10:46:52 -0400

Another thing has been bugging me since reading the draft yesterday and I'm
not sure if this was discussed in the WG or not.  There appear to be
differences in how a JWT thumbprint is described in the draft.  I'd like to
see if we can work this out before progress the draft into IETF last call.

The definition is not entirely clear.
Section 3 clearly states that the required members of the JWT are part of
the thumbprint.
Section 3.2.2, although the subtitle makes the point that this is about why
optional members are not included, the following sentence appears:

   The JWK Thumbprint value is a
   digest of the key value itself -- not of additional data that may
   also accompany the key.

Section 3.4 - Why is this allowed?  If it's not in JWT format, it is some
other kind of thumbprint. You are essentially creating a JWK to have the
key and required members I am assuming, but that's not clear and this text
could leave interoperability challenges.

Thanks,
Kathleen

On Mon, Apr 20, 2015 at 3:23 PM, Kathleen Moriarty <
[email-masked]> wrote:

> General comment, the use of long sentences and frequency of parens make
> the draft more difficult to read.
>
> Thanks!
>
> --
>
> Best regards,
> Kathleen
>

-- 

Best regards,
Kathleen

---

From: Mike Jones <[email-masked]>
Date: Tue, 21 Apr 2015 15:22:57 +0000

Hi Kathleen,

Thanks for taking the time to review the draft and write up today’s and yesterday’s comments.  Replies inline below…

From: jose [mailto:[email-masked]] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 7:47 AM
To: [email-masked]
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Another thing has been bugging me since reading the draft yesterday and I'm not sure if this was discussed in the WG or not.  There appear to be differences in how a JWT thumbprint is described in the draft.  I'd like to see if we can work this out before progress the draft into IETF last call.

The definition is not entirely clear.
Section 3 clearly states that the required members of the JWT are part of the thumbprint.
Section 3.2.2, although the subtitle makes the point that this is about why optional members are not included, the following sentence appears:

   also accompany the key.

3.2.2 was included in response to earlier review comments by Jim Schaad.  It’s there to motivate the particular choices made.  Is there some way in which you find 3 and 3.2.2 to be inconsistent?  3 is a positive statement about what’s included and the sentence in 3.2.2 that you quoted above is a negative statement about what’s not included, but that is consistent with the positive statement.  The negative statement is included to help readers understand the reasoning.  Is there some way in which you found it confusing or misleading?  Is there a particular change you might suggest to alleviate your concern?

Section 3.4 - Why is this allowed?  If it's not in JWT format, it is some other kind of thumbprint. You are essentially creating a JWK to have the key and required members I am assuming, but that's not clear and this text could leave interoperability challenges.

3.4 points out that the draft specifies a mathematical computation over a key value, which can be performed on any key.  It’s stating what’s possible, more than what’s stating what’s allowed.  Yes, you’re right that you’d be creating a JWK representation of the key value to create the thumbprint.  If a thumbprint of the key is needed, this may be a reasonable choice in some application contexts.

Thanks,
Kathleen

On Mon, Apr 20, 2015 at 3:23 PM, Kathleen Moriarty <[email-masked]<mailto:[email-masked]>> wrote:
Hi,

Thanks for your work on draft-ietf-jose-jwk-thumbprint-04.  This is the last one, right?  Great job getting through the JOSE work!

I read through the draft and have mostly editorial comments that I'd like to see if we can fix.

Section 2:

 JWK Thumbprint

"the subject of this specification" should not part of text for a definition.  The definition needs to clearly explain the term without having to read the whole specification.  Can you suggest something else?

Karen relayed text from Jim to me that I like and that will be used to improve the definition.  It was:

“This document defines a method for computing a hash value over a JSON Web Key structure.  The document describes what the subset of fields in a key to be used are, the method of creating a canonical form for those fields and how to convert the resulting UNICODE string into a byte sequence appropriate for hashing.”

Section 4:

OK

OK

Can you reword this sentence/paragraph?  I had to read it multiple times.  While I understand what you are saying, it could be easier to read.

OK

General comment, the use of long sentences and frequency of parens make the draft more difficult to read.

Thanks for pointing this out.  I’ll try to keep this in mind.

Thanks!

                                                            Thanks again!
                                                            -- Mike

--

Best regards,
Kathleen

--

Best regards,
Kathleen

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 21 Apr 2015 11:48:04 -0400

Hi Mike,

On Tue, Apr 21, 2015 at 11:22 AM, Mike Jones <[email-masked]>
wrote:

>  Hi Kathleen,
>
>
>
> Thanks for taking the time to review the draft and write up today’s and
> yesterday’s comments.  Replies inline below…
>
>
>
> *From:* jose [mailto:[email-masked]] *On Behalf Of *Kathleen
> Moriarty
> *Sent:* Tuesday, April 21, 2015 7:47 AM
> *To:* [email-masked]
> *Subject:* Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04
>
>
>
> Another thing has been bugging me since reading the draft yesterday and
> I'm not sure if this was discussed in the WG or not.  There appear to be
> Section 3.2.2, although the subtitle makes the point that this is about
> why optional members are not included, the following sentence appears:
>
> 3.2.2 was included in response to earlier review comments by Jim Schaad.
> It’s there to motivate the particular choices made.  Is there some way in
> which you find 3 and 3.2.2 to be inconsistent?  3 is a positive statement
> about what’s included and the sentence in 3.2.2 that you quoted above is a
> negative statement about what’s not included, but that is consistent with
> the positive statement.  The negative statement is included to help readers
> understand the reasoning.  Is there some way in which you found it
> confusing or misleading?  Is there a particular change you might suggest to
> alleviate your concern?
>
>
It is confusing.  Is this a thumbprint of the JWT or just the key?  If it's
just the key, it should be called a Key thumbprint.  If it is of the JWK
members that includes a key, I'm fine with this being the "JWK
thumbprint".  If it's just of the key, the quoted sentence above is fine,
but if the JWK required members are included and it's not just the key, you
have conflicting statements.

> 3.4 points out that the draft specifies a mathematical computation over a
> key value, which can be performed on any key.  It’s stating what’s
> possible, more than what’s stating what’s allowed.  Yes, you’re right that
> you’d be creating a JWK representation of the key value to create the
> thumbprint.  If a thumbprint of the key is needed, this may be a reasonable
> choice in some application contexts.
>

Again, is this a "Key Thumbprint" or a "JWK Thumbprint".  The draft needs
to be consistent and use the correct term depending on what type of
thumbprint this is.  I'm assuming JWK Thumbprint, that is kind of similar
to a certificate thumbprint in that it's over a full set of data and not
just the key (JWK or certificate in the case of X.509).

I hope that further clarifies why I find the text confusing.

> “This document defines a method for computing a hash value over a JSON Web
> Key structure.  The document describes what the subset of fields in a key
> to be used are, the method of creating a canonical form for those fields
> and how to convert the resulting UNICODE string into a byte sequence
> appropriate for hashing.”
>

That helps to improve the abstract and introduction, thank you.  How about
the definition of JWK Thumbprint?  It should not include things like "this
specification" or "this document".  It should be a stand alone definition.

> Thanks for pointing this out.  I’ll try to keep this in mind.

Great, thanks!
Kathleen

-- 

Best regards,
Kathleen

---

From: "Jim Schaad" <[email-masked]>
Date: Tue, 21 Apr 2015 10:36:43 -0700

Kathleen,

Some of you message is confusing me.  You keep referring to JWT in it.  Are you doing this as JW Token or JW Thumbprint?  JWT is currently “reserved” for the token and thus it is being confused.   Can you clarify?

Jim

From: jose [mailto:[email-masked]] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 8:48 AM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Hi Mike,

On Tue, Apr 21, 2015 at 11:22 AM, Mike Jones <[email-masked]> wrote:

Hi Kathleen,

[JLS] And I didn’t complain but it did not do a good job of what I asked it to do.  

It is confusing.  Is this a thumbprint of the JWT or just the key?  If it's just the key, it should be called a Key thumbprint.  If it is of the JWK members that includes a key, I'm fine with this being the "JWK thumbprint".  If it's just of the key, the quoted sentence above is fine, but if the JWK required members are included and it's not just the key, you have conflicting statements.

Again, is this a "Key Thumbprint" or a "JWK Thumbprint".  The draft needs to be consistent and use the correct term depending on what type of thumbprint this is.  I'm assuming JWK Thumbprint, that is kind of similar to a certificate thumbprint in that it's over a full set of data and not just the key (JWK or certificate in the case of X.509).

 

Thanks,

Kathleen

On Mon, Apr 20, 2015 at 3:23 PM, Kathleen Moriarty <[email-masked]> wrote:

Hi,

Section 2:

 JWK Thumbprint

      specification.

That helps to improve the abstract and introduction, thank you.  How about the definition of JWK Thumbprint?  It should not include things like "this specification" or "this document".  It should be a stand alone definition.

Section 4:

OK

OK

OK

Great, thanks!

Kathleen 

Thanks!

                                                            Thanks again!

                                                            -- Mike

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 21 Apr 2015 13:43:05 -0400

Hi Jim,

On Tue, Apr 21, 2015 at 1:36 PM, Jim Schaad <[email-masked]> wrote:

> Kathleen,
>
>
>
> Some of you message is confusing me.  You keep referring to JWT in it.
> Are you doing this as JW Token or JW Thumbprint?  JWT is currently
> “reserved” for the token and thus it is being confused.   Can you clarify?
>

Sorry, I meant JWK.

Kathleen

> *Sent:* Tuesday, April 21, 2015 8:48 AM
> *To:* Mike Jones
> *Cc:* [email-masked]
> It is confusing.  Is this a thumbprint of the JWT or just the key?  If
> it's just the key, it should be called a Key thumbprint.  If it is of the
> JWK members that includes a key, I'm fine with this being the "JWK

-- 

Best regards,
Kathleen

---

From: Mike Jones <[email-masked]>
Date: Tue, 21 Apr 2015 17:43:23 +0000

Jim, I assumed that her uses of JWT were typos for JWK.

Kathleen, thanks for clarifying what you found confusing.  I’ll think about it some more, but my initial reaction is that the name “JWK Thumbprint” is appropriate because it specifies a thumbprint computation over a JWK representation of a key.  Even if, per Section 3.4, the key didn’t start life as a JWK, the thumbprint computation specified creates a JWK representation of the key and hashes it.  Hence “JWK Thumbprint”.  I’ll think some more, particularly when revising the introduction and definitions, about how to make this clearer.

                                                            Thanks again,
                                                            -- Mike

From: Jim Schaad [mailto:[email-masked]]
Sent: Tuesday, April 21, 2015 10:37 AM
To: 'Kathleen Moriarty'; Mike Jones
Cc: [email-masked]
Subject: RE: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Kathleen,

Jim

From: jose [mailto:[email-masked]] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 8:48 AM
To: Mike Jones
Cc: [email-masked]<mailto:[email-masked]>
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Hi Mike,

On Tue, Apr 21, 2015 at 11:22 AM, Mike Jones <[email-masked]<mailto:[email-masked]>> wrote:
Hi Kathleen,

From: jose [mailto:[email-masked]<mailto:[email-masked]>] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 7:47 AM
To: [email-masked]<mailto:[email-masked]>
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

   also accompany the key.

Thanks,
Kathleen

Section 2:

 JWK Thumbprint

Section 4:

OK

OK

OK

Great, thanks!
Kathleen

Thanks!

                                                            Thanks again!
                                                            -- Mike

--

Best regards,
Kathleen

--

Best regards,
Kathleen

--

Best regards,
Kathleen

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 21 Apr 2015 13:48:28 -0400

Hi Mike,

>  Jim, I assumed that her uses of JWT were typos for JWK.
Yep, thanks.

>
>
> Kathleen, thanks for clarifying what you found confusing.  I’ll think
> about it some more, but my initial reaction is that the name “JWK
> Thumbprint” is appropriate because it specifies a thumbprint computation
> over a JWK representation of a key.  Even if, per Section 3.4, the key
> didn’t start life as a JWK, the thumbprint computation specified creates a
> JWK representation of the key and hashes it.  Hence “JWK Thumbprint”.  I’ll
> think some more, particularly when revising the introduction and
> definitions, about how to make this clearer.
>

I'm fine with the term "JWK Thumbprint" if it is clearly defined and used
consistently.  It's just not clear to me that it is a "Key fingerprint" as
well since required fields of the JWK are included in addition to the key.
In that respect, it is more like a certificate fingerprint that includes
the key and attributes of a certificate, but I understand it is a JWK
Thumbprint.

Thanks,
Kathleen

>
>
>                                                             Thanks again,
>
>                                                             -- Mike
>
>
>
> *From:* Jim Schaad [mailto:[email-masked]]
> *Sent:* Tuesday, April 21, 2015 10:37 AM
> *To:* 'Kathleen Moriarty'; Mike Jones
> *Cc:* [email-masked]
> *Subject:* RE: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04
>
>
>
> Kathleen,
>
>
>
> *From:* jose [mailto:[email-masked] <[email-masked]>] *On
> Behalf Of *Kathleen Moriarty

-- 

Best regards,
Kathleen

---

From: "Jim Schaad" <[email-masked]>
Date: Tue, 21 Apr 2015 13:06:11 -0700

Kathleen,

No it is really more like taking the hash of a SPKI.  The required fields match up closer to the OID for the algorithm ID and the components of the key.   

The entire reason that I wanted to have a good section on why optional items are not present, is that this is not similar to hashing a certificate because things like the user name (no JWK attribute) or key usage (either ‘uses’ or ‘key_opts’) values are not included as part of the hash.

My original hope for the addition to section 3.2.2 was to have text that clarified what it would mean to hash the optional fields vs what it means to just use the required fields.  And then justify the reasoning behind doing the equivalent of just hashing the SPKI of the JWK.

Jim

From: jose [mailto:[email-masked]] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 10:48 AM
To: Mike Jones
Cc: Jim Schaad; [email-masked]
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Hi Mike,

On Tue, Apr 21, 2015 at 1:43 PM, Mike Jones <[email-masked]> wrote:

Yep, thanks. 

I'm fine with the term "JWK Thumbprint" if it is clearly defined and used consistently.  It's just not clear to me that it is a "Key fingerprint" as well since required fields of the JWK are included in addition to the key.  In that respect, it is more like a certificate fingerprint that includes the key and attributes of a certificate, but I understand it is a JWK Thumbprint.

Thanks,

Kathleen 

                                                            Thanks again,

                                                            -- Mike

Kathleen,

Jim

Hi Mike,

Hi Kathleen,

 

 

Thanks,

Kathleen

Hi,

Section 2:

 JWK Thumbprint

      specification.

Section 4:

OK

OK

OK

Great, thanks!

Kathleen 

Thanks!

                                                            Thanks again!

                                                            -- Mike

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

---

From: Stephen Farrell <[email-masked]>
Date: Tue, 21 Apr 2015 21:16:29 +0100

On 21/04/15 21:06, Jim Schaad wrote:
> No it is really more like taking the hash of a SPKI.

Indeed;-) s/more like/just/ would produce a better outcome, but
I've said that before.

S.

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 21 Apr 2015 17:20:15 -0400

Jim,

On Tue, Apr 21, 2015 at 4:06 PM, Jim Schaad <[email-masked]> wrote:

> Kathleen,
>
>
>
> No it is really more like taking the hash of a SPKI.  The required fields
> match up closer to the OID for the algorithm ID and the components of the
> key.
>

OK, but it's not just the key as is stated in one sentence of this section.
  I'm just looking for consistency.

>
>
> The entire reason that I wanted to have a good section on why optional
> items are not present, is that this is not similar to hashing a certificate
> because things like the user name (no JWK attribute) or key usage (either
> ‘uses’ or ‘key_opts’) values are not included as part of the hash.
>
>
>
> My original hope for the addition to section 3.2.2 was to have text that
> clarified what it would mean to hash the optional fields vs what it means
> to just use the required fields.  And then justify the reasoning behind
> doing the equivalent of just hashing the SPKI of the JWK.
>

Once you update the text in the abstract and definition, could you please
update this section as well to make that intent clear and to make sure it
is consistent across all sections?  My issue in this section was that it
mentions repeatedly that the JWK Thumbprint is a digest of the key and it
doesn't include other data... but it does.  The JWK thumbprint include the
required JWK members, it's not just the key.  I see your point as to why
you wanted this text, but think the current text is confusing as it leaves
out that this is the JWK thumbprint of the required members of the JWK,
which includes the key.

Thanks,
Kathleen

Jim
> *Sent:* Tuesday, April 21, 2015 10:48 AM
> *To:* Mike Jones
> *Cc:* Jim Schaad; [email-masked]
>

-- 

Best regards,
Kathleen

---

From: Mike Jones <[email-masked]>
Date: Wed, 22 Apr 2015 20:37:37 +0000

Kathleen, Jim, and Karen – I assume that you want a new draft addressing these comments before proceeding to IETF & IESG review, correct?

                                                            -- Mike

P.S.  This likely won’t happen for a few days because the JOSE editors are in the midst of AUTH48 review for the core specs.  Yeah!

From: Kathleen Moriarty [mailto:[email-masked]]
Sent: Tuesday, April 21, 2015 2:20 PM
To: Jim Schaad
Cc: Mike Jones; [email-masked]
Subject: Re: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

Jim,

On Tue, Apr 21, 2015 at 4:06 PM, Jim Schaad <[email-masked]<mailto:[email-masked]>> wrote:
Kathleen,

OK, but it's not just the key as is stated in one sentence of this section.   I'm just looking for consistency.

Once you update the text in the abstract and definition, could you please update this section as well to make that intent clear and to make sure it is consistent across all sections?  My issue in this section was that it mentions repeatedly that the JWK Thumbprint is a digest of the key and it doesn't include other data... but it does.  The JWK thumbprint include the required JWK members, it's not just the key.  I see your point as to why you wanted this text, but think the current text is confusing as it leaves out that this is the JWK thumbprint of the required members of the JWK, which includes the key.

Thanks,
Kathleen

Jim

From: jose [mailto:[email-masked]<mailto:[email-masked]>] On Behalf Of Kathleen Moriarty
Sent: Tuesday, April 21, 2015 10:48 AM
To: Mike Jones
Cc: Jim Schaad; [email-masked]<mailto:[email-masked]>

Hi Mike,

On Tue, Apr 21, 2015 at 1:43 PM, Mike Jones <[email-masked]<mailto:[email-masked]>> wrote:
Jim, I assumed that her uses of JWT were typos for JWK.
Yep, thanks.

Thanks,
Kathleen

                                                            Thanks again,
                                                            -- Mike

From: Jim Schaad [mailto:[email-masked]<mailto:[email-masked]>]

Kathleen,

Jim

Hi Mike,

   also accompany the key.

Thanks,
Kathleen

Section 2:

 JWK Thumbprint

Section 4:

OK

OK

OK

Great, thanks!
Kathleen

Thanks!

                                                            Thanks again!
                                                            -- Mike

--

Best regards,
Kathleen

--

Best regards,
Kathleen

--

Best regards,
Kathleen

--

Best regards,
Kathleen

--

Best regards,
Kathleen

---

From: "Jim Schaad" <[email-masked]>
Date: Wed, 22 Apr 2015 13:40:53 -0700

Yes – a new draft would be good

I agree that the Auth48 takes precedence.

Jim

From: Mike Jones [mailto:[email-masked]] 
Sent: Wednesday, April 22, 2015 1:38 PM
To: Kathleen Moriarty; Jim Schaad
Cc: [email-masked]
Subject: RE: [jose] AD review of draft-ietf-jose-jwk-thumbprint-04

                                                            -- Mike

Jim,

Kathleen,

Thanks,

Kathleen

Jim

Hi Mike,

Yep, thanks. 

Thanks,

Kathleen 

                                                            Thanks again,

                                                            -- Mike

Kathleen,

Jim

Hi Mike,

Hi Kathleen,

 

 

Thanks,

Kathleen

Hi,

Section 2:

 JWK Thumbprint

      specification.

Section 4:

OK

OK

OK

Great, thanks!

Kathleen 

Thanks!

                                                            Thanks again!

                                                            -- Mike

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

-- 

Best regards,

Kathleen

---

From: Kathleen Moriarty <[email-masked]>
Date: Wed, 22 Apr 2015 17:45:52 -0400

Agreed & thanks.

On Wed, Apr 22, 2015 at 4:40 PM, Jim Schaad <[email-masked]> wrote:

> *From:* Mike Jones [mailto:[email-masked]]
> *Sent:* Wednesday, April 22, 2015 1:38 PM
> *To:* Kathleen Moriarty; Jim Schaad
>
> *Cc:* [email-masked]
> Kathleen, Jim, and Karen – I assume that you want a new draft addressing
> these comments before proceeding to IETF & IESG review, correct?
>
>
>
>                                                             -- Mike
>
>
>
> P.S.  This likely won’t happen for a few days because the JOSE editors are
> in the midst of AUTH48 review for the core specs.  Yeah!
>
>
>
> *From:* Kathleen Moriarty [mailto:[email-masked]
> <[email-masked]>]
> *Sent:* Tuesday, April 21, 2015 2:20 PM
> *To:* Jim Schaad
> *Cc:* Mike Jones; [email-masked]
> OK, but it's not just the key as is stated in one sentence of this
> section.   I'm just looking for consistency.
>
>
>

-- 

Best regards,
Kathleen