Subject: [apps-discuss] AppsDir reviews of draft-ietf-jose-json-web-signature-32

From: Claudio Allocchio <[email-masked]>
Date: Thu, 2 Oct 2014 08:32:57 +0200 (CEST)

Helo Ray, many thanks!

the template and instructions are here:

http://trac.tools.ietf.org/area/app/trac/wiki/template

I'm doing the distrubion as said in the template,

thanks again!

------------------------------------------------------------------------------
Claudio Allocchio             G   A   R   R          [email-masked]
                         Senior Technical Officer
tel: +39 040 3758523      Italian Academic and       G=Claudio; S=Allocchio;
fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;

            PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca

---------- Forwarded message ----------
Date: Wed, 1 Oct 2014 20:21:42 -0700 (PDT)
From: Ray Polk <[email-masked]>
To: [email-masked]
Cc: [email-masked]
Subject: Re: URGENT AppsDir reviews of the JOSE document set - asigned drafts

Hi Claudio (and Mike),

I've finished reviewing draft-ietf-jose-json-web-signature-32 for AppsDir.  I could not find another AppsDir review on the jose mailing list to use as a model.  So, I don't know to whom I should send my review, the format it should take, or the severity of the issues to include (include Nits?  include minor, non-blocking issues?).

For now, I'll include all of my notes.  If you can advise me of proper format/protocol/procedure, I'll craft an email to the jose list.

Major:  None

Minor:

4.1.1. & 4.1.2. The links to Section 4.1 and Section 5.1 of JWA are incorrect.  They link to JWE instead of JWA.

In 4.1.1. the link is:
https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-4.1
...but it should be:
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-4.1

In 4.1.2. the link is:
https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-5.1
...but it should be:
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-5
(JWA doesn't seem to have an anchor for 5.1)

9. saying "separated by X period ('.') characters" is ambiguous:

JWSs have three segments separated by two period ('.') characters.
This means:  segment..segment..segment

JWEs have five segments separated by four period ('.') characters.
This means:  segment....segment....segment....segment....segment

Say instead:  ___s have X segments.  Each segment is separated from the next by a single period ('.') for a total of X-1 delimiting periods ('.').

Nit:

3.2 change "of these eight values," to "...values:", remove commas and the 'and', change "...with the six" to a complete sentence.
3.3 remove the and from "...to produce the JWE Encrypted Key and" and the period from the next bullet

4.1.3. fix comma splicing in:  "This Header Parameter MUST be integrity protected, and therefore MUST occur only within the JWE Protected Header, when used."  For example, "When used, this Header Parameter MUST be integrity protected; therefore, it MUST occur only within the JWE Protected Header."

Sections 4.1.4. through 4.1.10. are almost entirely redundant.  Combine them like so:

The following parameters have the same meaning, syntax, and processing rules as those defined in JWS, except that the certificate referenced by the thumbprint contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

jku defined in Section 4.1.2. of [JWS]
jwk defined in Section 4.1.3. of [JWS]
etc.

----- Original Message -----
From: [email-masked]
To: [email-masked]
Cc: [email-masked]
Sent: Saturday, September 27, 2014 1:42:40 PM GMT -07:00 US/Canada Mountain
Subject: Re: URGENT AppsDir reviews of the JOSE document set - asigned drafts

On Sat, 27 Sep 2014, Ray wrote:

> What is the goal review date? Literally as soon as possible?  I won't be able
> to start on mine till Monday at the earliest.

the IESG telechat is on Oct 2nd, thus Oct 1st max :-)

Sorry again for the late call... my original message never got to the list
(but I sent it from an airport...).

thanks Ray!

