io.jsonwebtoken.security

Class Keys

java.lang.Object

io.jsonwebtoken.security.Keys

public final class Keys
extends Object

Utility class for securely generating SecretKeys and KeyPairs.

Since:

0.10.0

Method Summary

Methods

Modifier and Type	Method and Description
static PrivateKeyBuilder	builder(PrivateKey key) Returns a PrivateKeyBuilder that produces the specified key, allowing association with a publicKey to obtain public key data if necessary, or a provider that must be used with the key during cryptographic operations.
static SecretKeyBuilder	builder(SecretKey key) Returns a SecretKeyBuilder that produces the specified key, allowing association with a provider that must be used with the key during cryptographic operations.
static SecretKey	hmacShaKeyFor(byte[] bytes) Creates a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.
static KeyPair	keyPairFor(SignatureAlgorithm alg) Deprecated. since 0.12.0 in favor of your preferred SignatureAlgorithm instance's keyPair() builder method directly.
static Password	password(char[] password) Returns a new Password instance suitable for use with password-based key derivation algorithms.
static SecretKey	secretKeyFor(SignatureAlgorithm alg) Deprecated. since 0.12.0. Use your preferred MacAlgorithm instance's key() builder method directly.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

hmacShaKeyFor

public static SecretKey hmacShaKeyFor(byte[] bytes)
                               throws WeakKeyException

Creates a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.

Parameters:

bytes - the key byte array

Returns:

a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.

Throws:

WeakKeyException - if the key byte array length is less than 256 bits (32 bytes) as mandated by the JWT JWA Specification (RFC 7518, Section 3.2)

secretKeyFor

@Deprecated
public static SecretKey secretKeyFor(SignatureAlgorithm alg)
                              throws IllegalArgumentException

Deprecated. since 0.12.0. Use your preferred MacAlgorithm instance's key() builder method directly.

Deprecation Notice

As of JJWT 0.12.0, symmetric (secret) key algorithm instances can generate a key of suitable length for that specific algorithm by calling their key() builder method directly. For example:

 Jwts.SIG#HS256.key().build();
 Jwts.SIG#HS384.key().build();
 Jwts.SIG#HS512.key().build();
 

Call those methods as needed instead of this static secretKeyFor helper method - the returned KeyBuilder allows callers to specify a preferred Provider or SecureRandom on the builder if desired, whereas this secretKeyFor method does not. Consequently this helper method will be removed before the 1.0 release.

Previous Documentation

Returns a new SecretKey with a key length suitable for use with the specified SignatureAlgorithm.

JWA Specification (RFC 7518), Section 3.2 requires minimum key lengths to be used for each respective Signature Algorithm. This method returns a secure-random generated SecretKey that adheres to the required minimum key length. The lengths are:

JWA HMAC-SHA Key Length Requirements

Algorithm	Key Length
HS256	256 bits (32 bytes)
HS384	384 bits (48 bytes)
HS512	512 bits (64 bytes)

Parameters:

alg - the SignatureAlgorithm to inspect to determine which key length to use.

Returns:

a new SecretKey instance suitable for use with the specified SignatureAlgorithm.

Throws:

IllegalArgumentException - for any input value other than SignatureAlgorithm.HS256, SignatureAlgorithm.HS384, or SignatureAlgorithm.HS512

keyPairFor

@Deprecated
public static KeyPair keyPairFor(SignatureAlgorithm alg)
                          throws IllegalArgumentException

Deprecated. since 0.12.0 in favor of your preferred SignatureAlgorithm instance's keyPair() builder method directly.

Deprecation Notice

As of JJWT 0.12.0, asymmetric key algorithm instances can generate KeyPairs of suitable strength for that specific algorithm by calling their keyPair() builder method directly. For example:

 Jwts.SIG.RS256.keyPair().build();
 Jwts.SIG.RS384.keyPair().build();
 Jwts.SIG.RS512.keyPair().build();
 ... etc ...
 Jwts.SIG.ES512.keyPair().build();

