Archive for the 'Cryptography' Category

April 26, 2013
Draft -10 of the JOSE Specifications

IETF logoBased upon working group feedback on the -09 drafts, I’ve released an update to the JSON Object Signing and Encryption (JOSE) specifications that changes the processing rules for JWEs encrypted to multiple recipients. The new processing rules enable using AES GCM for multiple-recipient JWE objects. This update makes no changes to the single-recipient case.

The updated specification versions are:

HTML formatted versions are also available at:

No Comments » Posted under Cryptography & JSON & Specifications

April 23, 2013
JOSE and JWT specs incorporating decisions from IETF 86

IETF logoNew versions of the JSON Object Signing and Encryption (JOSE) specifications JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithms (JWA) and the JSON Web Token (JWT) specification have been released that incorporate the working group decisions made during and since IETF 86.

The primary new features in these working group drafts are:

  • adding support for private and symmetric keys to JWK and JWA,
  • adding support for JSON Serializations to JWS and JWE,
  • replacing the custom JOSE CBC+HMAC algorithms with ones compatible with those proposed in draft-mcgrew-aead-aes-cbc-hmac-sha2,
  • defining that the default action for header parameters and claims that are not understood is to ignore them, while providing a way to designate that some extension header parameters must be understood.

More details on the changes made can be found in the Document History entries.

The specifications are available at:

HTML formatted versions are also available at:

No Comments » Posted under Claims & Cryptography & JSON & OAuth & Specifications

March 15, 2013
The Emerging JSON/REST-Based Identity Protocol Suite

IETF logo Last week at the Japan Identity and Cloud Symposium I gave a presentation on this topic: A new set of simple, open identity protocols is emerging that utilize JSON data representations and REST-based communication patterns, including OAuth, JSON Web Token (JWT), JSON Object Signing and Encryption (JOSE), and WebFinger. I’ve posted PowerPoint and PDF versions of the presentation.

Thanks again to the organizers of JICS 2013 for a great event!

No Comments » Posted under Claims & Cryptography & Events & Federation & JSON & OAuth & OpenID & Specifications

December 28, 2012
December 27, 2012 JOSE Release

IETF logoNew versions of the JOSE specs have been released incorporating feedback since IETF 85 in Atlanta. The highlight of this release is the new JSON Private and Symmetric Key spec, which extends JWKs to be able to represent private and symmetric keys. These sensitive keys can then be protected for transmission and storage by JWE encryption of their JWK representations.

One new feature added to JWK is the ability to optionally specify which specific algorithm the key is intended to be used with. (This is already existing practice for keys in X.509 format.) For instance, a symmetric key might be annotated to say that it is to be used with the “HS256” algorithm. Because the natural field name for this functionality is “alg”, the “alg” name is now used for this purpose (matching JWS and JWE) and the key type (formerly “alg”) is now denoted by the “kty” field.

This release incorporates editorial improvements suggested by Jeff Hodges and Hannes Tschofenig in their reviews of the JWT specification. Many of these simplified the terminology usage. See the Document History section of each specification for more details about the changes made.

This release is part of a coordinated release of JOSE, OAuth, and OpenID Connect specifications. You can read about the other releases here: OAuth Release Notes, OpenID Connect Release Notes.

The new specification versions are:

HTML formatted versions are available at:

3 Comments » Posted under Cryptography & JSON & Specifications

November 20, 2012
Developer Preview of Microsoft JWT Support

Vittorio Bertocci just wrote about a developer preview release of JWT support for the Windows Identity Framework (WIF). Among other things, his catalog of places that JWT is already in production use is worth taking note of. I encourage those of you who are using JWTs to download it and give it a spin. Any feedback you could provide on how it works for your use cases would be very valuable.

No Comments » Posted under Claims & Cryptography & JSON & Software

November 8, 2012
JOSE and JWT specs updated for IETF 85 working group meetings

