Wiki

Clone wiki

jose4j / Home

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:

  • A very simple Android project showing how to use jose4j with Android keystore system keys requiring user biometric authentication for use
  • Javadocs are online here at javadoc.io though they are currently a touch sparse on actual documentation (but getting better!)

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

Digital Signature or MAC AlgorithmJWS "alg" Parameter Value
HMAC using SHA-2HS256, HS384 and HS512
RSASSA-PKCS1-V1_5 Digital Signatures with with SHA-2RS256, RS384 and RS512
Elliptic Curve Digital Signatures (ECDSA) with SHA-2ES256, ES384, ES512 and ES256K§
RSASSA-PSS Digital Signatures with SHA-2PS256†, PS384† and PS512†
Edwards-Curve Digital Signature AlgorithmEdDSA‡‡
Unsigned Plaintextnone


JWE Key Encryption and Key Agreement

Key Management AlgorithmJWE "alg" Parameter Value
Direct encryption with a shared symmetric keydir
RSAES-PKCS1-V1_5 key encryptionRSA1_5
RSAES using OAEP key encryptionRSA-OAEP and RSA-OAEP-256¶
AES key wrapA128KW, A192KW* and A256KW*
AES GCM key encryptionA128GCMKW‡, A192GCMKW*‡ and A256GCMKW*‡
Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDFECDH-ES
Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF with AES key wrapECDH-ES+A128KW, ECDH-ES+A192KW*, ECDH-ES+A256KW*
PBES2 with HMAC SHA-2 and AES key wrappingPBES2-HS256+A128KW, PBES2-HS384+A192KW* and PBES2-HS512+A256KW*


JWE Content Encryption

Content Encryption AlgorithmJWE "enc" Parameter Value
Authenticated encryption with AES-CBC and HMAC-SHA2A128CBC-HS256, A192CBC-HS384* and A256CBC-HS512*
Authenticated encryption with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM)A128GCM‡, A192GCM*‡ and A256GCM*‡


JWE Compression

Compression AlgorithmJWE "zip" Parameter Value
DEFLATE Compressed Data Format from RFC 1951DEF


JWK

Key TypeJWK "kty" Parameter Value
Elliptic Curve Public/Private KeysEC
RSA Public/Private KeysRSA
Symmetric Keys (Octet sequence)oct
Octet Key Pair (Ed25519/Ed448‡‡ & X25519/X448††)OKP


* 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.

Updated