The Nimbus library for processing JWS/JWE/JWK/JWT objects in Java was updated to comply with the latest draft suite v10 released by the JOSE WG:

• [JWA] draft-ietf-jose-json-web-algorithms-10
• [JWS] draft-ietf-jose-json-web-signature-10
• [JWE] draft-ietf-jose-json-web-encryption-10
• [JWK] draft-ietf-jose-json-web-key-10
• [JWT] draft-ietf-oauth-json-web-token-07

An important change is the new method for authenticated AES/CBC encryption based on draft-mcgrew-aead-aes-cbc-hmac-sha2-01 – Authenticated Encryption with AES-CBC and HMAC-SHA. This replaced the previously used method based on a concatenating KDF.

Other changes include the introduction of an “crit” header parameter to designate custom JWS/JWE headers that shouldn’t be ignored by clients, also several changes in terminology and a change in AAD computation for AES/GCM to allow multiple recipients. The complete change log can be found in the draft document histories and the respective CHANGELOG file in the library package.

The new library version should appear in Maven Central within a few hours.

Thanks to everyone who contributed, also to our colleagues on the JOSE WG who continue work on refining the specs.

Hard work pays off. The positive and encouraging feedback that we started receiving from early adopters of Nimbus JOSE + JWT for Java was a great inspiration and at same time motivation to continue refinement of the library.

Developers cited the new JSON-based formats for message signing and encryption, JWS and JWE, being a significant improvement in terms of simplicity and programming, particularly in comparison with the existing XML digital signature standard. A lot of effort was put to ensure this simplicity was also carried in the library, by making its application facing calls and class structures as simple and intuitive as possible. The same approach was applied to the API for plugging crypto algorithms in, which should make tracking draft changes to JOSE algorithms easier too.

Our main intended use of JWS/JWE/JWT is for generating and processing tokens in OpenID Connect. Last week we found a nice use case for JWE to protect identity data that is exchanged between Nimbus AuthService agents and the SaaS apps of customers. Other users have reported success in using JWS/JWE to exchange patient records between hospitals, sign transactions and encrypt message channels between web services.

Huge thanks to the JOSE WG for crafting this specification as well as to all developers who contributed to the library and continue to do so.

Release 2.14 of the Nimbus JOSE + JWT library adds support for direct JWE encryption using shared symmetric keys. Our particular use case for that is to secure synchronisation of identity data between an on-premise user authentication agent and an OpenID Connect provider service that we’re currently developing.

Direct JWE encryption comes in handy when you have control over both communication endpoints and wish to save the overhead of issuing public / private key pairs, such as RSA, and then wrapping / unwrapping them for the actual encryption / decryption.

Direct encryption is represented by setting the algorithm (alg) header parameter to “dir” and then specifying the actual encryption method to apply on the plain text, e.g. 128-bit AES/GCM:

{ "alg":"dir", "enc":"A128GCM" }

Programmaticaly you can create the header like this:

import com.nimbusds.jose.*;
JWEHeader header = new JWEHeader(JWEAlgorithm.DIR, EncryptionMethod.A128GCM);

You can then complete the JWE object construction:

JWEObject jweObj = new JWEObject(header, new Payload("Hello world!"));

To encrypt the JWE object you need a key with the matching length for A128GCM encryption, that is 128 bits or 16 bytes. The key must be shared between sender and recipient and kept secret, of course.

import com.nimbusds.jose.crypto.*;

byte[16] key = { ... };
DirectEncrypter encrypter = new DirectEncrypter(key);

// You can now use the encrypter on one or more JWE objects 
// that you wish to secure
jweObject.encrypt(encrypter);
String jweString = jweObject.serialize();

The resulting JWE object string will then look similar to this:

eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..0CxTyOgMw0nsG-KS.BJkGEk8LW3qOOU6v.dkNwv-fbQOgoOuYr6Kg74g

Notice that the encrypted key part (the second part) of the JWE string is missing. RSA and ECC encryption will have it, but direct encryption not.

To decrypt the JWE string on the other end you need the same symmetric key.

jweObject = JWEObject.parse(jweString);
JWEDecrypter decrypter = new DirectDecrypter(key);
jweObject.decrypt(decrypter);

// Prints "Hello world!"
System.out.println(jweObject.getPayload());

The Nimbus JOSE+JWT library supports all standard encryption methods for direct JWE:

• A128CBC+HS256 – requires 256 bit symmetric key
• A256CBC+HS512 – requires 512 bit symmetric key
• A128GCM – requires 128 bit symmetric key
• A256GCM – requires 256 bit symmetric key

The new 2.13 release of the Java library for Javascript Object Signing and Encryption (JOSE) and JSON Web Tokens (JWT) adds support for RSA encryption. You can now create encrypted payloads and tokens with RSAES-PKCS1-V1_5 and  RSAES-OAEP, using the authenticated AES/CBC+HMAC and AES/GCM encryption methods.

The following example demonstrates the typical lifecycle of an encrypted JWT, secured with RSA-OAEP and 128-bit AES/GCM.

