Subject: [secdir] sector review of draft-ietf-jose-jwk-thumbprint-05

From: "Adam W. Montville" <[email-masked]>
Date: Mon, 8 Jun 2015 10:46:29 -0500

Hi,

I have reviewed this document as part of the security directorate's ongoing effort to review all IETF documents being processed by the IESG. These comments were written primarily for the benefit of the security area directors. Document editors and WG chairs should treat these comments just like any other last call comments.

I believe the document is ready with (potential) issues.  The “with issues” might be due to ignorance on my part.  The draft does a very good job of explaining the canonical form of a JSON Web Key that can be used for establishing a thumbprint under varying circumstances, complete with what I found to be helpful examples.

The primary issue I have is that it’s unclear how relying parties are going to know which hash algorithm has been used.  The examples use SHA-256, but I’m not seeing where SHA-256 might be specified as a MUST or even a SHOULD.  Moreover, the example output ultimately shows only the Base-64 encoding of the resulting hash, which says nothing about the algorithm used to identify a key.

Additionally, in Section 4, “JSON and Unicode Considerations” some “should”s are used, but I’m not reading them as SHOULDs.  Should they be SHOULDs?  For example, the start of the third paragraph in that section: “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.”  It’s not clear to me whether this is a strong statement or just a recommendation - it seems that this draft could help the future by making stronger statements to encourage future interoperability.

Kind regards,

Adam

---

From: Mike Jones <[email-masked]>
Date: Thu, 11 Jun 2015 21:25:22 +0000

Hi Adam,

Thanks for the secdir review.

> From: Adam W. Montville [mailto:[email-masked]]
> Sent: Monday, June 08, 2015 8:46 AM
> To: The IESG; [email-masked]; [email-masked]
> Subject: sector review of draft-ietf-jose-jwk-thumbprint-05

> The primary issue I have is that it’s unclear how relying parties are going to know which hash algorithm has been used.  The examples use SHA-256, but I’m not seeing where SHA-256 might be specifie…

Earlier drafts had included fields whose names were intended to communicate the information about the hash function used - see the "jkt" field definitions in http://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-01#section-4 - but several working group reviewers suggested that these fields were unnecessary and that the typical usage would be as "kid" (key ID) field values.  With that removal, it falls onto the application to specify the hash algorithm for its particular usage.

This isn't as bad as you might think, however, because typically the consumer of the "kid" doesn't need to know the algorithm because it won't be reproducing the computation.  It just relies on the fact that a unique key ID value was generated for the key and compares "kid" values as opaque strings to find the appropriate key.  In this usage, the producer of the key is the only party that needs to know the hash algorithm that it is using.  I hope this helps.

> Additionally, in Section 4, “JSON and Unicode Considerations” some “should”s are used, but I’m not reading them as SHOULDs.  Should they be SHOULDs?  For example, the start of the third paragraph i…

For the other JOSE specifications, our chair Jim Schaad took the position that RFC 2119 keywords should be reserved for testable protocol behaviors and that other uses of the English word "should" should not use "SHOULD".  The authors followed that convention in this document.  I do understand that other authors and working groups have taken different positions in this regard.  If there are particular uses that you still feel should be changed to use RFC 2119 keywords, please call them out.

> Adam

				Thanks again!
				-- Mike

---

From: "Jim Schaad" <[email-masked]>
Date: Thu, 11 Jun 2015 15:35:40 -0700

> -----Original Message-----
> From: Mike Jones [mailto:[email-masked]]
> Sent: Thursday, June 11, 2015 2:25 PM
> To: Adam W. Montville; The IESG; [email-masked]; draft-ietf-jose-jwk-
> [email-masked]
> Cc: [email-masked]
> Subject: RE: sector review of draft-ietf-jose-jwk-thumbprint-05
> 
> Hi Adam,
> 
> > I have reviewed this document as part of the security directorate's ongoing
> effort to review all IETF documents being processed by the IESG. These
> comments were written primarily for the benefit of the security area directors.
> Document editors and WG chairs should treat these comments just like any
> other last call comments.
> >
> > I believe the document is ready with (potential) issues.  The “with issues” might
> be due to ignorance on my part.  The draft does a very good job of explaining
> the canonical form of a JSON Web Key that can be used for establishing a
> thumbprint under varying circumstances, complete with what I found to be
> helpful examples.
> >
> > The primary issue I have is that it’s unclear how relying parties are going to
> know which hash algorithm has been used.  The examples use SHA-256, but I’m
> not seeing where SHA-256 might be specified as a MUST or even a SHOULD.
> Moreover, the example output ultimately shows only the Base-64 encoding of
> the resulting hash, which says nothing about the algorithm used to identify a
> key.
> 
> Earlier drafts had included fields whose names were intended to communicate
> the information about the hash function used - see the "jkt" field definitions in
> http://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-01#section-4 - but
> several working group reviewers suggested that these fields were unnecessary
> and that the typical usage would be as "kid" (key ID) field values.  With that
> removal, it falls onto the application to specify the hash algorithm for its
> particular usage.
> 
> This isn't as bad as you might think, however, because typically the consumer of
> the "kid" doesn't need to know the algorithm because it won't be reproducing
> the computation.  It just relies on the fact that a unique key ID value was
> generated for the key and compares "kid" values as opaque strings to find the
> appropriate key.  In this usage, the producer of the key is the only party that
> needs to know the hash algorithm that it is using.  I hope this helps.
> 
> > Additionally, in Section 4, “JSON and Unicode Considerations” some “should”s
> are used, but I’m not reading them as SHOULDs.  Should they be SHOULDs?  For
> example, the start of the third paragraph in that section: “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.”  It’s not clear
> to me whether this is a strong statement or just a recommendation - it seems
> that this draft could help the future by making stronger statements to encourage
> future interoperability.
> 
> For the other JOSE specifications, our chair Jim Schaad took the position that
> RFC 2119 keywords should be reserved for testable protocol behaviors and that
> other uses of the English word "should" should not use "SHOULD".  The authors
> followed that convention in this document.  I do understand that other authors
> and working groups have taken different positions in this regard.  If there are
> particular uses that you still feel should be changed to use RFC 2119 keywords,
> please call them out.

