Subject: [OAUTH-WG] Review of draft-ietf-oauth-json-web-token-05

From: Hannes Tschofenig <[email-masked]>
Date: Sun, 25 Nov 2012 21:48:56 +0200

Hi all, 

I reviewed the document and I have a few questions (see below). I also think that this document has to wait for the JOSE documents to complete WGLC before it can be moved forward. It will have to wait anyway in the queue because of the normative dependency. 
 
- Header

In Section 3.1 you have an example of a JWT with an HMAC SHA-256 keyed message digest. 
I would have assumed that the header contains the key id so that the receipient can actually decode it. I am sure you assume it implicitly determines it (somehow) but wouldn't it be better practice to additionally include the kid field to make it less ambigious? 

- Namespace

The document defines a couple of claims. Quite naturally one wants to provide extension points since others will quite likely come up with new claims in the near future. The obvious approach would be to use an IANA registry to maintain uniqueness of the labels but without using a namespace declaration concept like XML does. 
 
For some reason that does not seem to be enough to use IANA alone: the document introduces three types of claims, namely Reserved Claim Names, Public Claim Names, and Private Claim Names

No mechanism is stated how these claims can be differentiated but essentially everything is allowed. Section 2 ("Terminology") says that the claims that are not registered through IANA may be Domain Names, Object Identifiers (OIDs), UUIDs, etc. 

Later in Section 4.2 it is said that public claims could be a URI, which is again different to what is said in Section 2. 

Furthermore, Private Claims (as defined in Section 4.3) do not seem to have the requirement for uniqueness anymore even though Section 4 says that claim names in a JWT have to be unique. 

The danger is obviously that two parties define claim names that have different semantic. This will lead to confusion. When claims with the same names are added to a JWT then, per specification, the receiver will have to fail. 

Do we really need to support claims where uniqueness cannot be guaranteed?
Can we decide on a few namespace concepts rather than leaving the list open-ended? What are the JOSE guys going to do about this issue?

Btw, is it allowed to use JavaScript reserved keywords as claim names?

* "Mandatory to Implement"/"Mandatory to Understand"

Section 4 you write:

"
When used in a security-related context,
   implementations MUST understand and support all of the claims
   present; otherwise, the JWT MUST be rejected for processing.
"

In the same paragraph you write: 

"
   Note
   however, that the set of claims that a JWT must contain to be
   considered valid is context-dependent and is outside the scope of
   this specification.
"

Wouldn't it also be application context dependent to decide how unknown claims are dealt with.
I fear that the above statement would lead to the problem that no extensions are possible anymore since you cannot be sure that the recipient understands all the extensions. 

Then, in Section 4.1 you write:

"
The following claim names are reserved.  None of the claims defined
   below are intended to be mandatory, but rather, provide a starting
   point for a set of useful, interoperable claims.
"

What does mandatory mean here? Given the statement you made above all claims must be understood anyway. 

Almost every claim description contains the following statement: "This claim is OPTIONAL."
What does this mean? Here are a few choices of what it could mean: 

 * A library does not need to implement it. 
 * When an entity receives a JWT with an optional claim it can safely ignore it. 
 * When constructing a JWT payload this claim is optional to include. 
  
* Data Types

I would suggest to move the two data types (IntDate & StringOrURI) into a separate Section instead of leaving them in the terminology since you are using RFC 2119 language there. 

* MTI Algorithms

You list a number of algorithms that must be implemented, namely "RSA-PKCS1-1.5 with 2048 bit keys, AES-128-KW, AES-256-KW, AES-128-CBC, and AES-256-CBC". While this may be a good choice for a Web environment I doubt it is useful for other, more constrained use cases. 

There are a few ways to deal with this, such as: 

 -  Avoid a MTI list and use RECOMMENDED language.  
 -  State the usage environment and thereby provide an escape clause for other use cases. 
 -  Outsource these algorithsm into a separate document that can be updated independently. 

* Security Consideration Section

I think the text could be improved. I was hoping to see some text about the plaintext JWS. 

I will try to make a suggestion in the next few days.  

* Examples

To me it seems that Appendix A & Appendix B are a copy-and-paste of the text in http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-07. 

Maybe it would be better to replace the text with a reference to draft-ietf-jose-json-web-signature-07. No need to artificially increase the size of the document. 

* References 

The references to [JWA], [JWK], and [JWS] are incomplete. [JWS] and [JWK] has to be, IMHO, a normative reference. 

[USA15] is not a normative reference, IMHO. 

Ciao
Hannes