Category: Cryptography Page 11 of 12

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

I’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:

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:

Pre-IETF 84 versions of JOSE and JWT specifications

On July 16, 2012

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

I’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:

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:

JSON Serialization Specifications Renamed

On July 9, 2012

I 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:

Updated versions of JOSE and JWT specifications

On July 6, 2012

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

New 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:

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!

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

On May 14, 2012

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

JSON 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:

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:

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

On March 12, 2012

New 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:

JSON Serializations for JWS and JWE

On March 5, 2012

Participants 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!

Initial IETF JOSE Specs: JWS, JWE, JWK, JWA

On January 18, 2012

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

SWD, JWT, JWS, JWE, JWK, and OAuth JWT Profile specs updated

On December 14, 2011

In Claims, Cryptography, JSON, OAuth, Specifications

OAuth logo New 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.

Updated versions of JWT, JWS, JWE, and JWK specs

On October 31, 2011

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

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:

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!

JSON Web Key (JWK) draft -01

On July 25, 2011

I’ve published JSON Web Key (JWK) draft -01. It contains the following changes:

Changed “algorithm” member value for Elliptic Curve keys from “ECDSA” to “EC”, since Elliptic Curve keys can be used with more algorithms than just the Elliptic Curve Digital Signature Algorithm (ECDSA).
Added OPTIONAL “use” member to identify intended key usage, especially since the same Elliptic Curve key should not be used for both signing and encryption operations.

The specification is available at these locations:

http://www.ietf.org/internet-drafts/draft-jones-json-web-key-01.txt
http://www.ietf.org/internet-drafts/draft-jones-json-web-key-01.xml
https://self-issued.info/docs/draft-jones-json-web-key-01.html
https://self-issued.info/docs/draft-jones-json-web-key-01.txt
https://self-issued.info/docs/draft-jones-json-web-key-01.xml
https://self-issued.info/docs/draft-jones-json-web-key.html (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-key.txt (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-key.xml (will point to new versions as they are posted)
http://svn.openid.net/repos/specifications/json_web_key/1.0/ (Subversion repository, with html, txt, and html versions available)

JSON Web Key (JWK) Specification

On April 30, 2011

I’ve posted the JSON Web Key (JWK) specification for representing public keys as JSON objects based on the decisions made at the last IIW. The introduction to the spec reads:

A JSON Web Key (JWK) is a JSON data structure that represents a set of public keys as a JSON object. The JWK format is used to represent bare keys; representing certificate chains is an explicit non-goal of this specification. JSON Web Keys are referenced in JSON Web Signatures (JWSs) using the jku (JSON Key URL) header parameter.

An example from the spec is:

{"keyvalues": [ {"algorithm":"ECDSA", "curve":"P-256", "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", "keyid":"1"},

{"algorithm":"RSA", "modulus": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", "exponent":"AQAB", "keyid":"2011-04-29"} ] }

The specification is available at these locations:

http://www.ietf.org/internet-drafts/draft-jones-json-web-key-00.txt
http://www.ietf.org/internet-drafts/draft-jones-json-web-key-00.xml
https://self-issued.info/docs/draft-jones-json-web-key-00.html
https://self-issued.info/docs/draft-jones-json-web-key-00.txt
https://self-issued.info/docs/draft-jones-json-web-key-00.xml
https://self-issued.info/docs/draft-jones-json-web-key.html (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-key.txt (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-key.xml (will point to new versions as they are posted)
http://svn.openid.net/repos/specifications/json_web_key/1.0/ (Subversion repository, with html, txt, and html versions available)

I also updated the description of the JSON Web Signature (JWS) header parameter “jku” (JSON Key URL) to reference the JWK spec in draft -02.

The Emerging JSON-Based Identity Protocol Suite

On April 28, 2011

In Claims, Cryptography, Documentation, Events, JSON, OAuth, OpenID, Specifications

My submission to the W3C Workshop on Identity in the Browser discusses The Emerging JSON-Based Identity Protocol Suite. The abstract is:

A new set of open identity protocols is emerging that utilizes JSON data representations and simple REST-based communication patterns. These protocols and data formats are intentionally designed to be easy to use in browsers and modern web development environments.

I hope you’ll find it worthwhile reading. I’m looking forward to discussing it with many of you at the workshop!

JSON Web Token (JWT) and JSON Web Signature (JWS) now in separate specs

On March 25, 2011

As promised, I have split the contents of the JWT spec draft-jones-json-web-token-01 into two simpler specs:

These should have introduced no semantic changes from the previous spec.

I then applied the feedback that I received since JWT -01 and created revised versions of the split specs:

The only breaking change introduced was that x5t (X.509 Certificate Thumbprint) is now a SHA-1 hash of the DER-encoded certificate, rather than a SHA-256 has, as SHA-1 is the prevailing existing practice for certificate thumbprint calculations. See the Document History sections for details on each change made.

.txt and .xml versions are also available. I plan to publish these as IETF drafts once the submission window re-opens on Monday. Feedback welcome!

P.S. Yes, work on the companion encryption spec is now under way…

JSON Web Token (JWT) Draft -01

On January 4, 2011

Draft -01 of the JSON Web Token (JWT) specification is now available. This version incorporates the consensus decisions reached at the Internet Identity Workshop. The remaining open issues and to-do items are documented in Section 12. As a reminder, the suggested pronunciation of JWT is the same as the English word “jot”.

The draft is available at these locations:

http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.txt
http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.xml
https://self-issued.info/docs/draft-jones-json-web-token-01.html
https://self-issued.info/docs/draft-jones-json-web-token-01.txt
https://self-issued.info/docs/draft-jones-json-web-token-01.xml
https://self-issued.info/docs/draft-jones-json-web-token.html (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-token.txt (will point to new versions as they are posted)
https://self-issued.info/docs/draft-jones-json-web-token.xml (will point to new versions as they are posted)
http://svn.openid.net/repos/specifications/json_web_token/1.0/ (Subversion repository, with html, txt, and html versions available)

The decisions reached at IIW are documented here:

Thanks to all who provided the input that led to this draft! Feedback is highly welcome.

JSON Public Key Spec Results at IIW on Thursday

On November 9, 2010

The final session at IIW related to JSON Web Tokens (JWTs) explored whether and how to represent public key information as JWTs or other JSON structures as an alternative to X.509 certificates. Thanks to Breno de Medeiros for taking notes, which I’ve pasted in below:

Issue/Topic: Public Key Certificates as JWT
Session: Thursday 1E
Convener: Mike Jones, Microsoft
Notes-taker(s): Breno de Medeiros
Tags: If and how to represent public key certificates as JSON Web Tokens
Discussion notes:

Certificate installation a difficult and core technical obstacle in configuring security
Not all cases require PKI validation; motivation examples given by J. Panzer et. al., drove the proposal for the Magic Signatures specs
In the absence of PKI certificates, it’s not possible to ‘preserve’ the security context around fetching the certificate
Is there a need to invent another type of JSON-based certificate? Do we have a need for certificates in addition to bare keys?
Why re-invent X.509? Create a JSON binding for the subset of KeyInfo from X.509 that is needed to advertise keys
After reviewing the KeyInfo, decided that the part of it of interest is trivially small and already described in competing proposals
Even a JWT is too complex, only need to create a simple descriptor for the key in JSON
Key_id needed

Decision: Go with simple approach

Keep this mini-spec separate from JWT and cross-reference? Or include this in the expanded spec of JWT to include encryption?

Decision: Keep specs separate

Need to allow this to have a URL-safe representation such as compact JWT?

Examples of what these representations might look like are as follows:

{"keyvalues": [ {"alg":"ECDSA", "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", "keyid":"1"},

{"alg":"RSA", "modulus": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", "exponent":"AQAB", "keyid":"2"} ] }

Near the end of the discussion, it was pointed out that want we are proposing is much closer to the XMLDSIG KeyValue element than the KeyInfo element.

The participants recognize that the security of these raw keys is dependent upon the security of the mechanisms for distributing them — in most cases TLS.

References:

XML Signature Syntax and Processing (Second Edition): http://www.w3.org/TR/xmldsig-core/
Using the Elliptic Curve Signature Algorithm (ECDSA) for XML Digital Signatures: http://tools.ietf.org/html/rfc4050
Additional XML Security Uniform Resource Identifiers (URIs): http://tools.ietf.org/html/rfc4051
Magic Signatures: http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-experimental-00.html

JSON Token Naming Spec Results at IIW on Wednesday

On November 9, 2010

We held a session on naming for JSON Web Tokens (JWTs) at IIW, building upon the results from the JSON Tokens and No Base String sessions on Tuesday and the JSON Token Encryption session on Wednesday. Like the previous sessions, there was a clear consensus for the decisions the group made.

Names are needed for these specification elements:

Envelope parameters (such as the name of the signature parameter)
Claim names (such as the name of the issuer claim)
Algorithm names (such as the names representing the HMAC SHA-256 and AES-256-CBC algorithms)

The first issue tacked by the participants was whether short names should be used in order to keep tokens concise (and in particular, in order to have them be potentially usable in query strings for mobile phone browsers with 512-character URL limits), or whether to use longer, descriptive names. For instance, the name of an algorithm parameter could be either “alg” or “algorithm”. By a 7-2 vote, the participants opted for short names.

We next used the names in the current JWT spec to drive discussion on specific names in each category. In keeping with the decision to employ short names, Nat Sakimura suggested that the few names over three characters in length — specifically “keyid” and “curi” also be shortened to three-character names. The other participants concurred with this suggestion.

A discussion was held on behalf of Paul Tarjan of Facebook on defining a standard time-issued-at claim (which together with the expires claim, bounds the token lifetime). There was consensus that this claim should be defined by the specification.

George Fletcher led a discussion on whether an issued-to claim distinct from the audience claim should be defined. The group didn’t feel strongly about this, but voted 3-1 against including it. The participants noted that any claims meaningful to both parties can be defined as needed, so all claims need not be pre-defined in the specification.

The group discussed what algorithm names should be used. It was agreed that while each software package uses specific names for algorithms, because they tend to differ by software package, there is no compelling reason to choose one set over another. And indeed, given the group’s over-arching decision to use short names, people felt that employing short names such as “HS256” imposed no more burden on implementers that using longer names like “HMAC-SHA-256” or “http://www.w3.org/2001/04/xmldsig-more#hmac-sha256”. Thus, the short names in the current JWT spec were endorsed, with the understanding that additional names will be needed for encryption algorithm names and names of recommended algorithm combinations.

To help implementers, the group suggested that the specification include a table cross-referencing the algorithm name strings used in standard software packages and specifications. Breno de Medeiros supplied a link to the JCE algorithm names for inclusion in this table.

While not strictly on the topic of naming, the group held a discussion of how to factor the JWT specification or specifications so as to maximize its acceptance and adoption. The choices discussed were (1) a single specification, (2) a part one specification covering signing and claims and a part two specification covering encryption, and (3) three related specifications — one for signing, one for claims, and one for encryption. The consensus was for (2), since the normal use case will always include signed sets of claims, whereas people should only need to pay the price to understand encryption if they actually need to employ it.

Finally, Nat Sakimura asked if we wanted the branding of the specification or specifications to be more general than JSON Web Token (JWT), since the scope of the work is actually broader — encompassing JSON encodings for claims, signing, and encryption. Mike Jones took the position that, given that this is a composite spec including JWT claims, that we’re better off branding it in a way that matches the common use case, and therefore and keeping the name JWT as the overall brand. The participants concurred.

JSON Token Encryption Spec Results at IIW on Wednesday

On November 8, 2010

We held a session on encryption for JSON Web Tokens at IIW on Wednesday, building upon the results from the JSON Tokens and No Base String sessions on Tuesday. Once again, substantial consensus emerged, which is described in the notes below.

These consensus decisions were in place by the start of the session:

Some use cases for JSON tokens require encryption
(plus all the decisions from the sessions on Tuesday)

It was agreed that these sets of high-level goals need to be achievable by application of signing and/or encryption:

Integrity
Confidentiality + Integrity
Non-Repudiation (which also implies Integrity)
Non-Repudiation + Confidentiality

Open issues identified at the start of the session were:

Should encryption and signing be accomplished via (1) separate but composable encryption and signing operations, (2) use of a small set of recommended composite operations that achieve the high-level goals, or (3) allowing for both possibilities?
Data format and how data formats affect streaming operations
Order of signing and encryption operations
Compress before encrypt?
What are we encrypting (payload or payload + signature)?

The primary consensus in the room was to invent as little as possible by reusing work that other experts have done in the space, while adapting their work to a JSON context. Participants provided the following references to work to borrow from:

Cryptographic Message Syntax (CMS): http://tools.ietf.org/html/rfc5652
Table of Algorithm Suites from WS-SecurityPolicy 1.2, section 6.1: http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html#_Toc161826547
XML Signature Syntax and Processing (Second Edition): http://www.w3.org/TR/xmldsig-core/
XML Encryption Syntax and Processing: http://www.w3.org/TR/xmlenc-core/
Defective Sign and Encrypt analysis: http://world.std.com/~dtd/sign_encrypt/sign_encrypt7.PDF
The TLS Protocol Version 1.0: http://tools.ietf.org/html/rfc2246
Transport Layer Security Protocol Compression Methods: http://tools.ietf.org/html/rfc3749
Compressed Data Content Type for Cryptographic Message Syntax (CMS): http://tools.ietf.org/html/rfc3274
DEFLATE Compressed Data Format Specification version 1.3: http://tools.ietf.org/html/rfc1951

Specific issues were resolved as follows:

Should encryption and signing be accomplished via (1) separate but composable encryption and signing operations, (2) use of a small set of recommended composite operations that achieve the high-level goals, or (3) allowing for both possibilities?

The consensus was for (3) — that we should specify a small set of composite operations that will meet the needs of common use cases, while also enabling applications to compose encryption and signing operations in a general fashion, should the composite operations prove insufficient for their use cases. A subset of the composite algorithm suites in WS-SecurityPolicy 1.2 was suggested as an appropriate starting point. Paul Tarjan of Facebook had also suggested during the OpenID Summit on Monday that descriptive composite algorithm values be used, such as “AES-256-CBC HMAC-SHA-256”.

Data format and how data formats affect streaming operations

For the same reasons as discussed during the signing session, the group reaffirmed that the order of the fields should be envelope.payload.signature, with the envelope containing sufficient information to determine the nature of the contents of the remaining fields. This order enables streaming operations, where content is created or analyzed in parallel with its transmission or reception, to the maximum extent possible, and also potentially minimizes buffering requirements imposed upon implementations.

Order of signing and encryption operations

It was recognized that no one-size-fits-all solution applies here and that different sets of operations are needed for different use cases. For instance, if non-repudiation is required, a signature of the plan text using public key cryptography must be present, which therefore must precede any other operations. Again, the group reaffirmed that we should reuse other work in this area to the extent possible.

Compress before encrypt?

Several participants pointed out existing practice in this area, including the use of the DEFLATE compression algorithm prior to encryption by TLS and CMS. It was agreed that we should similarly document how to optionally perform compression before encryption for those use cases where it makes sense.

What are we encrypting (payload or payload + signature)?

This was another area were the participants felt that we should reuse existing practice that has already been vetted by experts.

Special thanks go to Breno de Medeiros, whose crypto expertise was invaluable during this session, as well as Brad Hill, Diana Smetters and several other Googlers, John Bradley, Nat Sakimura, Joseph Holsten, Thomas Hardjono, Terry Hayes, Dick Hardt, Tony Nadalin, and others who contributed to this productive session.

JSON Token Spec Results at IIW on Tuesday

On November 3, 2010

We held two back-to-back sessions at IIW on Tuesday intended to produce consensus positions on JSON Web Tokens, including signing and encryption. Substantial consensus emerged, which is described in the notes below.

These consensus decisions were in place by the start of the session:

There is an envelope (a.k.a. header) that completely describes the cryptographic algorithm(s) used
There is a payload (a.k.a. body) that is distinct from the envelope
There is a signature that is distinct from the envelope and payload
Base64url encoding without padding is used to encode the parts above
The compact token representation separates the three encoded parts above by periods
No line breaks or other whitespace may be present in this representation
Encryption must be supported as well as signatures
The token representation should be compact
In particular, this means that multiple base64url encodings of the same content should be avoided
Any need for canonicalization should be avoided

Open issues identified at the start of the session were:

Ordering of the fields
Ordering of the signing and encryption operations
What can be in an envelope (a small fixed set of things or is it extensible)?
What to sign (envelope.payload or just payload)?
What can be in the payload (only sets of JSON token claims or arbitrary base64url encoded byte streams)?
Do we need to support multiple signatures?
Should we specify a JSON serialization as well as a compact serialization?

These issues were resolved as follows:

Ordering of the fields

By a vote of 8 to 1, people preferred the ordering envelope.payload.signature over the ordering signature.envelope.payload. Two reasons were cited: First, this allows for stream-mode operations, where consumers can begin operations based upon the contents of the envelope before the signature has arrived without having to buffer the signature, and where producers can compute the signature in parallel with the transmission of the envelope and payload. The counter-argument advanced by Paul Tarjan of Facebook (in abstentia) is that all languages have a string operation to split a string on the first occurrence of a character.

Ordering of the signing and encryption operations

How to compose these operations depends upon scenario requirements. Goals identified include Integrity, Confidentiality + Integrity, and Non-Repudiation. Brad Hill identified four sets of relevant operations, which were public key signature, symmetric key MAC, symmetric key confidentiality + MAC, and key wrap/key transport/agreement with Diffie-Hellman. Some took the position that we should define a small set of fixed configurations that are known to safely achieve the intended goals; others argued for general composability of operations. This was the one topic that we had to defer to a follow-on session to be held the next day, due to time limitations.

What can be in an envelope (a small fixed set of things or is it extensible)?

We reached a consensus that the envelope needs to be extensible (but should be extended only with great care).

What to sign (envelope.payload or just payload)?

Given that the envelope is extensible and therefore may contain security-sensitive information, we reached a consensus (with input from Ben Laurie via IM) that the combination envelope.payload must be signed.

What can be in the payload (only sets of JSON token claims or arbitrary base64url encoded byte streams)?

By a vote of 9 to 2, the group decided that the spec should support signing/encrypting of arbitrary base64url encoded byte streams. They also decided that the spec should define the syntax and semantics of a set of claims when what is being signed is a set of JSON claims.

Do we need to support multiple signatures?

The group voted 5 to 2 that it must be possible to support multiple signatures in some manner. Two variants of multiple signatures were discussed: the “gateway case”, where additional signatures are added to a token as it is passed between parties, and the parallel case, where multiple parties sign the same contents up front. However the group also decided that it would be overly complicated to support multiple signatures in the compact serialization. Support for multiple signatures was pushed to the JSON serialization (per the next issue).

Should we specify a JSON serialization as well as a compact serialization?

The group decided by a vote of 11 to 1 that there were use cases for a JSON serialization, and that multiple signatures would be possible in that serialization. The syntax agreed upon simply uses the three base64url encoded fields, while allowing there to be parallel arrays of envelopes and signatures. Specifically, the syntax agreed upon was:
{"envelope":["<envelope 1 contents>",...,"<envelope N contents>"], "payload":"<payload contents>", "signature":["<signature 1 contents>",...,"<signature N contents>"] }
and where the i^th signature is computed on the concatenation of <envelope i contents>.<payload contents>.

Updated JSON Web Token (JWT) draft based upon convergence proposal

On October 25, 2010