IETF logoI’ve made a small set of updates to the JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT) specs in preparation for the JOSE and OAuth working group meetings at IETF 85. These updates incorporate resolutions to issues that have been discussed by the working groups since publication of the previous drafts.

Normative changes to the working group specs were to add length fields for PartyUInfo and PartyVInfo values for key derivation calculations and to change the JWK field identifiers for RSA keys from (mod, xpo) to (n, e). Fields for representing the RSA private key values needed for Chinese Remainder Theorem (CRT) calculations were added to the JSON Private Key specification.

The updated specs are available at:

HTML formatted versions are available at:

See the history entries in the specs for detailed change descriptions.

No Comments » Posted under Claims & Cryptography & JSON & OAuth & Specifications

October 28, 2012
Platform Support for JWA Crypto Algorithms

IETF logoIn preparation for discussions at the JOSE working group meeting at IETF 84 in Vancouver, BC, I did some investigation into the state of support for the JWA algorithms in common Web development platforms. This table contains the data gathered. It was also discussed at the July 2012 W3C WebCrypto F2F Meeting. I’m posting it now because I’d recently received a request for it and because it may be useful at the upcoming WebCrypto meeting at TPAC in Lyon and at IETF 85 in Atlanta.

Thanks to Roland Hedberg, Axel Nennker, Emmanuel Raviart, Nov Matake, Justin Richer, Edmund Jay, Wan-Teh Chang, Christopher Kula, and Ryan Sleevi for the data they provided. If you have more data that I should add, or believe that there are additional columns or rows we should track, please let me know.

No Comments » Posted under Cryptography & Events & JSON & Specifications

October 15, 2012
JOSE and JWT specs incorporating working group decisions since IETF 84

IETF logoNew versions of the JSON WEB {Signature,Encryption,Key,Algorithms,Token} (JWS, JWE, JWK, JWA, JWT) specifications have been released. These versions incorporate the decisions made by the JOSE working group during and since IETF 84.

The primary change was revising the JWE format to always use AEAD encryption algorithms. The companion change was defining two new composite AEAD algorithms “A128CBC+HS256” and “A256CBC+HS512” that use AES CBC to perform encryption and matching HMAC SHA-2 algorithms to perform an integrity check on the ciphertext and the parameters used to create it.

Other than that, all changes were local in scope, with no changes to JWS – other than changing the format of the “x5c” (X.509 Certificate Chain) from a string containing a list of certificate values to an array of strings containing certificate values. Likewise, the only changes to JWT were to track changes made in the specs that it uses.

Having addressed all the open issues with resolutions with apparent working group consensus, it’s my hope that the working group will decide to send these specifications to working group last call at IETF 85.

