Author: Mike Jones Page 26 of 33

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:

• JSON Token Spec Results at IIW
• JSON Token Encryption Spec Results at IIW
• JSON Token Naming Spec Results at IIW
• JSON Public Key Spec Results at IIW

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

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

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:

1. Envelope parameters (such as the name of the signature parameter)
2. Claim names (such as the name of the issuer claim)
3. 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.

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.

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

I’ve produced a new JSON token draft based on a convergence proposal discussed with the authors of the other JSON signing proposals. I borrowed portions of this draft with permission from Dirk Balfanz, John Bradley, John Panzer, and Nat Sakimura, and so listed them as co-authors. (You shouldn’t take their being listed as authors as their blanket endorsement of its content, but I appreciate their willingness to let me build upon their work.)

Hopefully we can develop consensus positions on these and any other issues found during IIW. This doc is intended as a further step in that direction.

A detailed comparison of the precursor documents, which led to the convergence proposal incorporated in this draft, is posted on the OAuth working group list.

Recognizing that there is substantial interest in representing sets of claims in JSON tokens, Yaron Goland and I have put together a draft JSON Web Token (JWT) specification for that purpose and published it to the OAuth list, where it is being discussed.

While this was produced independently of Dirk Balfanz’s JSON token proposal, both of us agree that we should come up with a unified spec. Consider this draft an additional point in the possible design space from which to start discussions and drive consensus. (If you read the two proposals, I think you’ll find that there’s already a lot in common, which is great.)

By the way, the draft suggests that the acronym JWT be pronounced like the English word “jot”.

I’d love to hear your feedback.

====

NOTE: This specification version has been superseded by draft-ietf-oauth-json-web-token. Do not use this version other than for historical reference purposes.