[OAUTH-WG] review: draft-ietf-oauth-json-web-token-05

[=JeffH <[e-mail]>]

Hi, at ietf-85 atlanta I agreed to do a review of 
draft-ietf-oauth-json-web-token-05, and so I have some thoughts below. Also, +1 
to Hannes' comments.

Overall the spec seems to get its idea across, but is pretty rough. Part of this 
is due to the language being convoluted, plus some concepts are only tacitly 
described (with clues scattered throughout the spec), and thus it is difficult 
to understand without multiple passes of this spec as well as [JWE] and [JWS].

For example, a JWT appears to be simply either a JWS or a JWE containing a JWT 
Claims Set, but this is not stated until right before section 3.1 (and it isn't 
stated that clearly).

Immediately below are some overall comments, and then below that some detailed 
comments on various portions of the spec.  I'm not addressing everything I 
noticed due to time constraints (apologies).

HTH

=JeffH
------


JWT terminology:

Some issues seem to me to be caused by defining the JWT to be the base64url 
encoded JSON  object itself and not having terminology to clearly refer to its 
unencoded form.

For example, these two JSON objects together apparently comprise a (unencoded) JWT..

      {"typ":"JWT",
       "alg":"HS256"}

      {"iss":"joe",
       "exp":1300819380,
       "http://example.com/is_root":true}

..but there's no defined way to refer to them given the spec's terminlogy.

Consider terming the above a JWT and its encoded-string form an Encoded JWT, and 
define them separately. And then there'll be similar definitions for JWT Header 
and JWT Claims Set, e.g.,

    Encoded JWT   A JWT that has been encoded according to the
       process defined in Section X.

    Encoded JWT Header   The encoded-string form of a JWT Header

    Encoded JWT Claims Set   The encoded-string form of a JWT Claims Set

    encoded-string form   The result of applying Base64url encoding to an
       input JSON text .

    JSON Web Token (JWT)  A JWT comprises a JWT Header and a JWT Claims Set. ...

    JWT Header  A JSON object that is a component of a JWT. It denotes the
       cryptographic operations applied to the JWT.  ...

    JWT Claims Set  A JSON object containing a set of claims.  ...


