Package net.shibboleth.oidc.security.impl

Class JWETokenDecrypter

java.lang.Object

net.shibboleth.oidc.security.impl.JWETokenDecrypter

public class JWETokenDecrypter
extends Object

Supports decryption of encrypted JSON Web Tokens using the JSON Web Encryption standard. The EncryptedJWT will be decrypted in-place, with its JWEObject.State changing to JWEObject.State.DECRYPTED on successful decryption. Any error that occurs decrypting the JWT will throw an DecryptionException.

A decrypter should be created for each new decryption operation.

Since:

2.2.0

Field Summary

Fields

Modifier and Type	Field	Description
private org.slf4j.Logger	log	Class logger.
private DecryptionParameters	params	The JWT decryption parameters.

Constructor Summary

Constructors

Constructor	Description
JWETokenDecrypter(DecryptionParameters decryptionParams)	Constructor.

Method Summary

Modifier and Type	Method	Description
private void	buildContentEncryptionKeyAlgorithmCriteria(CriteriaSet criteriaSet, com.nimbusds.jwt.EncryptedJWT encryptedObject)	Optionally build decryption key 'enc' (encryption key algorithm) credential criteria according to information in the encrypted object.
private CriteriaSet	buildCriteria(com.nimbusds.jwt.EncryptedJWT encryptedObject, List<Criterion> criteria)	Build a criteria set using the additional criteria in the params, those supplied, and those that relate to the encrypted JWT.
private KeyAlgorithmCriterion	buildKeyAlgorithmCriteria(String algorithmURI)	Dynamically construct key algorithm credential criteria based on the specified algorithm URI.
private KeyLengthCriterion	buildKeyLengthCriteria(String encAlgorithmURI)	Dynamically construct key length credential criteria based on the specified algorithm URI.
private void	buildKeyManagementAlgorithmCriteria(CriteriaSet criteriaSet, com.nimbusds.jwt.EncryptedJWT encryptedObject)	Optionally build decryption key 'alg' (key management algorithm) credential criteria according to information in the encrypted object.
com.nimbusds.jwt.JWT	decrypt(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Decrypt a JWE object using credentials resolved from the CEK and KEK resolvers inside the decryption parameters.
private void	decryptUsingDirectEncryption(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Decrypt the encrypted JWT using direct encryption.
private void	decryptUsingKeyAgreement(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Decrypt the encrypted JWT by computing the content encryption key using Elliptic Curve Diffie-Hellman key agreement.
private void	decryptUsingKeyEncryption(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Decrypt the encrypted JWT by first decrypting the content encryption key using one of the (asymmetric) key encryption keys resolved by the DecryptionParameters.getKEKCredentialResolver() resolver.
private void	decryptUsingKeyWrapping(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Decrypt the encrypted JWT by first decrypting the wrapped content encryption key using one of the shared key wrapping keys derived from a symmetric key resolved by the DecryptionParameters.getKEKCredentialResolver() resolver.
private void	validateAlgorithmURI(String algorithmURI)	Validate the supplied algorithm URI against the configured include and exclude lists.
private com.nimbusds.jose.EncryptionMethod	validateContentEncryptionAlgorithm(com.nimbusds.jwt.EncryptedJWT encryptedObject)	Validates the 'enc' algorithm in the header against the include and exclude algorithm URI lists.
private com.nimbusds.jose.EncryptionMethod	validateContentEncryptionAlgorithm(com.nimbusds.jwt.EncryptedJWT encryptedObject, JWKCredential cred)	Validates the 'enc' algorithm in the header matches the encryption algorithm specified for the credential, and validates against the include and exclude algorithm URI lists.
private com.nimbusds.jose.JWEAlgorithm	validateKeyManagmentAlgorithm(com.nimbusds.jwt.EncryptedJWT encryptedObject, JWKCredential cred)	If the credential contains algorithm 'alg' information, validate the 'alg' algorithm in the JWT JOSE header matches the algorithm specified for the credential.

Methods inherited from class java.lang.Object

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

Field Detail

log

private final org.slf4j.Logger log

Class logger.

params

private final DecryptionParameters params

The JWT decryption parameters.

Constructor Detail

JWETokenDecrypter

public JWETokenDecrypter(@Nonnull
                         DecryptionParameters decryptionParams)

Constructor.

Parameters:

decryptionParams - the parameters to use during decryption

Method Detail

decrypt

@Nonnull
public com.nimbusds.jwt.JWT decrypt(@Nonnull
                                    com.nimbusds.jwt.EncryptedJWT encryptedObject)
                             throws DecryptionException

Decrypt a JWE object using credentials resolved from the CEK and KEK resolvers inside the decryption parameters. Supports Direct Encryption, Key Encryption, Key Wrapping, and Key Agreement management modes.

Parameters:

encryptedObject - JWE object to decrypt.

Returns:

Decrypted JWT object.

Throws:

DecryptionException - on failure to decrypt the JWT.

buildCriteria

@Nonnull
private CriteriaSet buildCriteria(@Nonnull
                                  com.nimbusds.jwt.EncryptedJWT encryptedObject,
                                  @Nullable
                                  List<Criterion> criteria)

Build a criteria set using the additional criteria in the params, those supplied, and those that relate to the encrypted JWT.

Parameters:

encryptedObject - the encrypted JWT to build criterion from

criteria - criteria supplied, can be null.

Returns:

the build criteria set.

buildKeyManagementAlgorithmCriteria

@Nullable
private void buildKeyManagementAlgorithmCriteria(@Nonnull
                                                 CriteriaSet criteriaSet,
                                                 @Nonnull
                                                 com.nimbusds.jwt.EncryptedJWT encryptedObject)

Optionally build decryption key 'alg' (key management algorithm) credential criteria according to information in the encrypted object.

Parameters:

criteriaSet - the criteria set to add built criteria too

encryptedObject - the encrypted JWT from which to deduce decryption key 'alg' criteria

buildContentEncryptionKeyAlgorithmCriteria

@Nullable
private void buildContentEncryptionKeyAlgorithmCriteria(@Nonnull
                                                        CriteriaSet criteriaSet,
                                                        @Nonnull
                                                        com.nimbusds.jwt.EncryptedJWT encryptedObject)

Optionally build decryption key 'enc' (encryption key algorithm) credential criteria according to information in the encrypted object.

Parameters:

criteriaSet - the criteria

encryptedObject - the encrypted JWT from which to deduce decryption key 'enc' criteria

buildKeyAlgorithmCriteria

@Nullable
private KeyAlgorithmCriterion buildKeyAlgorithmCriteria(@Nullable
                                                        String algorithmURI)

Dynamically construct key algorithm credential criteria based on the specified algorithm URI.

Parameters:

algorithmURI - the algorithm URI

Returns:

a new key algorithm credential criteria instance, or null if criteria could not be determined

buildKeyLengthCriteria

@Nullable
private KeyLengthCriterion buildKeyLengthCriteria(@Nullable
                                                  String encAlgorithmURI)

Dynamically construct key length credential criteria based on the specified algorithm URI.

Parameters:

encAlgorithmURI - the algorithm URI

Returns:

a new key length credential criteria instance, or null if the value could not be determined

decryptUsingKeyAgreement

private void decryptUsingKeyAgreement(com.nimbusds.jwt.EncryptedJWT encryptedObject)
                               throws DecryptionException

Decrypt the encrypted JWT by computing the content encryption key using Elliptic Curve Diffie-Hellman key agreement. The private EC key is resolved from the DecryptionParameters.getKEKCredentialResolver().

For each credential, algorithm compatibly is checked against that described by the JWE and any includes and excludes lists configured.

The process terminates when a resolved credential decrypts the JWT. The resolvers should only retrieve appropriate keys, but that is not guaranteed.

Parameters:

encryptedObject - the encrypted JWT to decrypt - in place.

Throws:

DecryptionException - if any of the resolved credentials could not be used to decrypt the JWT.

decryptUsingKeyWrapping

private void decryptUsingKeyWrapping(@Nonnull
                                     com.nimbusds.jwt.EncryptedJWT encryptedObject)
                              throws DecryptionException

Decrypt the encrypted JWT by first decrypting the wrapped content encryption key using one of the shared key wrapping keys derived from a symmetric key resolved by the DecryptionParameters.getKEKCredentialResolver() resolver.

For each credential, algorithm compatibly is checked against that described by the JWE and any includes and excludes lists configured.

The process terminates when the first resolved credential (that decrypts the CEK) decrypts the JWT. The resolvers should only retrieve appropriate keys, but that is not guaranteed.

Parameters:

encryptedObject - the encrypted JWT to decrypt - in place.

Throws:

DecryptionException - if the resolved credentials could not be used to decrypt the JWT.

decryptUsingKeyEncryption

private void decryptUsingKeyEncryption(com.nimbusds.jwt.EncryptedJWT encryptedObject)
                                throws DecryptionException

Decrypt the encrypted JWT by first decrypting the content encryption key using one of the (asymmetric) key encryption keys resolved by the DecryptionParameters.getKEKCredentialResolver() resolver.

For each credential, algorithm compatibly is checked against that described by the JWE and any includes and excludes lists configured.

The process terminates when the first resolved credential (that decrypts the CEK) decrypts the JWT. The resolvers should only retrieve appropriate keys, but that is not guaranteed.

Parameters:

encryptedObject - the encrypted JWT to decrypt - in place.

Throws:

DecryptionException - if the resolved credentials could not be used to decrypt the JWT.

decryptUsingDirectEncryption

private void decryptUsingDirectEncryption(@Nonnull
                                          com.nimbusds.jwt.EncryptedJWT encryptedObject)
                                   throws DecryptionException

Decrypt the encrypted JWT using direct encryption. One of the shared symmetric keys resolved by the DecryptionParameters.getContentEncryptionKeyCredentialResolver() is used to derive a content encryption key to decrypt the JWT - if any are appropriate.

For each credential, algorithm compatibly is checked against that described by the JWE and any includes and excludes lists configured.

The first resolved (and derived) credential that decrypts the JWT produces a result, and the process terminates. The resolvers should only retrieve appropriate keys, but that is not guaranteed.

Parameters:

encryptedObject - the encrypted JWT to decrypt - in place.

Throws:

DecryptionException - if the resolved credentials could not be used to decrypt the JWT.

validateKeyManagmentAlgorithm

private com.nimbusds.jose.JWEAlgorithm validateKeyManagmentAlgorithm(@Nonnull
                                                                     com.nimbusds.jwt.EncryptedJWT encryptedObject,
                                                                     @Nonnull
                                                                     JWKCredential cred)
                                                              throws DecryptionException

If the credential contains algorithm 'alg' information, validate the 'alg' algorithm in the JWT JOSE header matches the algorithm specified for the credential. Then, validates the algorithm in the JWT JOSE Header against the include and exclude algorithm URI lists. Finally, validates the credential contains the correct key type.

Parameters:

encryptedObject - the JWE

cred - the credential to validate against the 'alg' header

Returns:

the validated algorithm to use

Throws:

DecryptionException - if there is an algorithm mismatch.

validateContentEncryptionAlgorithm

@Nonnull
private com.nimbusds.jose.EncryptionMethod validateContentEncryptionAlgorithm(@Nonnull
                                                                              com.nimbusds.jwt.EncryptedJWT encryptedObject)
                                                                       throws DecryptionException

Validates the 'enc' algorithm in the header against the include and exclude algorithm URI lists. If valid, the encryption algorithm from the header is returned. If not valid, an DecryptionException is thrown.

Parameters:

encryptedObject - the JWE

Returns:

the content encryption algorithm from the JOSE header.

Throws:

DecryptionException - if there is an algorithm mismatch.

validateContentEncryptionAlgorithm

@Nonnull
private com.nimbusds.jose.EncryptionMethod validateContentEncryptionAlgorithm(@Nonnull
                                                                              com.nimbusds.jwt.EncryptedJWT encryptedObject,
                                                                              @Nonnull
                                                                              JWKCredential cred)
                                                                       throws DecryptionException

Validates the 'enc' algorithm in the header matches the encryption algorithm specified for the credential, and validates against the include and exclude algorithm URI lists. If valid, the encryption algorithm from the header is returned. If not valid, an DecryptionException is thrown.

Parameters:

encryptedObject - the JWE

cred - the credential to validate the 'enc' header

Returns:

the content encryption algorithm from the JOSE header.

Throws:

DecryptionException - if there is an algorithm mismatch.

validateAlgorithmURI

private void validateAlgorithmURI(@Nonnull
                                  String algorithmURI)
                           throws DecryptionException

Validate the supplied algorithm URI against the configured include and exclude lists.

Parameters:

algorithmURI - the algorithm URI to evaluate

Throws:

DecryptionException - if the algorithm URI does not satisfy the include/exclude policy