io.jsonwebtoken.security

Class Keys

java.lang.Object

io.jsonwebtoken.security.Keys

public final class Keys
extends java.lang.Object

Utility class for securely generating SecretKeys and KeyPairs.

Since:

0.10.0

Method Summary

Methods

Modifier and Type	Method and Description
static javax.crypto.SecretKey	hmacShaKeyFor(byte[] bytes) Creates a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.
static java.security.KeyPair	keyPairFor(SignatureAlgorithm alg) Returns a new KeyPair suitable for use with the specified asymmetric algorithm.
static javax.crypto.SecretKey	secretKeyFor(SignatureAlgorithm alg) Returns a new SecretKey with a key length suitable for use with the specified SignatureAlgorithm.

Methods inherited from class java.lang.Object

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

Method Detail

hmacShaKeyFor

public static javax.crypto.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

public static javax.crypto.SecretKey secretKeyFor(SignatureAlgorithm alg)
                                           throws java.lang.IllegalArgumentException

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:

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:

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

keyPairFor

public static java.security.KeyPair keyPairFor(SignatureAlgorithm alg)
                                        throws java.lang.IllegalArgumentException

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:

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:

JWA Algorithm	Key Size	JWA Curve Name	ASN1 OID Curve Name
EC256	256 bits	P-256	secp256r1
EC384	384 bits	P-384	secp384r1
EC512	512 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:

java.lang.IllegalArgumentException - if alg is not an asymmetric algorithm