Redesigning Nimbus JWT

In May 2012 we released the first comprehensive Java implementation of the upcoming Javascript Object Signing and Encryption (JOSE) RFC suit, with support for JWS, JWE and JWT messages. Over the following couple of months we collected feedback from initial adopters and also through our internal projects, such as our OpenID Connect server. We want to thank everyone who contributed to that!

Lessons learned:

Stateful JWS and JWE objects are good, keep them

The JWS and JWE messages were implemented as stateful classes. This feature enabled efficient in-place processing of the JOSE objects as they travel through the web app. To illustrate, suppose you’re running an OpenID Connect IdP which processes signed request objects:

// OpenID Connect IdP
AuthzRequest req = AuthzReq.parse(...);

try {
    req.getRequestObject().verify(JWSVerifier);

} catch (JOSEException e) {

   ...
}

When the request object is parsed and found to be valid in terms of syntax, it is given a state SIGNED. We then pass it to a service object to perform the necessary JWS signature verification. If verification passes this will be remembered in the request object state which will now be VERIFIED.

JWS objects have three states: UNSIGNED, SIGNED and VERIFIED.

When the JWS object is created for the first time from payload, its state is UNSIGNED. It’s then passed to a JWS signing service which appends the signature and the state becomes SIGNED. The object is then compact serialised and sent out.

On the receiver side the JWS object is parsed and again given a SIGNED state. It’s then passed to a JWS verification service and if it passes with success, its state becomes VERIFIED. It can then travel to the processing area of the web app.

JWE objects are represented similarly and have states UNENCRYPTED, ENCRYPTED and DECRYPTED.

Simplify plugin of crypto algorithms and backends

The first release of the library came with a fixed enumeration of cryptographic algorithms (JWAs) and other critical bits. The original intent of that was to simplify use by developers. Unfortunately, this proved to be a massive hindrance to implementing new algorithms and crypto backends.

In the new release we’ll get go of this limitation. There will be a single Java package dedicated to creating, representing and serialising the JOSE (JWS, JWE, JWK) objects. All crypto operations will be moved to separate packages, accessible through clean interfaces. With that you can implement crypto algorithms without having to fork the library and modify existing code.

Separate JOSE and JWT stuff

The initial release was heavily geared towards JSON Web Token (JWT) use. We then found out that not everyone uses it for that purpose. In the new release the JWT-specific code will be moved to a separate package. To reflect this change the library will be renamed to Nimbus JOSE + JWT.

The above changes are significant, so we decided to create a brand new Git repo for the 2.0 release.

We’re already working hard and by the end of September expect to have the new 2.0 version out. Comments and feedback are welcome as always!