The companion JWS JSON Serialization and JWE JSON Serialization specs were also updated.

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

  • Changed x5c (X.509 Certificate Chain) representation from being a single string to being an array of strings, each containing a single base64 encoded DER certificate value, representing elements of the certificate chain.
  • Applied changes made by the RFC Editor to RFC 6749′s registry language to this specification.

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

  • Removed the int and kdf parameters and defined the new composite AEAD algorithms A128CBC+HS256 and A256CBC+HS512 to replace the former uses of AES CBC, which required the use of separate integrity and key derivation functions.
  • Included additional values in the Concat KDF calculation — the desired output size and the algorithm value, and optionally PartyUInfo and PartyVInfo values. Added the optional header parameters apu (agreement PartyUInfo), apv (agreement PartyVInfo), epu (encryption PartyUInfo), and epv (encryption PartyVInfo). Updated the KDF examples accordingly.
  • Promoted Initialization Vector from being a header parameter to being a top-level JWE element. This saves approximately 16 bytes in the compact serialization, which is a significant savings for some use cases. Promoting the Initialization Vector out of the header also avoids repeating this shared value in the JSON serialization.
  • Changed x5c (X.509 Certificate Chain) representation from being a single string to being an array of strings, each containing a single base64 encoded DER certificate value, representing elements of the certificate chain.
  • Added an AES Key Wrap example.
  • Reordered the encryption steps so CMK creation is first, when required.
  • Correct statements in examples about which algorithms produce reproducible results.

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

  • Changed the name of the JWK RSA exponent parameter from exp to xpo so as to allow the potential use of the name exp for a future extension that might define an expiration parameter for keys. (The exp name is already used for this purpose in the JWT specification.)
  • Clarify that the alg (algorithm family) member is REQUIRED.
  • Correct an instance of “JWK” that should have been “JWK Set”.
  • Applied changes made by the RFC Editor to RFC 6749′s registry language to this specification.

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

  • Removed the int and kdf parameters and defined the new composite AEAD algorithms A128CBC+HS256 and A256CBC+HS512 to replace the former uses of AES CBC, which required the use of separate integrity and key derivation functions.
  • Included additional values in the Concat KDF calculation — the desired output size and the algorithm value, and optionally PartyUInfo and PartyVInfo values. Added the optional header parameters apu (agreement PartyUInfo), apv (agreement PartyVInfo), epu (encryption PartyUInfo), and epv (encryption PartyVInfo).
  • Changed the name of the JWK RSA exponent parameter from exp to xpo so as to allow the potential use of the name exp for a future extension that might define an expiration parameter for keys. (The exp name is already used for this purpose in the JWT specification.)
  • Applied changes made by the RFC Editor to RFC 6749′s registry language to this specification.

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

  • Promoted Initialization Vector from being a header parameter to being a top-level JWE element. This saves approximately 16 bytes in the compact serialization, which is a significant savings for some use cases. Promoting the Initialization Vector out of the header also avoids repeating this shared value in the JSON serialization.
  • Applied changes made by the RFC Editor to RFC 6749′s registry language to this specification.
  • Reference RFC 6755 — An IETF URN Sub-Namespace for OAuth.

http://tools.ietf.org/html/draft-jones-jose-jws-json-serialization-02

  • Changed to use an array of structures for per-recipient values, rather than a set of parallel arrays.

http://tools.ietf.org/html/draft-jones-jose-jwe-json-serialization-02

  • Changed to use an array of structures for per-recipient values, rather than a set of parallel arrays.
  • Promoted Initialization Vector from being a header parameter to being a top-level JWE element. This saves approximately 16 bytes in the compact serialization, which is a significant savings for some use cases. Promoting the Initialization Vector out of the header also avoids repeating this shared value in the JSON serialization.

HTML formatted versions are available at:

No Comments » Posted under Claims & Cryptography & JSON & Specifications

September 18, 2012
W3C WebCrypto API First Public Working Draft

W3C logoAs many of you know, the W3C Web Cryptography Working Group is developing a WebIDL/JavaScript API for cryptography operations. They recently published their First Public Working Draft. One of their use cases is being able to use the WebCrypto API to implement the IETF JOSE specifications.

I encourage those of you who are interested to review the draft API specification. Comments can be sent to public-webcrypto-comments@w3.org. The latest public version of the specification can always be found at http://www.w3.org/TR/WebCryptoAPI/.

Also see the post by Virginie Galindo, the working group chair.

No Comments » Posted under Cryptography & Specifications

August 15, 2012
JSON Private Key Specification

IETF logoW3C logoThe W3C WebCrypto working group recently made an inquiry to the IETF JOSE working group about the possibility of defining a JSON representation for private keys. To facilitate discussion of this topic by both working groups, I created a draft JSON Private Key specification. The specification is very simple; it just defines two additional members for the JWK structure for representing the private parts of Elliptic Curve and RSA keys.

The specification is available at:

A HTML-formatted version of the specification is available at:

No Comments » Posted under Cryptography & JSON & Specifications

July 31, 2012
IETF 84 versions of JOSE and JWT specifications