>
> -Ray
>
> On 9/27/2014 12:17 AM, Claudio Allocchio wrote:
>>
>> apart from Tobias, who said NAK :-( ... where are the others?
>>
>> this yar we had less pressure (less drafts to review) than the previous
>> one, but it does not mean we do not have to do the work.
>>
>> We all committed to do in average at least a review per month, is it?
>>
>> I know we are not so many and need new people, too... but at least let's do
>> the best we can, e.g. at lease say ACK or NAK ...
>>
>> many thanks!
>>
>>
>>
>> On Thu, 25 Sep 2014, Claudio Allocchio wrote:
>>
>>>
>>> Hello,
>>>
>>> as I did not get any answer to the message below, let's ask directly:
>>>
>>> draft-ietf-jose-json-web-algorithms-32
>>> - assigned to Carsten Bormann
>>>
>>> draft-ietf-jose-json-web-encryption-32
>>> - assigned to Tobias Gondrom
>>>
>>> draft-ietf-jose-json-web-key-32
>>> - assigned to Tony Hansen
>>>
>>> draft-ietf-jose-json-web-signature-32
>>> - assigned to Ray Polk
>>>
>>> Could you please ACK ?
>>>
>>> I know it is a very short time available (telechat on Oct 2nd!) and it's
>>> my late request... but let's try to do it.
>>>
>>> many thanks!
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Claudio Allocchio             G   A   R   R [email-masked]
>>>                        Senior Technical Officer
>>> tel: +39 040 3758523      Italian Academic and       G=Claudio;
>>> S=Allocchio;
>>> fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;
>>>
>>>           PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca
>>>
>>> ---------- Forwarded message ----------
>>> Date: Wed, 24 Sep 2014 18:15:13 +0200 (CEST)
>>> From: Claudio Allocchio <[email-masked]>
>>> To: [email-masked]
>>> Subject: [appsdir] URGENT AppsDir reviews of the JOSE document set
>>>
>>>
>>> Hi folks,
>>>
>>> due to my fault (thanks Barry for discovering that and sorry!), a request
>>> for AppsDir review of the JOSE document set never made it to this list!
>>>
>>> :-(
>>>
>>> draft-ietf-jose-json-web-algorithms-32
>>> draft-ietf-jose-json-web-encryption-32
>>> draft-ietf-jose-json-web-key-32
>>> draft-ietf-jose-json-web-signature-32
>>>
>>> Can we make an effort to take them on and try to make the reviews ASAP?
>>>
>>> Any volunteer (by tonght!) ?
>>>
>>> many thanks and sorry again!
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> Claudio Allocchio             G   A   R   R [email-masked]
>>>                        Senior Technical Officer
>>> tel: +39 040 3758523      Italian Academic and       G=Claudio;
>>> S=Allocchio;
>>> fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;
>>>
>>>           PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca
>>>
>>> _______________________________________________
>>> appsdir mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/listinfo/appsdir
>>>
>>> _______________________________________________
>>> appsdir mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/listinfo/appsdir
>>>
>>
>>
>> ------------------------------------------------------------------------------
>> Claudio Allocchio             G   A   R   R [email-masked]
>>                         Senior Technical Officer
>> tel: +39 040 3758523      Italian Academic and       G=Claudio;
>> S=Allocchio;
>> fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;
>>
>>            PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca
>
>

------------------------------------------------------------------------------
Claudio Allocchio             G   A   R   R          [email-masked]
                          Senior Technical Officer
tel: +39 040 3758523      Italian Academic and       G=Claudio; S=Allocchio;
fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;

             PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca

---

From: Mike Jones <[email-masked]>
Date: Wed, 15 Oct 2014 07:12:27 +0000

Thanks for your review Ray.  My apologies for not responding to it until now.  It had gotten sorted into a mail folder and I hadn't seen it until Kathleen brought it to my attention.  Responses are inline below...

> I've finished reviewing draft-ietf-jose-json-web-signature-32 for AppsDir.  I could
> not find another AppsDir review on the jose mailing list to use as a model.  So, I
> don't know to whom I should send my review, the format it should take, or the
> severity of the issues to include (include Nits?  include minor, non-blocking
> issues?).
> 
> For now, I'll include all of my notes.  If you can advise me of proper
> format/protocol/procedure, I'll craft an email to the jose list.
> 
> Major:  None
> 
> Minor:
> 

These link URLs are actually created by the IETF tools - not in the draft itself.  (You'll see "Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/" at the bottom of the drafts.)  I'm not sure who to file a bug on this with.

> Say instead:  ___s have X segments.  Each segment is separated from the next by
> a single period ('.') for a total of X-1 delimiting periods ('.').

Thanks - I'll plan to make this correction.

> Nit:
> 
> 3.2 change "of these eight values," to "...values:", remove commas and the
> 'and', change "...with the six" to a complete sentence.

The "values" correction is already present in the -34 draft.  I agree that not trying to include the list in a sentence structure would make it easier to read.

> period from the next bullet

OK

> 4.1.3. fix comma splicing in:  "This Header Parameter MUST be integrity
> protected, and therefore MUST occur only within the JWE Protected Header,
> when used."  For example, "When used, this Header Parameter MUST be
> integrity protected; therefore, it MUST occur only within the JWE Protected
> Header."

OK

> The following parameters have the same meaning, syntax, and processing rules
> as those defined in JWS, except that the certificate referenced by the thumbprint
> contains the public key to which the JWE was encrypted; this can be used to
> determine the private key needed to decrypt the JWE.
> 

I understand this suggestion but disagree because there's value to implementers and other readers to having each of the header parameters listed as a section header in the table of contents.  It makes it easy to see all of them in one place.  Combining them would lose this benefit.

				Thanks again,
				-- Mike

---

From: Barry Leiba <[email-masked]>
Date: Wed, 15 Oct 2014 08:54:31 -0400

> These link URLs are actually created by the IETF tools - not in the
> draft itself.  (You'll see "Html markup produced by rfcmarkup 1.109,
> available from https://tools.ietf.org/tools/rfcmarkup/" at the bottom
> of the drafts.)  I'm not sure who to file a bug on this with.

Ray is looking at the HTML generated by tools.ietf.org, which creates
the HTML by analyzing the text, not by looking at the markup.  When
the section name is separated from the reference, it can't figure it
out, and assumes that the section reference is to the current
document.  So, in JWE, for example, this:

   the initial contents of this registry are the values defined
   in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification.

...doesn't work, and makes "Section 4.1" link to Section 4.1 of the
current document, JWE, and then gives a link to the top of JWA at
"[JWA]".

You can make it work as desired by doing this:

OLD
   the initial contents of this registry are the values defined
   in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification.
NEW
   the initial contents of this registry are the values defined
   in the JSON Web Algorithms specification (JWA) [JWA], Section 4.1.
END

That will cause "[JWA], Section 4.1" to link as you'd expect.

(I also suggest that you don't need "(JWA) [JWA]" and can just use
"[JWA]" there, but perhaps that is an artifact of your markup tool.)

There are many places where this is an issue -- it's a tools issue,
not a document issue.  If you're willing to "fix" this in the
documents, please go through and try to find all the places where that
sentence structure is used.

Barry