Welcome to jose.4.j!

The jose.4.j library is an open source (Apache 2.0) implementation of JWT and the JOSE specification suite. It is written in Java and relies solely on the JCA APIs for cryptography.

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. JWT is the identity token format in OpenID Connect and it is also widely used in OAuth 2.0 and many other contexts that require compact message security.

The JWT code examples page shows how to easily produce and consume JWTs using this library.

JOSE is short for Javascript Object Signing and Encryption, which is the IETF Working Group that developed the JSON Web Signature (JWS), JSON Web Encryption (JWE) and JSON Web Key (JWK) specifications. JWS and JWE use JSON and base64url encoding to secure messages in a (relatively) simple, compact and web safe format while JWK defines a JSON representation of cryptographic keys. The actual algorithms for JWS, JWE and JWK are defined in JSON Web Algorithms (JWA).

The library supports the JWS/JWE compact serializations with the complete suite of JOSE algorithms. A more detailed breakdown is available below in the Algorithm Support section.

Getting the Library

The jose4j library is available in the Maven Central Repository. To use it in your project, add the following dependency to the <dependencies> section of your pom:

  <dependency>
    <groupId>org.bitbucket.b_c</groupId>
    <artifactId>jose4j</artifactId>
    <version>0.9.6</version>
  </dependency>

Dependency coordinate information for a number of other systems is available on the artifact details at central and compiled jars are also available on the downloads page.

Code Examples

jose.4.j is very easy to use and, to help get started, some code examples are provided demonstrating common things you might want to do with it.

Hello World JWE Example

The following snippet uses JWE to both encrypt and decrypt the message "Hello World!" in just a few lines of code.

 Key key = new AesKey(ByteUtil.randomBytes(16));
 JsonWebEncryption jwe = new JsonWebEncryption();
 jwe.setPayload("Hello World!");
 jwe.setAlgorithmHeaderValue(KeyManagementAlgorithmIdentifiers.A128KW);
 jwe.setEncryptionMethodHeaderParameter(ContentEncryptionAlgorithmIdentifiers.AES_128_CBC_HMAC_SHA_256);
 jwe.setKey(key);
 String serializedJwe = jwe.getCompactSerialization();
 System.out.println("Serialized Encrypted JWE: " + serializedJwe);
 jwe = new JsonWebEncryption();
 jwe.setAlgorithmConstraints(new AlgorithmConstraints(ConstraintType.PERMIT, 
        KeyManagementAlgorithmIdentifiers.A128KW));
 jwe.setContentEncryptionAlgorithmConstraints(new AlgorithmConstraints(ConstraintType.PERMIT, 
        ContentEncryptionAlgorithmIdentifiers.AES_128_CBC_HMAC_SHA_256));
 jwe.setKey(key);
 jwe.setCompactSerialization(serializedJwe);
 System.out.println("Payload: " + jwe.getPayload());

More Examples

Additional and more detailed examples and explanations are available:

• JWT Examples shows how to produce and consume JSON Web Tokens (including using Ed25519 EdDSA and X25519 ECDH).

• JWS Examples shows how to easily apply and verify signatures including how to use the "b64" RFC 7797 JWS Unencoded Payload Option

• JWE Examples shows how to encrypt and decrypt messages.

• A very simple Android project showing how to use jose4j with Android keystore system keys requiring user biometric authentication for use

• GSON serialization/deserialization of JWK objects

• Jackson serialization/deserialization of JWK objects

• A presentation at IIW 18 and a similar one at CIS 2014 have some code examples along with some general information about JOSE and JWT.

• Javadocs are online here at javadoc.io though they are currently a touch sparse on actual documentation (but getting better!)

• Response and analysis to some potential JWT vulnerabilities has some (maybe) useful info on using AlgorithmConstraints to specify what algorithms are allowed per JOSE or JWT object

Release Notes

The Release Notes give a changelog of the project.

Need help?

There's a jose4j tag on Stack Overflow that I (and some others) are reasonably attentive to. The project issue tracker is unfortunately sometimes not available due to excessive SPAM.

Security Considerations

Axel Nennker‏ has written some security considerations

Algorithm Support

All of the JOSE algorithms are fully implemented by jose4j. However, the library relies on the underlying cryptography provider in the Java Runtime Environment so, depending on the deployment environment, some algorithms may not be available at runtime. The tables below lists all the supported JWS/JWE/JWK algorithms and is annotated with some common JCA provider requirements.

JWS

JWE Key Encryption and Key Agreement

JWE Content Encryption

JWE Compression

JWK

* Requires the JCE's Unlimited Strength Jurisdiction Policy Files be installed for the JRE (download for Java 7 and Java 8 and note that later versions have the unlimited cryptographic policy enabled by default).
† Requires Java 11, Java 8 Java 8u251, or the Bouncy Castle JCA provider (or another provider which supports RSASSA-PSS)
‡ Requires Java 8 or the Bouncy Castle v1.50+ JCA provider (or another provider which supports AEAD ciphers though the JCA interface including recognizing GCMParameterSpec)
¶ Requires Java 8 or the Bouncy Castle JCA provider (or another provider which supports RSA/ECB/OAEPWithSHA-256AndMGF1Padding and an OAEPParameterSpec that indicates SHA-256 for MGF1)
§ Requires a provider that supports the secp256k1 curve (prior to Java 16 or Bouncy Castle)
‡‡ Requires Java 17
†† Requires Java 11

Dependencies

Jose4j is compiled for Java 7 and will run on Java 8 and later versions.

The jose.4.j library relies on the Simple Logging Facade for Java (SLF4J). Prior to v0.4.4 Appache Commons Logging was used.

As of v0.3.7 jose4j's JSON processing was derived from the JSON.simple toolkit and Base64 encoding/decoding was derived from the Apache Commons Codec project.

Acknowledgments

I'd like to thank Dan McNulty, Daniel Bleichenbacher, Mitch Dusina, Dmitry Vsekhvalnov, Guoping Liu, Jason Musgrave, Jeremie Miller, John Bradley, Justin Kwong, Travis Spencer, Joseph Heenan, Thomas Broyer, Tim McLean, Jan Høydahl, Jan Willem Janssen, Magnus Andersson, Samo Remec, Axel Nennker‏, Yaroslav Soltys, Quan Nguyen, Sergey Beryozkin, Yang Yu, James Manger, Aaron Levin, Eivind Larsen, Bastien Jansen, Marcin Nowak, Jesse Yang, Mitch Dusina, Thomas Zimmermann and Antonio Sanso for feedback and suggestions (please let me know if you deserve acknowledgment but I've somehow forgotten you).

Lastly, but maybe most importantly, I'd like to thank my employer, Ping Identity. I do believe that Ping benefits from this work (the library is used extensively in Ping's products). But I know for sure none of it would have happened without Ping.