io.jsonwebtoken

Enum SignatureAlgorithm

java.lang.Object

java.lang.Enum<SignatureAlgorithm>

io.jsonwebtoken.SignatureAlgorithm

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<SignatureAlgorithm>

public enum SignatureAlgorithm
extends java.lang.Enum<SignatureAlgorithm>

Type-safe representation of standard JWT signature algorithm names as defined in the JSON Web Algorithms specification.

Since:

0.1

Enum Constant Summary

Enum Constants

Enum Constant and Description
ES256 JWA algorithm name for ECDSA using P-256 and SHA-256
ES384 JWA algorithm name for ECDSA using P-384 and SHA-384
ES512 JWA algorithm name for ECDSA using P-521 and SHA-512
HS256 JWA algorithm name for HMAC using SHA-256
HS384 JWA algorithm name for HMAC using SHA-384
HS512 JWA algorithm name for HMAC using SHA-512
NONE JWA name for No digital signature or MAC performed
PS256 JWA algorithm name for RSASSA-PSS using SHA-256 and MGF1 with SHA-256.
PS384 JWA algorithm name for RSASSA-PSS using SHA-384 and MGF1 with SHA-384.
PS512 JWA algorithm name for RSASSA-PSS using SHA-512 and MGF1 with SHA-512.
RS256 JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-256
RS384 JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-384
RS512 JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-512

Method Summary

If the Key is a: And: With a key size of: The returned SignatureAlgorithm will be: SecretKeygetAlgorithm().equals("HmacSHA256")¹ 256 <= size <= 383 ²HS256SecretKeygetAlgorithm().equals("HmacSHA384")¹ 384 <= size <= 511 HS384SecretKeygetAlgorithm().equals("HmacSHA512")¹ 512 <= size HS512ECKeyinstanceof PrivateKey 256 <= size <= 383 ³ES256ECKeyinstanceof PrivateKey 384 <= size <= 511 ES384ECKeyinstanceof PrivateKey 4096 <= size ES512RSAKeyinstanceof PrivateKey 2048 <= size <= 3071 ^4,5RS256RSAKeyinstanceof PrivateKey 3072 <= size <= 4095 ⁵RS384RSAKeyinstanceof PrivateKey 4096 <= size ⁵RS512

Methods

Key Signature Algorithm

