IETF logoJSON Crypto Specs Draft -02: JWS, JWE, JWK, JWA and JSON Web Token (JWT) Draft -10

New -02 versions of the JSON Object Signing and Encryption (JOSE) specifications are now available that incorporate working group decisions made since the previous versions, including decisions made at IETF 83 in Paris and in follow-up discussions on the JOSE 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

Also, Draft -10 of the JSON Web Token (JWT) specification has been published. It uses the -02 versions of the JOSE specifications and contains parallel editorial changes to those applied to the JOSE specs.

These specifications are available at:

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.

http://tools.ietf.org/html/draft-jones-json-web-token-10:

  • Clarified the relationship between typ header parameter values, typ claim values, and MIME types.
  • Clarified that JWTs with duplicate Header Parameter Names or Duplicate Claim names MUST be rejected.
  • Required implementation of AES-128-KW and AES-256-KW when the implementation provides encryption capabilities.
  • Registered “JWT” typ header parameter value.
  • 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 claim definition and header parameter its own section heading.

HTML formatted versions are available at: