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

From: Mike Jones <[email-masked]>
Date: Tue, 11 Dec 2012 02:23:55 +0000

Thanks for the review comments, Hannes.  Replies are inline in green...

                                                                -- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Hannes Tschofenig
Sent: Sunday, November 25, 2012 11:49 AM
To: [email-masked] WG
Subject: [OAUTH-WG] Review of draft-ietf-oauth-json-web-token-05

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.

Agreed

- 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?

I agree that in some contexts, including a Key ID would be important.  That being said, in other contexts, including some OAuth contexts, the key is implicitly known from context.  For instance, a shared symmetric key may be assigned to be used for an OAuth client at client registration time.  In that case, both the client and the server already know what key to use without needing a Key ID.  The same may true when using public key cryptography with an issuer that publishes a public key and a relying party that also publishes a public key.  Here again, the correct keys to be used can be determined via means external to the token itself.

- 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.

If people are following the spec and using (IANA) reserved claim names, or public claim names (those containing a collision-resistant namespace), then the same names will always have the same semantics.  IANA is used for reserved claim names, where conflicts would otherwise be likely.  IANA is unnecessary for public claim names, because the collision-resistant namespace in the claim name prevents duplication.

Do we really need to support claims where uniqueness cannot be guaranteed?

Private claim names are there because in some contexts, the communication is between a fixed or constrained set of parties between whom private agreements are a perfectly acceptable namespace allocation solution.  Indeed, it wouldn't make much sense to register the meanings of claims with IANA that will only be used in a closed environment.

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?

The same namespace allocation strategy is being used by JOSE.

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

Yes

* "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.

(See my reply to Prateek Mishra on the same topic.)

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.

Mandatory to use.  I'll plan to clarify this in the next draft.

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.

The intended meaning is "Use of this claim is OPTIONAL."  I'll clarify this in the next draft.

* 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.

This would make for a pretty short section.  I realize that RFC 2119 language shouldn't be used in the abstract or introduction, but the RFC 2119 requirements are legitimate constraints on the definitions of these terms.

* 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.

Having a small set of MTI algorithms is part of what makes the spec simple and promotes real interoperability.  That being said, per Sean Turner's suggestion, the Required/Recommended/Optional/Deprecated status of algorithms can change over time in the IANA algorithms registry, as the changing crypto landscape may require.

* 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.

Sure - that would be good.

* 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.

It's an editorial judgment call.  The example is there so people reading the JWT spec first will get the (correct) sense that "this is pretty simple".  If they have to immediately go to another spec just to see an example, my sense is that they'll likely think "this is already getting complicated!".

* References

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

I'll plan to address this in the next draft.

[USA15] is not a normative reference, IMHO.

I think it's probably normative because it occurs in the context of RFC 2119 language: "Unicode Normalization [USA15] MUST NOT be applied...".

Ciao

Hannes

_______________________________________________

OAuth mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Sat, 29 Dec 2012 01:10:51 +0000

Thanks for your review, Hannes.  Updates resulting from these comments are included in the latest drafts.

                                                            Thanks again,
                                                            -- Mike

From: Mike Jones
Sent: Monday, December 10, 2012 6:24 PM
To: 'Hannes Tschofenig'; [email-masked]<mailto:[email-masked]> WG
Subject: RE: [OAUTH-WG] Review of draft-ietf-oauth-json-web-token-05

                                                                -- Mike

-----Original Message-----
From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]] On Behalf Of Hannes Tschofenig
Sent: Sunday, November 25, 2012 11:49 AM
To: [email-masked]<mailto:[email-masked]> WG
Subject: [OAUTH-WG] Review of draft-ietf-oauth-json-web-token-05

Hi all,

Agreed

- Header

- Namespace

Yes

Section 4 you write:

"

"

"

   Note

   this specification.

"

"

"

* Data Types

* MTI Algorithms

* Examples

* References

Ciao

Hannes

OAuth mailing list