Subject: [jose] JWS Comments

From: Nat Sakimura <[email-masked]>
Date: Fri, 15 Mar 2013 12:26:41 +0900

FYI, here is a set of comments that I provided on JWS to Mike couple
of days ago.
Just for the record so that you guys knows that Mike was not doing the
edits ad lib.

2. Terminology

-
JSON Web Signature (JWS)
----------------------------------------------
Currently, it states that JWS is:

      A data structure representing a digitally
      signed or MACed message.  The structure consists of three parts:
      the JWS Header, the JWS Payload, and the JWS Signature value.

It is false. It should be

      A data structure representing a digitally
      signed or MACed message.  The structure consists of three parts:
      the Encoded JWS Header, the Encoded  JWS Payload,
      and the Encoded JWS Signature value.

JWS Payload
---------------------
Change "The bytes to be secured" to "The byte array to be secured" OR
"The sequence of octets to be secured2.
"the bytes" does not seem to work very well here as it literally would
mean some number of integer.

Also, it is better not use "a.k.a." as it is not a defined acronym.
For an English native speaker, it would be fine, but for people with
English as second or third language, it may become a stumbling point.

Header Parameter Name
-----------------------------
We seem to be mixing the JSON terminology and something that is not.
For example, "The name of a member of the JWS Header" should be
"The string of a member of the JWS Header" in JSON terminology,
while 'member' is a JSON terminology. I agree that 'name' is much better
term than 'string', but we probably should define it if we use it.

4.1.1. "alg" Header Parameter
--------------------------------------
The second sentence is very long and hard to read. It probably is
better to be split.
It was kind of hard for me to parse, so non-native English speaker
probably would have a hard time reading it.

4.1.8 "cty" Header Parameter
--------------------------------------
It talks about 'JWT' case. It probably would be more illustrative if
we add other cases, such as JPEG as well.

5.1 - 5 Reduce repitition
--------------------------------------
Do we need to repeat the definition of JWS Secured Input here?
Just stating:

Compute the JWS Signature in the manner defined for teh paritcular
algorithm being used over the JWS Secured Input.

would seem sufficient.

5.1 - 5 replace 'JSON Header' with 'JWS Header'

The paragraph is using "JSON Header". Is it not "JWS Header"?

5.1 - 7
---------
Let us not conflate the creation of the JWS and compact serialization.
Step 7 should stop at the creation of JWS, and a new step 8 should
describe the compact serialization.

5.2 - 7
----------
I think we can delete what goes into parenthesis. We do not have to repeat.

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en