This also gets rid of the use of the "A string representing a JSON object..." 
which I find confusing and potentially misleading (because it is actually "a 
Base64url encoding of a JSON object").



UTF-8:

UTF-8 is mentioned in lots of places. It could probably be stated once up near 
the beginning of the spec that all the JSON text is UTF-8 encoded, and all the 
JSON strings are UTF-8 encoded.



Semantics, profiles and relationship to SAML:

The spec does not define any overall JWT semantics (i.e., what any given JWT 
/means/). Semantics are only defined in context of each individual Reserved 
Claim Name.

Thus any application of JWTs will need to profile the JWT spec: specifying the 
claim set(s) contents, and the overall semantics of the resultant JWT(s).  This 
is not explicitly explained in the JWT spec.

In terms of SAML, Appendix B should refer to SAML assertions rather than saml 
tokens. Also, I'm not sure SAML assertions inherently have more expressivity 
than JWTs. They do have more pre-defined structure and semantics.

Syntactically, it seems one can encode pretty much anything in whatever amount 
in a JWT (one can do the same with SAML assertions), and thus theoretically JWTs 
could be used to accomplish the same things as SAML assertions.

Semantically, SAML assertions are explicitly statements made by a system entity 
about a subject. But by default, a JWT is empty, and has no semantics (this 
isn't stated explicitly). All semantics defined in the JWT spec are particular 
to individual reserved claims, but all reserved claims are optional. Thus an 
application of JWTs to use cases also apropos for SAML assertions will require 
arguably more profiling than that needed to apply SAML assertions.

The token size & complexity comparison seems nominally fine.



Some detailed-but-rough comments and musings on portions of the spec as I was 
reading through it...



 > 2. Terminology


terminology is not alphabetised!


"claim", "claims", "token" should be defined in terminology

suggestion:

      Claim:  an assertion of something as a fact. Here, claims are
         name and value pairs, consisting of a Claim Name and a
         Claim Value.


 >    JSON Web Token (JWT)

   is jwt always a "string" or is it string (only) when it's been serialized 
into one?

 >                    A string representing a set of claims as a JSON
 >       object that is digitally signed or MACed and/or encrypted.

   is it more that it's a set of claims encoded as a JSON object
   that is string-serialized?

   is it /not/ a JWT by definition if it is not ((signed or unmac'd) and/or 
encrypted) ?   No, because there are Plaintext JWTs, but they aren't in 
terminology (probably should be).

   "parts" in JWT definition is unclear
     are "parts" json objects or arrays unto themselves ?

   the definition assumes knowledge that's presented later. perhaps needs fwd
   reference(s), or perhaps better is to not present as much technical detail
   in the definitions.


 >    JWT Claims Set

   similar comments as to JSON Web Token (JWT)

   the definition says how it is encoded and encrypted, but not how claims are 
mapped into a JSON object


should probably be simply:

    JWT Claims Set: A set of claims expressed as a JSON object, where each
       claim is an object member (i.e., a name/value pair). A claim may have
       a JWT Claims Set as a value.


 >    Claim Name  The name of a member of the JSON object representing a
 >       JWT Claims Set.

should probably be simply:

    Claim Name  The name portion of a claim, expressed as a JSON object member
       name.


 >    Claim Value  The value of a member of the JSON object representing a
 >       JWT Claims Set.

should probably be simply:

    Claim Value  The value portion of a claim, expressed as a JSON object member
       value.



 > 3. JSON Web Token (JWT) Overview

 >    The bytes of the UTF-8 representation of the JWT Claims Set are
 >    digitally signed or MACed in the manner described in JSON Web
 >    Signature (JWS) [JWS] and/or encrypted in the manner described in
 >    JSON Web Encryption (JWE) [JWE].

s/ and/or encrypted / or encrypted and signed /


 >    The contents of the JWT Header describe the cryptographic operations
 >    applied to the JWT Claims Set. If the JWT Header is a JWS Header, the
 >    claims are digitally signed or MACed.  If the JWT Header is a JWE
 >    Header, the claims are encrypted.

What if a JWT is signed AND encrypted?  Hm, from my looking at JWS and JWE 
specs, it seems that in that case one uses JWE because that encompasses both 
encrypt & sign.



 >    A JWT is represented as a JWS or JWE.  The number of parts is
 >    dependent upon the representation of the resulting JWS or JWE.

Does the above mean to say..

    A JWT consists of a JWS or JWE object, which in turn conveys the JWT
    Claims Set. In the case of a JWS, the JWT Claims Set is the JWS
    Payload. In the case of a JWE, the JWT Claims Set is the input
    Plaintext.




 > 4. JWT Claims
 >
 >
 >    The JWT Claims Set represents a JSON object whose members are the
 >    claims conveyed by the JWT.  The Claim Names within this object MUST
 >    be unique; JWTs with duplicate Claim Names MUST be rejected.

does the above mean to say claim names must be unique amongst the set of claim 
names within any given JWT Claims Set ?  If so, that's only implied by the above 
but should be stated explicitly; as it is, the above is ambiguous.


 > 4.2. Public Claim Names
 >
 >
 >    Claim names can be defined at will by those using JWTs.  However, in

s/Claim names/Public claim names/

 >    order to prevent collisions, any new claim name SHOULD either be
 >    registered in the IANA JSON Web Token Claims registry Section 9.1 or
 >    be a URI that contains a Collision Resistant Namespace.


why should a claim name be a URI if I wish to make use of Collision Resistant 
Namespaces?  For example, if I simply use say UUIDs as claim names..

      {"iss":"joe",
       "3005fa05-e76c-4994-bbc9-65b2ace2305c":"foo"}

..it will be universally unique provided I minted it appropriately (no URI 
syntax is needed).



 > 4.3. Private Claim Names
 >
 >
 >    A producer and consumer of a JWT may agree to any claim name that is
 >    not a Reserved Name Section 4.1 or a Public Name Section 4.2.  Unlike
 >    Public Names, these private names are subject to collision and should
 >    be used with caution.

it seems private claim names are only subject to collision if the implementers 
don't make appropriate use of Collision Resistant Namespaces, i.e. they "can be" 
subject to collision.


the above two sections use "public" and "private" as distinguishing factors, but 
it seems to me the distinguishing factor (given how the above is written) is 
more whether Collision Resistant Namespaces are employed or not.

An implied aspect of public claim names seems to be that it is assumed that they 
are publicly listed/documented/leaked, thus the "public" moniker, and hence 
ought to be universally unique as a matter of course.

and "private" ones seem to be assumed to be obfuscated to all but the agreeing 
parties?  Or they are "private" in only the sense that they are created in the 
context of a private arrangement?



 >
 > 7. Rules for Creating and Validating a JWT
 >
 >
 >    To create a JWT, one MUST perform these steps.  The order of the
 >    steps is not significant in cases where there are no dependencies
 >    between the inputs and outputs of the steps.
 >
 >    1.  Create a JWT Claims Set containing the desired claims.  Note that
 >        white space is explicitly allowed in the representation and no
 >        canonicalization is performed before encoding.


I presume the rationale for allowing white space is that JSON objects are 
unordered (and can contain arbitrary whitespace), thus simple buffer-to-buffer 
comparisons between serialized objects cannot be reliably performed.  If so this 
should be explicitly stated.

It seems that member/value-by-member/value comparisons must always be done, by 
parsing the JSON objects and extracting all members and values, this should be 
stated explicitly in the spec.

I found meager jwt comparison instructions at the very end of Section 7. it 
should probably be its own subsection. It should probably explicitly say that 
JWTs need to be parsed into their constituent components, and the latter must be 
individually examined/compared.


 >    Comparisons between JSON strings and other Unicode strings MUST be
 >    performed as specified below:

this comparison algorithm seems to be attempting to allow for comparison of 
UTF-8 encoded JSON strings with other unicode strings in any of the unicode 
encoding formats, but only implies that; it should be stated.

 >
 >    1.  Remove any JSON applied escaping to produce an array of Unicode
 >        code points.

I don't think (1) is correct.  A JSON string is by default encoded in UTF-8. A 
UTF-8 encoded string is not "an array of Unicode code points" (its a sequence of 
code units, which must be decoded into code points), i think a step is missing 
here..

    1.  Remove any JSON escaping from the input JSON string.

    1.a  convert the string into a sequence of unicode code points.

..and then compare code point-by-code point. This overall algorithm /seems/ ok, 
but I'm not sure, it seems there's rationale that's not expressed, eg for 
excluding use of Unicode Normalization [USA15]. Also the alg is incomplete in 
that it doesn't stipulate converting the "other unicode string" into a sequence 
of code points.




 > 10. Security Considerations
 >
 >
 >    All of the security issues faced by any cryptographic application
 >    must be faced by a JWT/JWS/JWE/JWK agent.  Among these issues are
 >    protecting the user's private key, preventing various attacks, and
 >    helping the user avoid mistakes such as inadvertently encrypting a
 >    message for the wrong recipient.  The entire list of security
 >    considerations is beyond the scope of this document, but some
 >    significant concerns are listed here.
 >
 >    All the security considerations in the JWS specification also apply
 >    to JWT, as do the JWE security considerations when encryption is
 >    employed.  In particular, the JWS JSON Security Considerations and
 >    Unicode Comparison Security Considerations apply equally to the JWT
 >    Claims Set in the same manner that they do to the JWS Header.
 >

dunno if you can get away with sec cons wholly in other docs, and I'm not sure 
it's appropriate given that JWTs are a profile of JWE or JWS.

above needs editorial polish -- there aren't any  "significant concerns" 
actually listed here.


---
end