// Compose the JWT claims set
JWTClaimsSet jwtClaims = new JWTClaimsSet();
jwtClaims.setIssuer("https://openid.net");
jwtClaims.setSubject("alice");
List<String> aud = new ArrayList<String>();
aud.add("https://app-one.com");
aud.add("https://app-two.com");
jwtClaims.setAudience(aud);
// Set expiration in 10 minutes
jwtClaims.setExpirationTime(new Date(new Date().getTime() + 1000*60*10));
jwtClaims.setNotBeforeTime(new Date());
jwtClaims.setIssueTime(new Date());
jwtClaims.setJWTID(UUID.randomUUID().toString());

System.out.println(jwtClaims.toJSONObject());
// Produces 
// { 
//   "iss" : "https:\/\/openid.net",
//   "sub" : "alice",
//   "aud" : [ "https:\/\/app-one.com" , "https:\/\/app-two.com" ],
//   "exp" : 1364293137871,
//   "nbf" : 1364292537871,
//   "iat" : 1364292537871,
//   "jti" : "165a7bab-de06-4695-a2dd-9d8d6b40e443"
// }

// Request JWT encrypted with RSA-OAEP and 128-bit AES/GCM
JWEHeader header = new JWEHeader(JWEAlgorithm.RSA_OAEP, EncryptionMethod.A128GCM);

// Create the encrypted JWT object
EncryptedJWT jwt = new EncryptedJWT(header, jwtClaims);

// Create an encrypter with the specified public RSA key
RSAEncrypter encrypter = new RSAEncrypter(publicKey);

// Do the actual encryption
jwt.encrypt(encrypter);

// Serialise to JWT compact form
String jwtString = jwt.serialize();

System.out.println(jwtString);
// Produces 
//
// eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhHQ00ifQ.K52jFwAQJH-
// DxMhtaq7sg5tMuot_mT5dm1DR_01wj6ZUQQhJFO02vPI44W5nDjC5C_v4p
// W1UiJa3cwb5y2Rd9kSvb0ZxAqGX9c4Z4zouRU57729ML3V05UArUhck9Zv
// ssfkDW1VclingL8LfagRUs2z95UkwhiZyaKpmrgqpKX8azQFGNLBvEjXnx
// -xoDFZIYwHOno290HOpig3aUsDxhsioweiXbeLXxLeRsivaLwUWRUZfHRC
// _HGAo8KSF4gQZmeJtRgai5mz6qgbVkg7jPQyZFtM5_ul0UKHE2y0AtWm8I
// zDE_rbAV14OCRZJ6n38X5urVFFE5sdphdGsNlA.gjI_RIFWZXJwaO9R.oa
// E5a-z0N1MW9FBkhKeKeFa5e7hxVXOuANZsNmBYYT8G_xlXkMD0nz4fIaGt
// uWd3t9Xp-kufvvfD-xOnAs2SBX_Y1kYGPto4mibBjIrXQEjDsKyKwndxzr
// utN9csmFwqWhx1sLHMpJkgsnfLTi9yWBPKH5Krx23IhoDGoSfqOquuhxn0
// y0WkuqH1R3z-fluUs6sxx9qx6NFVS1NRQ-LVn9sWT5yx8m9AQ_ng8MBWz2
// BfBTV0tjliV74ogNDikNXTAkD9rsWFV0IX4IpA.sOLijuVySaKI-FYUaBy
// wpg

// Parse back
jwt = EncryptedJWT.parse(jwtString);

// Create a decrypter with the specified private RSA key
RSADecrypter decrypter = new RSADecrypter(privateKey);

// Decrypt
jwt.decrypt(decrypter);

// Retrieve JWT claims
System.out.println(jwt.getJWTClaimsSet().getIssuer());;
System.out.println(jwt.getJWTClaimsSet().getSubject());
System.out.println(jwt.getJWTClaimsSet().getAudience().size());
System.out.println(jwt.getJWTClaimsSet().getExpirationTime());
System.out.println(jwt.getJWTClaimsSet().getNotBeforeTime());
System.out.println(jwt.getJWTClaimsSet().getIssueTime());
System.out.println(jwt.getJWTClaimsSet().getJWTID());

Check out src/test/java/com/nimbusds/jwt/EncryptedJWTTest.java for the complete code.

Don’t forget that the library JavaDocs are your friend. They include full description of all classes and methods, references to the applicable JOSE and other spec sections as well as short code snippets.

Thanks for Axel Nennker, David Ortiz and Juraj Somorovsky from the JOSE community who contributed with concrete code and suggestions.

Note that the current A128CBC+HS256 and A256CBC+HS512
specifications may get revised by the JOSE WG to switch to draft-mcgrew-aead-aes-cbc-hmac-sha2-01 for appending authenticated encryption to AES/CBC.

Thanks to a contribution from Ville Kurkinen the Java library for handling JWS/JWE protected messages and JSON Web Tokens (JWT) has now Maven support.

You can download the library sources and compiled JAR from the project Git repo:

https://bitbucket.org/nimbusds/nimbus-jose-jwt/

The library supports all standard JSON Web Signature (JWS) algorithms based on HMAC encoding, RSA public/private keys and Elliptic Curve cryptography. See the Nimbus JOSE+JWT wiki for examples.