Modifier and Type	Method and Description
void	assertValidSigningKey(java.security.Key key) Returns quietly if the specified key is allowed to create signatures using this algorithm according to the JWT JWA Specification (RFC 7518) or throws an InvalidKeyException if the key is not allowed or not secure enough for this algorithm.
void	assertValidVerificationKey(java.security.Key key) Returns quietly if the specified key is allowed to verify signatures using this algorithm according to the JWT JWA Specification (RFC 7518) or throws an InvalidKeyException if the key is not allowed or not secure enough for this algorithm.
static SignatureAlgorithm	forName(java.lang.String value) Looks up and returns the corresponding SignatureAlgorithm enum instance based on a case-insensitive name comparison.
static SignatureAlgorithm	forSigningKey(java.security.Key key) Returns the recommended signature algorithm to be used with the specified key according to the following heuristics:
java.lang.String	getDescription() Returns the JWA algorithm description.
java.lang.String	getFamilyName() Returns the cryptographic family name of the signature algorithm.
java.lang.String	getJcaName() Returns the name of the JCA algorithm used to compute the signature.
int	getMinKeyLength() Returns the minimum key length in bits (not bytes) that may be used with this algorithm according to the JWT JWA Specification (RFC 7518).
java.lang.String	getValue() Returns the JWA algorithm name constant.
boolean	isEllipticCurve() Returns true if the enum instance represents an Elliptic Curve ECDSA signature algorithm, false otherwise.
boolean	isHmac() Returns true if the enum instance represents an HMAC signature algorithm, false otherwise.
boolean	isJdkStandard() Returns true if the algorithm is supported by standard JDK distributions or false if the algorithm implementation is not in the JDK and must be provided by a separate runtime JCA Provider (like BouncyCastle for example).
boolean	isRsa() Returns true if the enum instance represents an RSA public/private key pair signature algorithm, false otherwise.
static SignatureAlgorithm	valueOf(java.lang.String name) Returns the enum constant of this type with the specified name.
static SignatureAlgorithm[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NONE

public static final SignatureAlgorithm NONE

JWA name for No digital signature or MAC performed

HS256

public static final SignatureAlgorithm HS256

JWA algorithm name for HMAC using SHA-256

HS384

public static final SignatureAlgorithm HS384

JWA algorithm name for HMAC using SHA-384

HS512

public static final SignatureAlgorithm HS512

JWA algorithm name for HMAC using SHA-512

RS256

public static final SignatureAlgorithm RS256

JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-256

RS384

public static final SignatureAlgorithm RS384

JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-384

RS512

public static final SignatureAlgorithm RS512

JWA algorithm name for RSASSA-PKCS-v1_5 using SHA-512

ES256

public static final SignatureAlgorithm ES256

JWA algorithm name for ECDSA using P-256 and SHA-256

ES384

public static final SignatureAlgorithm ES384

JWA algorithm name for ECDSA using P-384 and SHA-384

ES512

public static final SignatureAlgorithm ES512

JWA algorithm name for ECDSA using P-521 and SHA-512

PS256

public static final SignatureAlgorithm PS256

JWA algorithm name for RSASSA-PSS using SHA-256 and MGF1 with SHA-256. This algorithm requires Java 11 or later or a JCA provider like BouncyCastle to be in the runtime classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime classpath.

PS384

public static final SignatureAlgorithm PS384

JWA algorithm name for RSASSA-PSS using SHA-384 and MGF1 with SHA-384. This algorithm requires Java 11 or later or a JCA provider like BouncyCastle to be in the runtime classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime classpath.

PS512

public static final SignatureAlgorithm PS512

JWA algorithm name for RSASSA-PSS using SHA-512 and MGF1 with SHA-512. This algorithm requires Java 11 or later or a JCA provider like BouncyCastle to be in the runtime classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime classpath.

Method Detail

values

public static SignatureAlgorithm[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (SignatureAlgorithm c : SignatureAlgorithm.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static SignatureAlgorithm valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

java.lang.NullPointerException - if the argument is null

getValue

public java.lang.String getValue()

Returns the JWA algorithm name constant.

Returns:

the JWA algorithm name constant.

getDescription

public java.lang.String getDescription()

Returns the JWA algorithm description.

Returns:

the JWA algorithm description.

getFamilyName

public java.lang.String getFamilyName()

Returns the cryptographic family name of the signature algorithm. The value returned is according to the following table:

Crypto Family

SignatureAlgorithm	Family Name
HS256	HMAC
HS384	HMAC
HS512	HMAC
RS256	RSA
RS384	RSA
RS512	RSA
PS256	RSA
PS384	RSA
PS512	RSA
ES256	ECDSA
ES384	ECDSA
ES512	ECDSA

Returns:

Returns the cryptographic family name of the signature algorithm.

Since:

0.5

getJcaName

public java.lang.String getJcaName()

Returns the name of the JCA algorithm used to compute the signature.

Returns:

the name of the JCA algorithm used to compute the signature.

isJdkStandard

public boolean isJdkStandard()

Returns true if the algorithm is supported by standard JDK distributions or false if the algorithm implementation is not in the JDK and must be provided by a separate runtime JCA Provider (like BouncyCastle for example).

Returns:

true if the algorithm is supported by standard JDK distributions or false if the algorithm implementation is not in the JDK and must be provided by a separate runtime JCA Provider (like BouncyCastle for example).

isHmac

public boolean isHmac()

Returns true if the enum instance represents an HMAC signature algorithm, false otherwise.

Returns:

true if the enum instance represents an HMAC signature algorithm, false otherwise.

isRsa

public boolean isRsa()

Returns true if the enum instance represents an RSA public/private key pair signature algorithm, false otherwise.

Returns:

true if the enum instance represents an RSA public/private key pair signature algorithm, false otherwise.

isEllipticCurve

public boolean isEllipticCurve()

Returns true if the enum instance represents an Elliptic Curve ECDSA signature algorithm, false otherwise.

Returns:

true if the enum instance represents an Elliptic Curve ECDSA signature algorithm, false otherwise.

getMinKeyLength

public int getMinKeyLength()

Returns the minimum key length in bits (not bytes) that may be used with this algorithm according to the JWT JWA Specification (RFC 7518).

Returns:

the minimum key length in bits (not bytes) that may be used with this algorithm according to the JWT JWA Specification (RFC 7518).

Since:

0.10.0

assertValidSigningKey

public void assertValidSigningKey(java.security.Key key)
                           throws InvalidKeyException

Returns quietly if the specified key is allowed to create signatures using this algorithm according to the JWT JWA Specification (RFC 7518) or throws an InvalidKeyException if the key is not allowed or not secure enough for this algorithm.

Parameters:

key - the key to check for validity.

Throws:

InvalidKeyException - if the key is not allowed or not secure enough for this algorithm.

Since:

0.10.0

assertValidVerificationKey

public void assertValidVerificationKey(java.security.Key key)
                                throws InvalidKeyException

Returns quietly if the specified key is allowed to verify signatures using this algorithm according to the JWT JWA Specification (RFC 7518) or throws an InvalidKeyException if the key is not allowed or not secure enough for this algorithm.

Parameters:

key - the key to check for validity.

Throws:

InvalidKeyException - if the key is not allowed or not secure enough for this algorithm.

Since:

0.10.0

forSigningKey

public static SignatureAlgorithm forSigningKey(java.security.Key key)
                                        throws InvalidKeyException

Returns the recommended signature algorithm to be used with the specified key according to the following heuristics:

Key Signature Algorithm

If the Key is a:	And:	With a key size of:	The returned SignatureAlgorithm will be:
SecretKey	getAlgorithm().equals("HmacSHA256")1	256 <= size <= 383 2	HS256
SecretKey	getAlgorithm().equals("HmacSHA384")1	384 <= size <= 511	HS384
SecretKey	getAlgorithm().equals("HmacSHA512")1	512 <= size	HS512
ECKey	instanceof PrivateKey	256 <= size <= 383 3	ES256
ECKey	instanceof PrivateKey	384 <= size <= 511	ES384
ECKey	instanceof PrivateKey	4096 <= size	ES512
RSAKey	instanceof PrivateKey	2048 <= size <= 3071 4,5	RS256
RSAKey	instanceof PrivateKey	3072 <= size <= 4095 5	RS384
RSAKey	instanceof PrivateKey	4096 <= size 5	RS512

Notes:

1. SecretKey instances must have an algorithm name equal to HmacSHA256, HmacSHA384 or HmacSHA512. If not, the key bytes might not be suitable for HMAC signatures will be rejected with a InvalidKeyException.
2. The JWT JWA Specification (RFC 7518, Section 3.2) mandates that HMAC-SHA-* signing keys MUST be 256 bits or greater. SecretKeys with key lengths less than 256 bits will be rejected with an WeakKeyException.
3. The JWT JWA Specification (RFC 7518, Section 3.4) mandates that ECDSA signing key lengths MUST be 256 bits or greater. ECKeys with key lengths less than 256 bits will be rejected with a WeakKeyException.
4. The JWT JWA Specification (RFC 7518, Section 3.3) mandates that RSA signing key lengths MUST be 2048 bits or greater. RSAKeys with key lengths less than 2048 bits will be rejected with a WeakKeyException.
5. Technically any RSA key of length >= 2048 bits may be used with the RS256, RS384, and RS512 algorithms, so we assume an RSA signature algorithm based on the key length to parallel similar decisions in the JWT specification for HMAC and ECDSA signature algorithms. This is not required - just a convenience.

This implementation does not return the PS256, PS256, PS256 RSA variant for any specified RSAKey because:

• The JWT JWA Specification (RFC 7518, Section 3.1) indicates that RS256, RS384, and RS512 are recommended algorithms while the PS* variants are simply marked as optional.
• The RS256, RS384, and RS512 algorithms are available in the JDK by default while the PS* variants require an additional JCA Provider (like BouncyCastle).

Finally, this method will throw an InvalidKeyException for any key that does not match the heuristics and requirements documented above, since that inevitably means the Key is either insufficient or explicitly disallowed by the JWT specification.

Parameters:

key - the key to inspect

Returns:

the recommended signature algorithm to be used with the specified key

Throws:

InvalidKeyException - for any key that does not match the heuristics and requirements documented above, since that inevitably means the Key is either insufficient or explicitly disallowed by the JWT specification.

Since:

0.10.0

forName

public static SignatureAlgorithm forName(java.lang.String value)
                                  throws SignatureException

Looks up and returns the corresponding SignatureAlgorithm enum instance based on a case-insensitive name comparison.

Parameters:

value - The case-insensitive name of the SignatureAlgorithm instance to return

Returns:

the corresponding SignatureAlgorithm enum instance based on a case-insensitive name comparison.

Throws:

SignatureException - if the specified value does not match any SignatureAlgorithm name.

SignatureException