Skip to content
Connect2id
JOSE

Nimbus JOSE + JWT 3.0, redesigned and with AES key wrap support

Thanks to Melisa Halsband, a contributor from CertiVox UK, the Nimbus library can now handle JSON Web Tokens (JWT) and other objects encrypted with a shared key using the AES or AES/GCM key wrap algorithm.

These are the JWA identifiers for the newly added algorithms:

  • For AES key wrap encryption: A128KW, A192KW and A256KW
  • For AES GCM key wrap encryption: A128CGMKW, A192CGMKW and A256CGMKW

Support of AES key wrap necessitated a number of braking changes to the JOSE header and object classes. That cleared the way for a number of other significant changes in the new 3.0 release, all of which we hope you’ll find useful :)

Simplified immutable headers

The plain / JWS / JWE header classes are now simplified and completely immutable, which makes for safer development. A builder is available to help you construct headers where you need to specify additional parameters than the mandatory alg and enc:

JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.RS256).
                   keyID("123").
                   contentType("text/plain").
                   customParam("exp", new Date().getTime()).
                   build();

To facilitate AES key wrap the JWE header was given direct support for the iv and tag parameter. We also added support for the new x4t#S256 (X.509 certificate SHA-256 thumbprint) header parameter added in draft 27 of the JOSE specs.

AES key wrap encryption

AES key wrap is useful in situations when you want to encrypt a message using a shared secret key, e.g. to ensure confidentiality of ID tokens in OpenID Connect where the client application has been issued with a simple client secret at registration.

Note that the key length must match the one required by the algorithm:

  • 128 bit key for A128KW
  • 192 bit key for A192KW
  • 256 bit key for A256KW
// Create JWE object
JWEHeader header = new JWEHeader(JWEAlgorithm.A128KW, EncryptionMethod.A128CBC_HS256);
Payload payload = new Payload("Hello world!");
JWEObject jweObject = new JWEObject(header, payload);

// Encrypt with secret key
JWEEncrypter encrypter = new AESEncrypter(secretKey);
jweObject.encrypt(encrypter);

// Output JWE string
jweObject.serialize();

// ...


// Parse JWE string on recipient side
jweObject = JWEObject.parse(jweString);

// Decrypt with same secret key
JWEDecrypter decrypter = new AESDecrypter(key128);
jweObject.decrypt(decrypter);

// Get the decrypted payload
assertEquals("Hello world!", jweObject.getPayload().toString());

Encryption with AES GCM key wrap is similar, you just need to specify A128GCMKW as the JWE algorithm instead.

Serialising single-valued JWT audience (aud) claims

A developer complained that some JWT libraries cannot handle JWT audience (aud) values that are JSON arrays, even in the simple case (array with a single audience). To enable interop with such software we decided to modify the JWTClaimsSet class, so that single-valued aud claims are now output as a string.

JWT claims set with a single aud:

{
 "iss": "https://c2id.com",
 "sub": "alice",
 "aud": "http://app.example.com"
}

JWT claims set with multiple aud values:

{
 "iss": "https://c2id.com",
 "sub": "alice",
 "aud": [ "http://app1.example.com", "http://app2.example.com" ]
}

Java 7 is now the minimum requirement

With the new 3.0 release you will now need Java 7 to build and run the library. Java 6 is no longer officially supported as of February 2013, so we decided to drop support for it too, and start enjoying the language features Java 7 has to offer (and are already eyeing Java 8, but we’ll have to be patient ;)

Matching IETF specifications

From the JOSE WG:

From the OAuth WG:

Download

The Maven Dependency for the new 3.0 release:

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>nimbus-jose-jwt</artifactId>
    <version>3.0</version>
</dependency>

For other methods check out the downloads page.