IETF logoI’ve made a minor release of the JSON WEB {Signature,Encryption,Key,Algorithms,Token} (JWS, JWE, JWK, JWA, JWT) specifications to support the working group discussions at IETF 84 in Vancouver, BC. This release incorporates working group feedback since the minor release on July 16th and updates the lists of open issues in the JWE and JWA specifications.

The 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-05

  • Added statement that “StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied”.
  • Indented artwork elements to better distinguish them from the body text.

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

  • Support both direct encryption using a shared or agreed upon symmetric key, and the use of a shared or agreed upon symmetric key to key wrap the CMK.
  • Added statement that “StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied”.
  • Updated open issues.
  • Indented artwork elements to better distinguish them from the body text.

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

  • Indented artwork elements to better distinguish them from the body text.

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

  • Support both direct encryption using a shared or agreed upon symmetric key, and the use of a shared or agreed upon symmetric key to key wrap the CMK. Specifically, added the alg values dir, ECDH-ES+A128KW, and ECDH-ES+A256KW to finish filling in this set of capabilities.
  • Updated open issues.

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

  • Added statement that “StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied”.
  • Indented artwork elements to better distinguish them from the body text.

HTML-formatted versions are available at:

No Comments » Posted under Claims & Cryptography & JSON & Specifications

July 16, 2012
Pre-IETF 84 versions of JOSE and JWT specifications

IETF logoI’ve made a minor release of the JSON WEB {Signature,Encryption,Key,Algorithms,Token} (JWS, JWE, JWK, JWA, JWT) working group specifications and the JWS and JWE JSON Serialization (JWS-JS, JWE-JS) individual submission specifications in preparation for IETF 84 in Vancouver, BC. These versions incorporate feedback from working group members since the major release on July 6th, and update the lists of open issues in preparation for discussions in Vancouver (and on the working group mailing lists).

One significant addition is that the JWT and JWE-JS specs both now contain complete, testable examples with encrypted results. No normative changes were made.

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

  • Completed JSON Security Considerations section, including considerations about rejecting input with duplicate member names.
  • Completed security considerations on the use of a SHA-1 hash when computing x5t (x.509 certificate thumbprint) values.
  • Refer to the registries as the primary sources of defined values and then secondarily reference the sections defining the initial contents of the registries.
  • Normatively reference XML DSIG 2.0 [W3C.CR xmldsig core2 20120124] for its security considerations.
  • Added this language to Registration Templates: “This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted.”
  • Reference draft-jones-jose-jws-json-serialization instead of draft-jones-json-web-signature-json-serialization.
  • Described additional open issues.
  • Applied editorial suggestions.

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

  • Refer to the registries as the primary sources of defined values and then secondarily reference the sections defining the initial contents of the registries.
  • Normatively reference XML Encryption 1.1 [W3C.CR xmlenc core1 20120313] for its security considerations.
  • Reference draft-jones-jose-jwe-json-serialization instead of draft-jones-json-web-encryption-json-serialization.
  • Described additional open issues.
  • Applied editorial suggestions.

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

  • Refer to the registries as the primary sources of defined values and then secondarily reference the sections defining the initial contents of the registries.
  • Normatively reference XML DSIG 2.0 [W3C.CR xmldsig core2 20120124] for its security considerations.
  • Added this language to Registration Templates: “This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted.”
  • Described additional open issues.
  • Applied editorial suggestions.

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

  • Added text requiring that any leading zero bytes be retained in base64url encoded key value representations for fixed-length values.
  • Added this language to Registration Templates: “This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted.”
  • Described additional open issues.
  • Applied editorial suggestions.

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

  • Added an example of an encrypted JWT.
  • Added this language to Registration Templates: “This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted.”
  • Applied editorial suggestions.

http://tools.ietf.org/html/draft-jones-jose-jws-json-serialization-01

  • Generalized language to refer to Message Authentication Codes (MACs) rather than Hash-based Message Authentication Codes (HMACs).

