Subject: [OAUTH-WG] WGLC on JSON Web Token (JWT)

From: Hannes Tschofenig <[email-masked]>
Date: Wed, 07 Aug 2013 11:19:55 +0200

Hi all,

this is a working group last call for the JSON Web Token (JWT).

Here is the document:
http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-11

Please send you comments to the OAuth mailing list by August 21, 2013.

Ciao
Hannes & Derek

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 9 Aug 2013 00:54:56 +1000

Comments on draft-ietf-oauth-json-web-token-11:

1. Should JWT really go to WGLC before the JOSE docs that it depends on so heavily (JWS/JWE/...)? Even if the "bytes-on-the-wire" are fairly stable, JWT repeats a lot of text from JWS/JWE some of which is likely to change. Finishing WGLC now and queuing the doc to be auto-published when JWS/JWE are published would be bad (unless the duplicate text is removed).

2. The JWT doc would be so much more readable if it could refer to a "JOSE message", "JOSE header", and "JOSE compact serialization"; instead of having to explicitly talk about JWS and JWE every time even when talking about aspects common to both. It would also avoid introducing "JWT Header", "Encoded JWT Header", "Nested JWT", "Plaintext JWT" etc as though these are new items, when in fact they are just additional names for JOSE items. For instance, "JWT Header" is effectively shorthand for "JWS or JWE header" but it is presented as a JWT-specific thing.

3. The doc should not repeat definitions from JWS and JWE. For instance, the whole first paragraph of section 5 "JWT Header" (JSON object; describes crypto ops; unique names; reject duplicates or use last) is an almost identical copy of paragraphs from JWS and JWE. The duplication (often triplication) adds confusion (eg what is the difference between a JWT Header and JWS Header?) and gets subtly out of sync (eg "cty" either "declares structural information about the JWT" or "declares the type of the secured/encrypted content (the payload/Plaintext) in an application-specific manner"). 
Other examples of unnecessarily duplicated text include: section 7 steps 3 & 4 (creating) and steps 1-8 (validating); section 7.1 text about comparing "alg" values; parts of the last 2 paragraphs of section 3 "JWT overview"; 1st and 3rd paragraphs of section 5.2 "cty"; 1st, 2nd, and 4th sentence of section 5.1 "typ".

4. Hardly anyone pronounces JWT as "jot" -- it is usually spelt out -- so drop the sentence in the abstract suggesting the "jot" pronunciation.

5. Collision Resistant Namespace (section 2 "Terminology") mentions domain names, OIDs, and UUIDs as examples, but fails to mention URIs, which is a likely choice. Domain names will start colliding with "reserved" names soon with all the new top-level domains. Should UUIDs use a "urn:uuid:" prefix, or "uuid:", or no prefix? Should UUIDs only use lower-case hex digits (otherwise duplicate UUIDs will look like distinct JSON names)? Should an OID be "2.5.4.3" or "oid:2.5.4.3" or "URN:OID:2.5.4.3" or "commonName" or "cn"? Collision resistant namespaces lose collision-resistance when you combine namespaces as is done here.

Could the reserved/public/private mess be simplified by saying (at the end of section 4 "JWT Claims"):

  A claim name can be any string. Using URIs as claim names is one
  way to ensure claim names are unambiguous. Claim names that are
  not URIs SHOULD be registered in the IANA Claims registry [section 9.1]

Then drop the last paragraph of section 4 "JWT claims" that starts "there are three classes of JT Claim Names"; drop section 4.2 "Public claim names"; drop section 4.3 "Private claim names"; drop the "collision resistant namespace" term.

6. The docs says including a "typ" field is OPTIONAL. Even when present "typ" can have any value since the two suggestions in the doc ("JWT" or "urn:ietf:params:oauth:token-type:jwt") are only RECOMMENDED. Given this, there doesn't seem to be anything a JWT recipient can usefully do with "typ". If it tries to use "typ" it will just be incompatible with compliant JWT senders that either omit "typ" or use another value. It would be better to drop section 5.1 "Type Header Parameter" entirely -- leaving any "typ" value definitions to profiles that actually define processing for such values.

7. The doc redefines the "cty" header parameter, which is already defined in JWS and JWE (slightly differently in all 3 cases - argh). JWT uses "cty" to indicate nested JOSE messages, which should be a JOSE feature as it is not specific to JWT (hence "cty":"jwt" is a poor choice).

8. [Editorial] "JWA signing algorithm" and "JWA encryption algorithms" are the wrong phrases. These are JWS signing algs and JWE encryption algs that happen to be specified in JWA.

9. Including a short description for each claim name in the registry would be useful. Just a 3-letter abbreviation is not helpful enough. Eg add a Claim description field:
  Claim name: "nbf"
  Claim description: not before
  Change controller: IETF
  Specification document: section 4.1.5. of [[ this doc ]]

--
James Manger

> ----------
> Sent: Wednesday, 7 August 2013 7:20 PM
> Subject: [OAUTH-WG] WGLC on JSON Web Token (JWT)
> 
> Hi all,
>

---

From: Mike Jones <[email-masked]>
Date: Wed, 21 Aug 2013 22:08:35 +0000

I believe that the technical content of this document is complete and stable and ready to move forward.

As a JOSE working group member and editor, I am aware of editorial changes being requested to be made to the JWS and JWE documents that could change some of the terminology used by JWT - in particular, the terms JWS Header, JWS Payload, JWE Header, and JWE Plaintext could change.  Other JOSE actions could also require changes to the JWT document to maintain editorial consistency.

I believe that we should continue the IETF process for this document, while recognizing that some local editorial changes may still be required.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Hannes Tschofenig
Sent: Wednesday, August 07, 2013 2:20 AM
To: [email-masked] WG
Subject: [OAUTH-WG] WGLC on JSON Web Token (JWT)

Hi all,

Here is the document:

Ciao
Hannes & Derek
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Prateek Mishra <[email-masked]>
Date: Wed, 21 Aug 2013 19:51:05 -0400

1) As a JWT is always an instance of JWE or JWS, I am not sure why there 
is a need for the the materials found in Section 5, para 1 (these are 
also found in the JWE and JWS draft specifications). It could simply be 
removed from the draft.

2) Why do we need both a "typ" claim and a "typ" header name? Need they 
have some relationship to each other?
Isn't this also covered by Section 5.3?

3)  The materials in Section 5.3 could be simplified further.

Why should the use of claims as header parameters be restricted to the 
case where the JWT=JWE; what about the encrypt then sign (symmetric) 
use-case? I see no issue in allowing this feature with a JWT of any type.

The last paragraph of Section 5.3 ("This specification reserves the iss 
(issuer), sub (subject),....") seems to be an instance of the
previous paragraph. If claims are allowed in the header, then iss 
(issuer), sub (subject) are trivially allowed, right? I couldn't find 
any additional information in this last paragraph.

Finally, do we need "SHOULD verify that their values are identical" - 
given that this matter is left upto applications, couldnt they choose to 
verify only a certain relationship between the corresponding values 
(e.g., header carries hash of value, JWT carries the (large) complete 
value)?  Can this be weakened to "SHOULD verify that their values have 
an appropriate (application-defined) relationship. In many instances, 
applications may want to ensure that they are identical".

4) Section 8 -

am I correct in reading this as: all conforming JWT implementations MUST 
implement JWS and MAY implement JWE?
At least thats what I understood from the last paragraph ("/if/ an 
implementation provides encryption capabilities...").

- prateek