JCA algorithm support

From version 4 of the Nimbus JOSE + JWT library virtually all crypto operations are performed via the standard Java crypto API. This abstraction permits easy plugin of alternative implementations (providers) for common cryptographic primitives and devices such as hardware security modules and smart cards.

JOSE algorithm support the Java

The stock JDK comes with a crypto provider which supports most standard JOSE algorithms. For those algorithms that are not supported, like RSASSA-PSS signatures (identified as JWS algorithms PS256, PS384 and PS512), you will need to install an additional JCA provider (library). BouncyCastle is the popular choice for that.

Use the table below to check of a JOSE algorithm is supported by your Java runtime.

BouncyCastle

BouncyCastle is an open source Java library which implements a dazzling array of cryptographic algorithms, and where possible, they have been made available via the standard JCA provider interface.

In terms of JOSE algorithm support, BouncyCastle can handle all those that are not covered out-of-the-box in Java 7 and 8.

How do you set up the BouncyCastle JCA provider in your application?

First, add a dependency to BouncyCastle 1.56 or a newer stable version in your project. If you use Maven:

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15on</artifactId>
    <version>[1.56,)</version>
</dependency>

Then, load the BouncyCastle JCA provider and add it to the list of the available providers in your Java runtime:

import java.security.Provider;
import java.security.Security;
import com.nimbusds.jose.crypto.bc.BouncyCastleProviderSingleton;

Provider bc = BouncyCastleProviderSingleton.getInstance();
Security.addProvider(bc);

That's it!

JWS and JWE algorithm support

The following table lists the JOSE algorithm support of the Java 7, Java 8 and BouncyCastle JCA providers.

Algorithm family Java 7 Java 8 Bouncy Castle
JWS alg
HS256, HS384, HS512
RS256, RS384, RS512
PS256, PS384, PS512
ES256, ES384, ES512
JWE alg
RSA1_5
RSA-OAEP, RSA-OAEP-256
A128KW, A192KW, A256KW
ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW
A128GCMKW, A192GCMKW, A256GCMKW
PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
JWE enc
A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
A128GCM, A192GCM, A256GCM
A128CBC+HS256, A256CBC+HS512 (deprecated)

Checking JOSE algorithm support programmatically

Version 4.3 of the library introduces a simple utility called JCASupport for checking whether a given JWS or JWE algorithm is supported by a JCA provider.

Example:

To check if the RSA-PSS signature algorithm PS256 is supported by the available JCA providers:

JCASupport.isSupported(JWSAlgorithm.RS512));

In Java 7 if you're using the default JCA providers you'll get a negative answer.

As we explained above, the open source BouncyCastle JCA provider has ready support for RSA-PSS signatures. Let's verify this:

Provider bc = BouncyCastleProviderSingleton.getInstance();

assert JCASupport.isSupported(JWSAlgorithm.PS256, bc);

Once loaded the BouncyCastle provider may be added to the global JCA provider list:

Security.addProvider(bc);
assert JCASupport.isSupported(JWSAlgorithm.PS256);

If you don't want to add BouncyCastle globally, can just set it for the particular RSA signer / verifier instance that you intend to use:

RSASSASigner signer = new RSASSASigner(privateKey);
signer.getJCAContext().setProvider(BouncyCastleProviderSingleton.getInstance());

RSASSAVerifier verifier = new RSASSAVerifier(publicKey);
verifier.getJCAContext().setProvider(BouncyCastleProviderSingleton.getInstance());