If we really wanted to make sure that the recommendation was followed, then it would make sense to adjust the IANA reviewers instructions for the registry.  Putting a SHOULD or a MUST in this document would not have any effect since it does not define a protocol and might not be seen by anybody defining a new header field.

Jim

---

From: Mike Jones <[email-masked]>
Date: Thu, 11 Jun 2015 22:48:56 +0000

The registration instructions don't appear to be stored with the registry at http://www.iana.org/assignments/jose/jose.xhtml.  The closest there is there is the Reference field, which specifies [RFC7515], which I assume is how the designated experts are expected to retrieve the instructions.

Does anyone on the thread know if it's possible to add a copy of the registration instructions in the registry itself?  If so, then we'd have a mechanism by which we could update them, as Jim suggested.

				-- Mike

-----Original Message-----
From: Jim Schaad [mailto:[email-masked]] 
Sent: Thursday, June 11, 2015 3:36 PM
To: Mike Jones; 'Adam W. Montville'; 'The IESG'; [email-masked]; [email-masked]
Cc: [email-masked]
Subject: RE: sector review of draft-ietf-jose-jwk-thumbprint-05

> > To: The IESG; [email-masked]; 
> > [email-masked]
> Document editors and WG chairs should treat these comments just like 
> any other last call comments.
> >
> be due to ignorance on my part.  The draft does a very good job of 
> explaining the canonical form of a JSON Web Key that can be used for 
> establishing a thumbprint under varying circumstances, complete with 
> what I found to be helpful examples.
> >
> know which hash algorithm has been used.  The examples use SHA-256, 
> but I’m not seeing where SHA-256 might be specified as a MUST or even a SHOULD.
> Moreover, the example output ultimately shows only the Base-64 
> encoding of the resulting hash, which says nothing about the algorithm 
> used to identify a key.
> 
> Earlier drafts had included fields whose names were intended to 
> communicate the information about the hash function used - see the 
> "jkt" field definitions in
> http://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-01#section-4 
> - but several working group reviewers suggested that these fields were 
> unnecessary and that the typical usage would be as "kid" (key ID) 
> field values.  With that removal, it falls onto the application to 
> specify the hash algorithm for its particular usage.
> 
> This isn't as bad as you might think, however, because typically the 
> consumer of the "kid" doesn't need to know the algorithm because it 
> won't be reproducing the computation.  It just relies on the fact that 
> a unique key ID value was generated for the key and compares "kid" 
> values as opaque strings to find the appropriate key.  In this usage, 
> the producer of the key is the only party that needs to know the hash algorithm that it is using.  I hope this helps.
> 
> are used, but I’m not reading them as SHOULDs.  Should they be 
> SHOULDs?  For example, the start of the third paragraph in that 
> section: “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.”  It’s not clear to me whether this 
> is a strong statement or just a recommendation - it seems that this 
> draft could help the future by making stronger statements to encourage future interoperability.
> 
> For the other JOSE specifications, our chair Jim Schaad took the 
> position that RFC 2119 keywords should be reserved for testable 
> protocol behaviors and that other uses of the English word "should" 
> should not use "SHOULD".  The authors followed that convention in this 
> document.  I do understand that other authors and working groups have 
> taken different positions in this regard.  If there are particular 
> uses that you still feel should be changed to use RFC 2119 keywords, please call them out.

Jim

---

From: "Jim Schaad" <[email-masked]>
Date: Thu, 11 Jun 2015 17:00:06 -0700

