Subject: [jose] Draft -02 of JSON Crypto Specs: JWS, JWE, JWK, JWA

From: Mike Jones <[email-masked]>
Date: Sun, 13 May 2012 00:08:59 +0000

New -02 versions of the JSON Object Signing and Encryption (JOSE)<http://datatracker.ietf.org/wg/jose/> specifications are now available that incorporate working decisions made since the previous versions, including decisions made at IETF 83 in Paris and in follow-up discussions on the working group list.  The drafts contain numerous clarifications, refinements, and editorial improvements.  They are:

*        JSON Web Signature (JWS) - Digital signature/HMAC specification

*        JSON Web Encryption (JWE) - Encryption specification

*        JSON Web Key (JWK) - Public key specification

*        JSON Web Algorithms (JWA) - Algorithms and identifiers specification

These specifications are available at:

*        http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-02

*        http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-02

*        http://tools.ietf.org/html/draft-ietf-jose-json-web-key-02

*        http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-02

The document history entries (also in the specifications) are as follows:

http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-02:

  *   Clarified that it is an error when a kid value is included and no matching key is found.
  *   Removed assumption that kid (key ID) can only refer to an asymmetric key.
  *   Clarified that JWSs with duplicate Header Parameter Names MUST be rejected.
  *   Clarified the relationship between typ header parameter values and MIME types.
  *   Registered application/jws MIME type and "JWS" typ header parameter value.
  *   Simplified JWK terminology to get replace the "JWK Key Object" and "JWK Container Object" terms with simply "JSON Web Key (JWK)" and "JSON Web Key Set (JWK Set)" and to eliminate potential confusion between single keys and sets of keys. As part of this change, the header parameter name for a public key value was changed from jpk (JSON Public Key) to jwk (JSON Web Key).
  *   Added suggestion on defining additional header parameters such as x5t#S256 in the future for certificate thumbprints using hash algorithms other than SHA-1.
  *   Specify RFC 2818 server identity validation, rather than RFC 6125 (paralleling the same decision in the OAuth specs).
  *   Generalized language to refer to Message Authentication Codes (MACs) rather than Hash-based Message Authentication Codes (HMACs) unless in a context specific to HMAC algorithms.
  *   Reformatted to give each header parameter its own section heading.

http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-02:

  *   When using AEAD algorithms (such as AES GCM), use the "additional authenticated data" parameter to provide integrity for the header, encrypted key, and ciphertext and use the resulting "authentication tag" value as the JWE Integrity Value.
  *   Defined KDF output key sizes.
  *   Generalized text to allow key agreement to be employed as an alternative to key wrapping or key encryption.
  *   Changed compression algorithm from gzip to DEFLATE.
  *   Clarified that it is an error when a kid value is included and no matching key is found.
  *   Clarified that JWEs with duplicate Header Parameter Names MUST be rejected.
  *   Clarified the relationship between typ header parameter values and MIME types.
  *   Registered application/jwe MIME type and "JWE" typ header parameter value.
  *   Simplified JWK terminology to get replace the "JWK Key Object" and "JWK Container Object" terms with simply "JSON Web Key (JWK)" and "JSON Web Key Set (JWK Set)" and to eliminate potential confusion between single keys and sets of keys. As part of this change, the header parameter name for a public key value was changed from jpk (JSON Public Key) to jwk (JSON Web Key).
  *   Added suggestion on defining additional header parameters such as x5t#S256 in the future for certificate thumbprints using hash algorithms other than SHA-1.
  *   Specify RFC 2818 server identity validation, rather than RFC 6125 (paralleling the same decision in the OAuth specs).
  *   Generalized language to refer to Message Authentication Codes (MACs) rather than Hash-based Message Authentication Codes (HMACs) unless in a context specific to HMAC algorithms.
  *   Reformatted to give each header parameter its own section heading.