Call those methods as needed instead of this static keyPairFor helper method - the returned KeyPairBuilder allows callers to specify a preferred Provider or SecureRandom on the builder if desired, whereas this keyPairFor method does not. Consequently this helper method will be removed before the 1.0 release.

Previous Documentation

Returns a new KeyPair suitable for use with the specified asymmetric algorithm.

If the alg argument is an RSA algorithm, a KeyPair is generated based on the following:

Generated RSA Key Sizes

JWA Algorithm	Key Size
RS256	2048 bits
PS256	2048 bits
RS384	3072 bits
PS384	3072 bits
RS512	4096 bits
PS512	4096 bits

If the alg argument is an Elliptic Curve algorithm, a KeyPair is generated based on the following:

Generated Elliptic Curve Key Parameters

JWA Algorithm	Key Size	JWA Curve Name	ASN1 OID Curve Name
ES256	256 bits	P-256	secp256r1
ES384	384 bits	P-384	secp384r1
ES512	521 bits	P-521	secp521r1

Parameters:

alg - the SignatureAlgorithm to inspect to determine which asymmetric algorithm to use.

Returns:

a new KeyPair suitable for use with the specified asymmetric algorithm.

Throws:

IllegalArgumentException - if alg is not an asymmetric algorithm

password

public static Password password(char[] password)

Returns a new Password instance suitable for use with password-based key derivation algorithms.

Usage Note: Using Passwords outside of key derivation contexts will likely fail. See the Password JavaDoc for more, and also note the Password Safety section below.

Password Safety

Instances returned by this method use a clone of the specified password character array argument - changes to the argument array will NOT be reflected in the returned key, and vice versa. If you wish to clear a Password instance to ensure it is no longer usable, call its Destroyable.destroy() method will clear/overwrite its internal cloned char array. Also note that each subsequent call to Password.toCharArray() will also return a new clone of the underlying password character array per standard JCE key behavior.

Parameters:

password - the raw password character array to clone for use with password-based key derivation algorithms.

Returns:

a new Password instance that wraps a new clone of the specified password character array.

Since:

0.12.0

See Also:

Password.toCharArray()

builder

public static SecretKeyBuilder builder(SecretKey key)

Returns a SecretKeyBuilder that produces the specified key, allowing association with a provider that must be used with the key during cryptographic operations. For example:

 SecretKey key = Keys.builder(key).provider(mandatoryProvider).build();

Cryptographic algorithm implementations can inspect the resulting key instance and obtain its mandatory Provider if necessary.

This method is primarily only useful for keys that cannot expose key material, such as PKCS11 or HSM (Hardware Security Module) keys, and require a specific Provider to be used during cryptographic operations.

Parameters:

key - the secret key to use for cryptographic operations, potentially associated with a configured Provider

Returns:

a new SecretKeyBuilder that produces the specified key, potentially associated with any specified provider.

Since:

0.12.0

builder

public static PrivateKeyBuilder builder(PrivateKey key)

Returns a PrivateKeyBuilder that produces the specified key, allowing association with a publicKey to obtain public key data if necessary, or a provider that must be used with the key during cryptographic operations. For example:

 PrivateKey key = Keys.builder(privateKey).publicKey(publicKey).provider(mandatoryProvider).build();

Cryptographic algorithm implementations can inspect the resulting key instance and obtain its mandatory Provider or PublicKey if necessary.

This method is primarily only useful for keys that cannot expose key material, such as PKCS11 or HSM (Hardware Security Module) keys, and require a specific Provider or public key data to be used during cryptographic operations.

Parameters:

key - the private key to use for cryptographic operations, potentially associated with a configured Provider or PublicKey.

Returns:

a new PrivateKeyBuilder that produces the specified private key, potentially associated with any specified provider or PublicKey

Since:

0.12.0