I would do this by including an IANA considerations section that states you are updating the expert review instructions for a registry.  They will then include that in the list of references for the registry itself.

Jim

> Sent: Thursday, June 11, 2015 3:49 PM
> To: Jim Schaad; 'Adam W. Montville'; 'The IESG'; [email-masked]; draft-ietf-jose-
> [email-masked]
> Cc: [email-masked]
> The registration instructions don't appear to be stored with the registry at
> http://www.iana.org/assignments/jose/jose.xhtml.  The closest there is there is
> the Reference field, which specifies [RFC7515], which I assume is how the
> designated experts are expected to retrieve the instructions.
> 
> Does anyone on the thread know if it's possible to add a copy of the registration
> instructions in the registry itself?  If so, then we'd have a mechanism by which
> we could update them, as Jim suggested.
> 
> 				-- Mike
> 
> > the producer of the key is the only party that needs to know the hash
> algorithm that it is using.  I hope this helps.
> >
> If we really wanted to make sure that the recommendation was followed, then
> it would make sense to adjust the IANA reviewers instructions for the registry.
> Putting a SHOULD or a MUST in this document would not have any effect since it
> does not define a protocol and might not be seen by anybody defining a new
> header field.
> 
> Jim
> 
> >
> > > Kind regards,
> > > Adam
> >
> > 				Thanks again!
> > 				-- Mike
>

---

From: "Adam W. Montville" <[email-masked]>
Date: Fri, 12 Jun 2015 07:06:30 -0500

> On Jun 11, 2015, at 4:25 PM, Mike Jones <[email-masked]> wrote:
> 
> Hi Adam,
> 
> Earlier drafts had included fields whose names were intended to communicate the information about the hash function used - see the "jkt" field definitions in http://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-01#section-4 <http://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-01#section-4> - but several working group reviewers suggested that these fields were unnecessary and that the typical usage would be as "kid" (key ID) field values.  With that removal, it falls onto the application to specify the hash algorithm for its particular usage.
> 

Yes, this does help, thank you.  It seems like something that could be easily added to the draft to explain why the generating algorithm needn’t be disclosed so that slow folk like myself get the picture straight away.

> For the other JOSE specifications, our chair Jim Schaad took the position that RFC 2119 keywords should be reserved for testable protocol behaviors and that other uses of the English word "should"…

This is all good, too.  I was simply pointing out that there are “should”s around that may need to be considered as “SHOULD”s. I also see Jim’s (and others’) subsequent notes on the subject, so this is good from my perspective.

---

From: Mike Jones <[email-masked]>
Date: Mon, 22 Jun 2015 19:18:52 +0000

I’d be glad to add the explanation below to the draft and to also include an IANA considerations section that states we are updating the expert review instructions for a registry, as Jim Schaad had suggested.  Chairs and Kathleen, do you want Nat and I to proceed to publish an updated draft?

                                                                -- Mike

From: Adam W. Montville [mailto:[email-masked]]
Sent: Friday, June 12, 2015 5:07 AM
To: Mike Jones
Cc: The IESG; [email-masked]; [email-masked]; [email-masked]
Subject: Re: sector review of draft-ietf-jose-jwk-thumbprint-05

On Jun 11, 2015, at 4:25 PM, Mike Jones <[email-masked]<mailto:[email-masked]>> wrote:

Hi Adam,

From: Adam W. Montville [mailto:[email-masked]]
Sent: Monday, June 08, 2015 8:46 AM
To: The IESG; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: sector review of draft-ietf-jose-jwk-thumbprint-05

Hi,

Kind regards,
Adam

                                                                Thanks again!
                                                                -- Mike

---

From: Kathleen Moriarty <[email-masked]>
Date: Mon, 22 Jun 2015 21:51:20 +0200

Yes, thank you.
Kathleen 

Sent from my iPhone

> On Jun 22, 2015, at 9:18 PM, Mike Jones <[email-masked]> wrote:
>

---

From: Mike Jones <[email-masked]>
Date: Wed, 24 Jun 2015 08:40:19 +0000

Hi Adam,

Thanks again for your review comments.  https://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-06 has been posted to address them.  See sections 3.4 (Selection of Hash Function) and 6 (IANA Considerations).

                                                            Thanks again,
                                                            -- Nat and Mike

From: Kathleen Moriarty [mailto:[email-masked]]
Sent: Monday, June 22, 2015 12:51 PM
To: Mike Jones
Cc: Adam W. Montville; The IESG; [email-masked]; [email-masked]; [email-masked]
Subject: Re: sector review of draft-ietf-jose-jwk-thumbprint-05

Yes, thank you.
Kathleen

Sent from my iPhone

