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

[Antonio Sanso <[e-mail]>]

Thanks Nat,

so I assume [0] is out of date since nether RSA-PKCS1 and AES-* are not AEAD algorithms as long as I know.

Quoting:

"If an implementation provides encryption capabilities, of the JWE

   encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES-
   128-KW, AES-256-KW, AES-128-CBC, and AES-256-CBC MUST be implemented
   by conforming implementations.  It is RECOMMENDED that
   implementations also support ECDH-ES with 256 bit keys, AES-128-GCM,
   and AES-256-GCM.  Support for other algorithms and key sizes is
   OPTIONAL."

Regards

Antonio

[0] http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-06#section-8
On Dec 29, 2012, at 7:01 PM, Nat Sakimura wrote:



=nat via iPhone

Dec 29, 2012 19:35、Antonio Sanso <[e-mail]<mailto:[e-mail]>> のメッセージ:

Hi Nat,

apologies if this sounds trivial but I am trying to understand the JW* stuff and this mail thread is helping me to clarify some of my doubts.


On Dec 20, 2012, at 7:12 AM, Nat Sakimura wrote:

Thanks.

Just a few things:

1. Sign+Encrypt

kind of nitpicking here, but would not be better to invert those terms in order to sound Encrypt+Sign (as long as I know the order matters here and the only safe way is encrypt than  MAC).

No. You should use AEAD algorithms for the integrity protection.

Signing something that you cannot decrypt and verify is pretty meaningless  in the contractual settings.



Sign+Encrypt is useful when you want the signed JWT as a proof of consent to sign.
It can also exist after being decrypted.
If you just want integrity protection, use JWE.

For integrity should not be enough the signature so JWS?

All JWE algorithms are AEAD so JWS signing over JWE is redundant.


Thanks a lot and regards

Antonio


2. Alphabetization of the terminology

That's one way of organizing it.
Another way of organizing it is to lay them out in a semantic order,
where the preceding definition cannot use the terms defined later.
It is a good way to make sure the consistency, and I probably like this way better.

Of the definition themselves, I agree it still lacks bunch of terms that needs to be defined,
and needs tightening up.

Best,

Nat


On Thu, Dec 20, 2012 at 9:14 AM, Mike Jones <[e-mail]<mailto:[e-mail]>> wrote:

Thanks a bunch for the useful review, Jeff!  Responses are inline in green.



                                                                -- Mike



-----Original Message-----
From: [e-mail]<mailto:[e-mail]> [mailto:[e-mail]<mailto:[e-mail]>] On Behalf Of =JeffH
Sent: Tuesday, November 27, 2012 2:23 PM
To: IETF oauth WG
Subject: [OAUTH-WG] review: draft-ietf-oauth-json-web-token-05



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



OK, I’ll say that earlier and more 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"}



This is the JWT Header.  The base64url encoded version is the Encoded JWT Header.



      {"iss":"joe",

       "exp":1300819380,

       "http://example.com/is_root":true}



This is the JWT Claims Set.



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



The terms above are already defined in the spec.



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



I disagree with redefining the term “JWT” to not also include the signature.  The term “JWT” should continue to refer to the whole thing.



    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



I’ll note that when the JWT is encrypted, a base64url encoded representation of the JWT Claims Set is never used.  (The encrypted form of them is base64url encoded instead.)



    encoded-string form   The result of applying Base64url encoding to an

       input JSON text .



Sometimes he input to the base64url encoding is not JSON – for instance signature values or encrypted payloads.



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



Aah – I now see that this is the real misunderstanding.  The “string representing a JSON object” is not the base64url encoded form – it’s the string representation that’s parseable into a JSON object.  For instance, it could be a string such as {“alg”:”RS256”} – not the base64url encoded version of that string.  The reason for the syntactic construction “string representing a JSON object” is that its string representation is distinct from the abstract JSON object itself.  If I insert whitespace after the colon in the string {“alg”:”RS256”} it would parse to an equivalent JSON object but it would be a different string representation.  It’s the string representation that is actually operated on by the JWT/JWS/JWE operations.



I’ll try to make this clearer in the spec.



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.



I’ll see if I can figure out how to do this without introducing ambiguity.



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.



Can you suggest some language you’d like to see added about this?



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.



OK



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.



All true.  However once you add an issuer and a principal, then you’re back to the JWT being statements made by an entity about a subject.  Again, if there is language you believe should be added in that regard, please let me know.  (BTW, one such usage profile is in http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer-03.  Another is in http://openid.net/specs/openid-connect-messages-1_0.html#id_token.)



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!



No, it’s in a top-down descriptive order.  Is there a requirement in IETF specs that the terminology be alphabetized?



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



I’ll add a definition for “claim”.  “token” should actually probably become “security token”, with a definition of the term.



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?



It’s always the string representation of the serialized parts.



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



No, per my earlier comments



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



Good catch



   "parts" in JWT definition is unclear

     are "parts" json objects or arrays unto themselves ?



The parts are all base64url encoded values.  I’ll review this terminology usage to see if it can be clarified.



   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.



I’ll review



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



I’ll look into moving the definition in this direction.  What you’re missing in the above, though, is the distinction between the string representing the JSON object and the abstract JSON object.  We want the former.



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



I’ll look into moving the definitions in this direction.



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



I think you mean “encrypted and integrity protected” rather than “encrypted and signed”, right?



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



No, actually JWE just provides an integrity check – not a signature.  If you want a signature, you need to use JWS.  They can (and often are) used in a nested fashion.



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



Yes.  Although this is missing the fact that nested signing/encryption may be employed.



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



OK



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



Fair enough.  I’ll try to generalize the language.



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



True



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.



Yes, although using a collision resistant namespace effectively makes them public, as we’re using the term



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?



Private in that they are created in the context of a private arrangement.  I’ll try to clarify this point.  Facebook could define how they’re going to use the “id” claim very publicly, and yet it would still be a private claim if not registered with IANA.



>

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



Actually, it’s to avoid canonicalization.  I’ll reread the spec to see if we’ve stated that clearly or not.



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.



We tried to cover this in the end of section 7, starting with the sentence “Processing a JWT inevitably requires comparing known strings to values in the token”, which says how these comparisons must be performed.  I agree that this should become its own subsection.  I don’t understand your remark about constituent components.  Can you clarify?



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



Good



>

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



How about “Remove any JSON escaping from the input JSON string and 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.



Fair enough



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



That was the approach that Sean had suggested.  If there other things you think we should specifically add, however, please let me know.



above needs editorial polish -- there aren't any  "significant concerns"

actually listed here.



True enough



---

end





_______________________________________________

OAuth mailing list

[e-mail]<mailto:[e-mail]>

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

_______________________________________________
OAuth mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/oauth




--
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en
_______________________________________________
OAuth mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/oauth