http://tools.ietf.org/html/draft-jones-jose-jwe-json-serialization-01

  • Added a complete JWE-JS example.
  • Generalized language to refer to Message Authentication Codes (MACs) rather than Hash-based Message Authentication Codes (HMACs).

HTML-formatted versions are available at:

1 Comment » Posted under Claims & Cryptography & JSON & Specifications

July 9, 2012
JSON Serialization Specifications Renamed

IETF logoI renamed the JSON Serialization specifications so that they now have “jose” in the document name. Jim Schaad tells me that then they’ll automatically be added to the JOSE Related Documents list at http://datatracker.ietf.org/wg/jose/. No normative changes were made.

These documents use the JWS and JWE crypto calculations, but enable multiple parallel signatures and multiple recipients.

The new versions are:

HTML formatted versions are available at:

No Comments » Posted under Cryptography & JSON & Specifications

July 6, 2012
Updated versions of JOSE and JWT specifications

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!

1 Comment » Posted under Claims & Cryptography & JSON & Specifications

May 14, 2012
JSON Crypto Specs Draft -02: JWS, JWE, JWK, JWA and JSON Web Token (JWT) Draft -10

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:

1 Comment » Posted under Claims & Cryptography & JSON & Specifications

March 12, 2012
Draft -01 of JSON Crypto Specs: JWS, JWE, JWK, JWA, JWS-JS, JWE-JS

IETF logoNew versions of the IETF JSON Object Signing and Encryption (JOSE) specifications are now available that incorporate working group feedback since publication of the initial versions. 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

The most important changes are:

  • Added a separate integrity check for encryption algorithms without an integral integrity check.
  • Defined header parameters for including JWK public keys and X.509 certificate chains directly in the header.

See the Document History section in each specification for a more detailed list of changes.

Corresponding versions of the JSON Serialization specs, which use these JOSE drafts, are also available. Besides using JSON Serializations of the cryptographic results (rather than Compact Serializations using a series of base64url encoded values), these specifications also enable multiple digital signatures and/or HMACs to applied to the same message and enable the same plaintext to be encrypted to multiple recipients. They are:

  • JSON Web Signature JSON Serialization (JWS-JS)
  • JSON Web Encryption JSON Serialization (JWE-JS)

These specifications are available at:

HTML formatted versions are available at:

2 Comments » Posted under Cryptography & JSON & Specifications

March 5, 2012
JSON Serializations for JWS and JWE

IETF logoParticipants in the JOSE working group have described use cases where a JSON top-level representation of digitally signed, HMAC’ed, or encrypted content is desirable. They have also described use cases where multiple digital signatures and/or HMACs need to applied to the same message and where the same plaintext needs to be encrypted to multiple recipients.

Responding to those use cases and working group input, I have created two new brief specifications:

  • JSON Web Signature JSON Serialization (JWS-JS)
  • JSON Web Encryption JSON Serialization (JWE-JS)

These use the same cryptographic operations as JWS and JWE, but serialize the results into a JSON objects, rather than a set of base64url encoded values separated by periods (as is done for JWS and JWE to produce compact, URL-safe representations).

These drafts are available at:

HTML-formatted versions are available at:

Feedback welcome!

No Comments » Posted under Cryptography & JSON & Specifications

January 18, 2012
Initial IETF JOSE Specs: JWS, JWE, JWK, JWA

IETF logoThe initial versions of the IETF JSON Object Signing and Encryption (JOSE) specifications are now available. 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

They are refactored from the previous individual submission versions to move algorithms and identifiers into the separate JSA specification, per the working group charter. Also, per the working group’s input, the terminology usage has been changed to no longer call both digital signatures and HMACs “signatures”. The JOSE versions contain no normative changes from the individual submission versions.

These specifications are available at:

HTML formatted versions are available at:

No Comments » Posted under Cryptography & JSON & Specifications

December 14, 2011
SWD, JWT, JWS, JWE, JWK, and OAuth JWT Profile specs updated

