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.