Subject: [jose] Issue #121 - Section 7.2 JWS JSON Serialization

From: "Jim Schaad" <[email-masked]>
Date: Fri, 7 Feb 2014 10:30:15 -0800

This is an improvement over the previous version, however there are a number
of changes that can be done to make things better.

1.        Move the  requirement language into the list.  Thus "This member
MUST be present." Should be part of the payload and signatures and signature
list items and the separate paragraph can be removed

2.       Suggested text for signatures element: 

<t hangText="signatures"/>The type of this element is an array of objects.
Each object represents a separate signature or MAC computation over the
payload.  This element MUST be present.
<vspace line="1"/>
The following members are defined for the JSON object for each signature:
<list style="hanging"/>

<t hangText="protected">contains the value BAES64URL(UTF8(JWS Protected
Header)).  The value MUST be absent if there is no protected header.</t>

<t hangText="header">contains a JSON object.  The member of the object
consist of the unprotected header name/value pairs.  This value MUST be
absent if there are no unprotected header members.</t>

<t hangText="signature">contains the value BASE64URL(JWS Signature).  This
value MUST be present.

</list>

</t>

3.       A note that one of protected and header will be present because the
alg header parameter is required could be added, but I don't know that it is
really necessary.

4.  If the paragraph starting with "The contents of the JWS Payload and JWS
Signature values are" is required here, then it should also be in section
7.1
5.  I don't understand what the paragraph starting with "Each JWS Signature
value is computed on the JWS Signing Input" is trying to say.  I think it
could probably be said in a clearer and terser manner however.

---

From: Mike Jones <[email-masked]>
Date: Sat, 15 Feb 2014 01:46:05 +0000

Thanks for these useful comments, Jim.  They helped make the section much more readable.  Please review the revised language in the -21 draft.

                                                                -- Mike

From: Jim Schaad [mailto:[email-masked]]
Sent: Friday, February 07, 2014 10:30 AM
To: [email-masked]
Cc: [email-masked]
Subject: Issue #121 - Section 7.2 JWS JSON Serialization

This is an improvement over the previous version, however there are a number of changes that can be done to make things better.

1.        Move the  requirement language into the list.  Thus "This member MUST be present." Should be part of the payload and signatures and signature list items and the separate paragraph can be removed

<t hangText="signatures"/>The type of this element is an array of objects.  Each object represents a separate signature or MAC computation over the payload.  This element MUST be present.
<vspace line="1"/>
The following members are defined for the JSON object for each signature:
<list style="hanging"/>

<t hangText="protected">contains the value BAES64URL(UTF8(JWS Protected Header)).  The value MUST be absent if there is no protected header.</t>

<t hangText="header">contains a JSON object.  The member of the object consist of the unprotected header name/value pairs.  This value MUST be absent if there are no unprotected header members.</t>

<t hangText="signature">contains the value BASE64URL(JWS Signature).  This value MUST be present.

</list>

</t>

3.       A note that one of protected and header will be present because the alg header parameter is required could be added, but I don't know that it is really necessary.

4.  If the paragraph starting with "The contents of the JWS Payload and JWS Signature values are" is required here, then it should also be in section 7.1

5.  I don't understand what the paragraph starting with "Each JWS Signature value is computed on the JWS Signing Input" is trying to say.  I think it could probably be said in a clearer and terser manner however.