http://tools.ietf.org/html/draft-ietf-jose-json-web-key-02:

  *   Simplified JWK terminology to get replace the "JWK Key Object" and "JWK Container Object" terms with simply "JSON Web Key (JWK)" and "JSON Web Key Set (JWK Set)" and to eliminate potential confusion between single keys and sets of keys. As part of this change, the top-level member name for a set of keys was changed from jwk to keys.
  *   Clarified that values with duplicate member names MUST be rejected.
  *   Established JSON Web Key Set Parameters registry.
  *   Explicitly listed non-goals in the introduction.
  *   Moved algorithm-specific definitions from JWK to JWA.
  *   Reformatted to give each member definition its own section heading.

http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-02:

  *   For AES GCM, use the "additional authenticated data" parameter to provide integrity for the header, encrypted key, and ciphertext and use the resulting "authentication tag" value as the JWE Integrity Value.
  *   Defined minimum required key sizes for algorithms without specified key sizes.
  *   Defined KDF output key sizes.
  *   Specified the use of PKCS #5 padding with AES-CBC.
  *   Generalized text to allow key agreement to be employed as an alternative to key wrapping or key encryption.
  *   Clarified that ECDH-ES is a key agreement algorithm.
  *   Required implementation of AES-128-KW and AES-256-KW.
  *   Removed the use of A128GCM and A256GCM for key wrapping.
  *   Removed A512KW since it turns out that it's not a standard algorithm.
  *   Clarified the relationship between typ header parameter values and MIME types.
  *   Generalized language to refer to Message Authentication Codes (MACs) rather than Hash-based Message Authentication Codes (HMACs) unless in a context specific to HMAC algorithms.
  *   Established registries: JSON Web Signature and Encryption Header Parameters, JSON Web Signature and Encryption Algorithms, JSON Web Signature and Encryption "typ" Values, JSON Web Key Parameters, and JSON Web Key Algorithm Families.
  *   Moved algorithm-specific definitions from JWK to JWA.
  *   Reformatted to give each member definition its own section heading.

                                                            -- Mike

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 16 May 2012 00:22:02 +1000

draft-ietf-jose-json-web-signature-02 §7.2 registers the "JWS" type value (for the "typ" header field). Presumably this value indicates that the data to be signed is itself a JSON Web Signature (JWS). That is, it is used when you want multiple signatures, one wrapping another. This sounds like quite an unusual corner case. Yet, the 2nd sentence of the definition of the "typ" header parameter [§4.1.8] explicitly mentions this "JWS" type value - almost implying it is the usual value for this parameter.

Perhaps "typ":"JWS" is more useful in a JWE header when encrypting signed content (sign-then-encrypt). If this is the intention, then mentioning the "JWS" type value when defining the "typ" header for a JWS is misleading. It would be better to mention it where the JWE spec defines "typ".

The definition of the "JWS" type value [§7.2] doesn't actually say what the syntax is. It needs to explicitly say that when "typ" is "JWS" the content bytes are a JWS Compact Serialization.