On Jun 22, 2015, at 9:18 PM, Mike Jones <[email-masked]<mailto:[email-masked]>> wrote:
I’d be glad to add the explanation below to the draft and to also include an IANA considerations section that states we are updating the expert review instructions for a registry, as Jim Schaad had suggested.  Chairs and Kathleen, do you want Nat and I to proceed to publish an updated draft?

                                                                -- Mike

From: Adam W. Montville [mailto:[email-masked]]
Sent: Friday, June 12, 2015 5:07 AM
To: Mike Jones
Cc: The IESG; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Re: sector review of draft-ietf-jose-jwk-thumbprint-05

Hi Adam,

Hi,

Kind regards,
Adam

                                                                Thanks again!
                                                                -- Mike

---

From: "Adam W. Montville" <[email-masked]>
Date: Wed, 24 Jun 2015 07:11:58 -0500

Hi Nat and Mike,

Thanks for your attention on this issue.  I see the following text in section 3.4:

Note that in many cases, only the party that creates a key will need
   to know the hash function used.  A typical usage is for the producer
   of the key to use the base64url-encoded JWK Thumbprint value as a
   "kid" (key ID) value.  The consumer of the "kid" treats it as an
   opaque value that it uses to select the key.  Only if multiple
   parties will be reproducing the JWK Thumbprint calculation for some
   reason, will parties other than the original producer of the JWK
   Thumbprint need to know which hash function was used.

Would it make the draft clearer if that last sentence were omitted?  The way this paragraph reads is such that draft considers and would allow for multiple parties generating key IDs, but then we’re back at not knowing which algorithm was chosen.  If that last sentence were omitted, this would be less of an issue.  

> On Jun 24, 2015, at 3:40 AM, Mike Jones <[email-masked]> wrote:
> 
> Hi Adam,
>  
> Thanks again for your review comments.  https://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-06 <https://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-06> has been posted to address them.  See sections 3.4 (Selection of Hash Function) and 6 (IANA Considerations).
>  
>                                                             Thanks again,
>                                                             -- Nat and Mike
>  
> On Jun 22, 2015, at 9:18 PM, Mike Jones <[email-masked] <mailto:[email-masked]>> wrote:
> 
> From: Adam W. Montville [mailto:[email-masked] <mailto:[email-masked]>] 
> Cc: The IESG; [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>
> On Jun 11, 2015, at 4:25 PM, Mike Jones <[email-masked] <mailto:[email-masked]>> wrote:
>  
> Hi Adam,
> 
> From: Adam W. Montville [mailto:[email-masked] <mailto:[email-masked]>]
> To: The IESG; [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>

---

From: Mike Jones <[email-masked]>
Date: Wed, 24 Jun 2015 17:49:09 +0000

Hi Adam,

I take your point that the paragraph would seem simpler without the last sentence, but I’d rather err on the side of giving readers more information than less.  While in many cases knowledge of the hash function used need not be propagated (per the example in the beginning of the paragraph), sometimes it does.  So Nat and I decided to also include a sentence about when it does.  Per the previous paragraph, which hash function to use is an application choice.

From that viewpoint, does the current paragraph work for you, or is there a specific wording change that you’d still like to see?

Thanks again for your review!

                                                            -- Mike

From: Adam W. Montville [mailto:[email-masked]]
Sent: Wednesday, June 24, 2015 5:12 AM
To: Mike Jones
Cc: The IESG; [email-masked]; [email-masked]; [email-masked]
Subject: Re: sector review of draft-ietf-jose-jwk-thumbprint-05

Hi Nat and Mike,

On Jun 24, 2015, at 3:40 AM, Mike Jones <[email-masked]<mailto:[email-masked]>> wrote:

Hi Adam,

                                                            Thanks again,
                                                            -- Nat and Mike

From: Kathleen Moriarty [mailto:[email-masked]]
Sent: Monday, June 22, 2015 12:51 PM
To: Mike Jones
Cc: Adam W. Montville; The IESG; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Re: sector review of draft-ietf-jose-jwk-thumbprint-05

Yes, thank you.
Kathleen

Sent from my iPhone

                                                                -- Mike

Hi Adam,

Hi,

Kind regards,
Adam

                                                                Thanks again!
                                                                -- Mike

---

From: "Adam W. Montville" <[email-masked]>
Date: Thu, 25 Jun 2015 16:32:38 -0500

I haven’t an objection to the paragraph as worded, so it works for me.  Should have made that clear before - sorry.

> On Jun 24, 2015, at 12:49 PM, Mike Jones <[email-masked]> wrote:
> 
> Hi Adam,
>  
> On Jun 24, 2015, at 3:40 AM, Mike Jones <[email-masked] <mailto:[email-masked]>> wrote:
>  
> Hi Adam,
>  
> From: Kathleen Moriarty [mailto:[email-masked] <mailto:[email-masked]>] 
> Cc: Adam W. Montville; The IESG; [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>