OAuth logoNew versions of the SWD, JWT, JWS, JWE, JWK, and OAuth JWT Profile specs have been posted. They address a number of comments received on the JOSE list and at the JOSE WG meeting in Taipei and make a number of clarifications, corrections, and editorial improvements.

The only breaking change made was to use short names in the JWK spec, as suggested during the WG meeting in Taipei, since JWK Key Object values are used as JWE Ephemeral Public Keys, and so compactness matters. This also required corresponding changes in the JWE spec.

This checkin moves the definitions of the “prn” (principal) and “jti” (JSON Token ID) claims from other specs into the JWT spec, as both of these claims enable general token functionality that is likely to be used in many contexts.

This checkin is intended to be the last set of individual submissions of the JWS, JWE, and JWK drafts before they are refactored and submitted to the JOSE WG as working group drafts. The primary changes requested by the JOSE WG but not yet done are to break the algorithm profiles and identifiers out into a new spec and to rework the terminology in the signature spec to use different terms for digital signature and HMAC integrity operations.

See the Document History sections of each document for a detailed description of the changes made. These documents are available at:

HTML-formatted versions are available at:

Special thanks to Jim Schaad for his detailed comments on the JWS and JWE specs, many of which were incorporated into these drafts.

1 Comment » Posted under Claims & Cryptography & JSON & OAuth & Specifications

October 31, 2011
Updated versions of JWT, JWS, JWE, and JWK specs

I’ve posted updated versions of the JSON Web Token (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. No changes should be required to any existing deployments as a result of these updates.

The primary thrust of these changes was updating the JWT spec to describe how to create and process encrypted JWTs. (The previous JWT spec pre-dated publication of the JWE spec.) I also removed duplicate content from the JWT spec describing the steps to sign JWTs and instead simply referenced it in the JWS spec. Numerous suggestions on improving the specifications from the WOES and JOSE lists were also incorporated. The changelog entries are as follows:

draft-jones-json-web-token-06:

  • Reference and use content from [JWS] and [JWE], rather than repeating it here.
  • Simplified terminology to better match JWE, where the terms “JWT Header” and “Encoded JWT Header” are now used, for instance, rather than the previous terms “Decoded JWT Header Segment” and “JWT Header Segment”. Also changed to “Plaintext JWT” from “Unsigned JWT”.
  • Describe how to perform nested encryption and signing operations.
  • Changed “integer” to “number”, since that is the correct JSON type.
  • Changed StringAndURI to StringOrURI.

draft-jones-json-web-signature-03:

  • Simplified terminology to better match JWE, where the terms “JWS Header” and “Encoded JWS Header”, are now used, for instance, rather than the previous terms “Decoded JWS Header Input” and “JWS Header Input”. Likewise the terms “JWS Payload” and “JWS Signature” are now used, rather than “JWS Payload Input” and “JWS Crypto Output”.
  • The jku and x5u URLs are now required to be absolute URLs.
  • Removed this unnecessary language from the kid description: “Omitting this parameter is equivalent to setting it to an empty string”.
  • Changed StringAndURI to StringOrURI.

draft-jones-json-web-encryption-01:

  • Changed type of Ephemeral Public Key (epk) from string to JSON object, so that a JWK Key Object value can be used directly.
  • Specified that the Digest Method for ECDH-ES is SHA-256. (The specification was previously silent about the choice of digest method.)
  • The jku and x5u URLs are now required to be absolute URLs.
  • Removed this unnecessary language from the kid description: “Omitting this parameter is equivalent to setting it to an empty string”.
  • Use the same language as RFC 2616 does when describing GZIP message compression.

draft-jones-json-web-key-02:

  • Editorial changes to have this spec better match the JWT, JWS, and JWE specs. No normative changes.

 

The specs are available in the standard places. The HTML versions can be found at these locations:

Feedback welcome!

No Comments » Posted under Claims & Cryptography & JSON & Specifications

Next »