This is not a great syntax when there are multiple wrapped signature, nor when encrypting a signature. It causes nested layers of base64url encodings. For instance, if 3 signatures sign some message the result includes base64(base64(base64(message). Similarly, encrypting signed content results in base64(base64(message)). This hardly matches the opening sentence of the spec that talks about a "compact format" for "space constrained environments".

It is great to have a base64url-based format for when a small amount of secured data is passed around, but it doesn't need to cause bloat for nested operations or securing larger amounts of data.

--
James Manger

---

From: Mike Jones <[email-masked]>
Date: Tue, 15 May 2012 15:07:10 +0000

Your second paragraph correctly describes the intended usage.  For instance, see http://tools.ietf.org/html/draft-jones-json-web-token-10#section-5.1 for this usage in action.  The value is registered per the working group decision relating "typ" values to MIME types.

                                                            -- Mike

From: Manger, James H [mailto:[email-masked]]
Sent: Tuesday, May 15, 2012 7:22 AM
To: Mike Jones; [email-masked]
Subject: "typ":"JWS"

--
James Manger

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 16 May 2012 10:40:20 +1000

>> draft-ietf-jose-json-web-signature-02 §7.2 registers the "JWS" type value (for the "typ" header field)
>> ...
>> ...

> Your second paragraph correctly describes the intended usage.  For instance, see http://tools.ietf.org/html/draft-jones-json-web-token-10#section-5.1 for this usage in action.  The value is registe…

Good. So let's say that. Suggested text changes:

* draft-ietf-jose-json-web-signature-02, section 4.1.8 "typ" (Type) Header Parameter: delete the 2nd sentence because signing a signature is not what we are talking about (and JWS-JS recommends a different approach for multiple signatures anyway).

* section 7.1 Registration of application/jws MIME Media Type: add a phrase explicitly stating the syntax (since the spec mentions two: compact, and JWS JS) so the section says:
  This specification registers the "application/jws" MIME Media Type [RFC 2045]
  to identify content that uses the JWS compact serialization.

* section 7.2 Registration of "JWS" Type Value: mention the intended use of encrypting signed content by adding this sentence.
  The "typ" parameter can be set to "JWS" in a JSON Web Encryption [JWE] header when encrypting signed content.

* draft-ietf-jose-json-web-encryption-02, section 4.1.13 "typ" (Type) Header Parameter, section 11.1 Registration of application/jwe MIME Media Type, section 11.2 Registration of "JWE" type Value: make equivalent changes.

--
James Manger

---

From: "Manger, James H" <[email-masked]>
Date: Thu, 17 May 2012 12:23:25 +1000

The term "JWT" is used both for:
1. A JSON object listing claims, eg {"iss":"joe","exp":1300819380}; and
2. A string of base64-and-dots, eg eyJhbGciOiJub25lIn0.eyJ...lfQ.

I assume "typ":"JWT" in a JWS or JWE header means the payload or plaintext is #1.

If I received content with the application/jwt media type, however, I would probably expect #2 as this is the form that is more often passed around in protocols. But this expectation must be wrong.

These seems inconsistent.
"typ":"JWT" is also not consistent with "typ":"JWS" and "typ":"JWE".

Could we add a sentence to "Registration of application/jwt media type" [draft-jones-json-web-token-10#section-9.3] explicitly stating the syntax being identified is a JWT Claim Set.
I would also add a note:
  Note: The syntax associated with "typ":"JWT" is a JSON object,
        in contrast to the syntax associated with "typ":"JWS" and
       "typ":"JWE" that is a string of dot-separated base64url segments.
  
Alternatively use "typ":"CLM" (for claims) instead of "typ":"JWT".

--
James Manger

---

From: Mike Jones <[email-masked]>
Date: Thu, 17 May 2012 02:57:16 +0000

If JWT is ever used to refer to the bare claim set, rather than the complete object, that's a spec bug.  If you've found any such references, can you point me to them so I can correct them?

				Thanks,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Manger, James H
Sent: Wednesday, May 16, 2012 7:23 PM
To: [email-masked]
Subject: [jose] "typ":"JWT"

The term "JWT" is used both for:
1. A JSON object listing claims, eg {"iss":"joe","exp":1300819380}; and 2. A string of base64-and-dots, eg eyJhbGciOiJub25lIn0.eyJ...lfQ.

  

--
James Manger
_______________________________________________
jose mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/jose

---

From: "Manger, James H" <[email-masked]>
Date: Thu, 17 May 2012 13:06:41 +1000

The "typ" value tells you the syntax of the payload.
"typ":"JWT" means the payload is a bare claim set doesn't it? That is what §3.1 "Example JWT" has.
This looks like "JWT" referring to a bare claim set to me.

--
James Manger

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Thursday, 17 May 2012 12:57 PM
To: Manger, James H; [email-masked]
Subject: Re: [jose] "typ":"JWT"

				Thanks,
				-- Mike

---

From: Mike Jones <[email-masked]>
Date: Thu, 17 May 2012 03:13:08 +0000

Fair enough.  Let me think about this one...

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Manger, James H
Sent: Wednesday, May 16, 2012 8:07 PM
To: Mike Jones; [email-masked]
Subject: Re: [jose] "typ":"JWT"

--
James Manger

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Thursday, 17 May 2012 12:57 PM
To: Manger, James H; [email-masked]
Subject: Re: [jose] "typ":"JWT"

				Thanks,
				-- Mike