IETF logoNew versions of the JSON WEB {Signature,Encryption,Key,Algorithms,Token} (JWS, JWE, JWK, JWA, JWT) specifications have been released. These versions incorporate numerous suggestions from working group members and developers that clarify the intent of the specifications and make them easier to read and implement. In particular, the JWE spec now includes encryption and key derivation examples for a number of algorithms that have been verified in multiple independent implementations.

I’ve worked to close out all the former “TBD” items in the specs, bringing them up to an editorially complete state, in preparation for working group last call. As with previous releases, see the “Open Issues” sections for a small number of discussion points that I believe merit working group attention.

I also applied the changes made to the JOSE specs to the related individual submission JWS JSON Serialization and JWE JSON Serialization specs, which enable multiple recipients.

The working group specifications are available at:

The individual submission 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-03

  • Added the cty (content type) header parameter for declaring type information about the secured content, as opposed to the typ (type) header parameter, which declares type information about this object.
  • Added “Collision Resistant Namespace” to the terminology section.
  • Reference ITU.X690.1994 for DER encoding.
  • Added an example JWS using ECDSA P-521 SHA-512. This has particular illustrative value because of the use of the 521 bit integers in the key and signature values. This is also an example in which the payload is not a base64url encoded JSON object.
  • Added an example x5c value.
  • No longer say “the UTF-8 representation of the JWS Secured Input (which is the same as the ASCII representation)”. Just call it “the ASCII representation of the JWS Secured Input”.
  • Added Registration Template sections for defined registries.
  • Added Registry Contents sections to populate registry values.
  • Changed name of the JSON Web Signature and Encryption “typ” Values registry to be the JSON Web Signature and Encryption Type Values registry, since it is used for more than just values of the typ parameter.
  • Moved registries JSON Web Signature and Encryption Header Parameters and JSON Web Signature and Encryption Type Values to the JWS specification.
  • Numerous editorial improvements.

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

  • Added the kdf (key derivation function) header parameter to provide crypto agility for key derivation. The default KDF remains the Concat KDF with the SHA-256 digest function.
  • Reordered encryption steps so that the Encoded JWE Header is always created before it is needed as an input to the AEAD “additional authenticated data” parameter.
  • Added the cty (content type) header parameter for declaring type information about the secured content, as opposed to the typ (type) header parameter, which declares type information about this object.
  • Moved description of how to determine whether a header is for a JWS or a JWE from the JWT spec to the JWE spec.
  • Added complete encryption examples for both AEAD and non-AEAD algorithms.
  • Added complete key derivation examples.
  • Added “Collision Resistant Namespace” to the terminology section.
  • Reference ITU.X690.1994 for DER encoding.
  • Added Registry Contents sections to populate registry values.
  • Numerous editorial improvements.

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

  • Clarified that kid values need not be unique within a JWK Set.
  • Moved JSON Web Key Parameters registry to the JWK specification.
  • Added “Collision Resistant Namespace” to the terminology section.
  • Changed registration requirements from RFC Required to Specification Required with Expert Review.
  • Added Registration Template sections for defined registries.
  • Added Registry Contents sections to populate registry values.
  • Numerous editorial improvements.

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

  • Always use a 128 bit “authentication tag” size for AES GCM, regardless of the key size.
  • Specified that use of a 128 bit IV is REQUIRED with AES CBC. It was previously RECOMMENDED.
  • Removed key size language for ECDSA algorithms, since the key size is implied by the algorithm being used.
  • Stated that the int key size must be the same as the hash output size (and not larger, as was previously allowed) so that its size is defined for key generation purposes.
  • Added the kdf (key derivation function) header parameter to provide crypto agility for key derivation. The default KDF remains the Concat KDF with the SHA-256 digest function.
  • Clarified that the mod and exp values are unsigned.
  • Added Implementation Requirements columns to algorithm tables and Implementation Requirements entries to algorithm registries.
  • Changed AES Key Wrap to RECOMMENDED.
  • Moved registries JSON Web Signature and Encryption Header Parameters and JSON Web Signature and Encryption Type Values to the JWS specification.
  • Moved JSON Web Key Parameters registry to the JWK specification.
  • Changed registration requirements from RFC Required to Specification Required with Expert Review.
  • Added Registration Template sections for defined registries.
  • Added Registry Contents sections to populate registry values.
  • No longer say “the UTF-8 representation of the JWS Secured Input (which is the same as the ASCII representation)”. Just call it “the ASCII representation of the JWS Secured Input”.
  • Added “Collision Resistant Namespace” to the terminology section.
  • Numerous editorial improvements.

http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-01

  • Added the cty (content type) header parameter for declaring type information about the secured content, as opposed to the typ (type) header parameter, which declares type information about this object. This significantly simplified nested JWTs.
  • Moved description of how to determine whether a header is for a JWS or a JWE from the JWT spec to the JWE spec.
  • Changed registration requirements from RFC Required to Specification Required with Expert Review.
  • Added Registration Template sections for defined registries.
  • Added Registry Contents sections to populate registry values.
  • Added “Collision Resistant Namespace” to the terminology section.
  • Numerous editorial improvements.

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

  • Tracked editorial changes made to the JWS spec.

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

  • Updated examples to track updated algorithm properties in the JWA spec.
  • Tracked editorial changes made to the JWE spec.

HTML formatted versions are available at:

Special thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund Jay for validating the JWE examples!