org.forgerock.json.jose.jwe.handlers.encryption

Class RSAEncryptionHandler

java.lang.Object

org.forgerock.json.jose.jwe.handlers.encryption.RSAEncryptionHandler

All Implemented Interfaces:

EncryptionHandler

public final class RSAEncryptionHandler
extends Object
implements EncryptionHandler

Abstract base class for implementations of the RSAES-PKCS1-v1_5 and RSA-OAEP encryption schemes.

See Also:

RFC 7518 Section 4.2 and 4.3

Field Summary

Fields

Modifier and Type	Field and Description
static Option<Boolean>	USE_WRAP_UNWRAP_OPERATIONS Indicates whether the handler should use Cipher.wrap(Key) and Cipher.unwrap(byte[], String, int) operations or normal encrypt/decrypt operations for encrypting the per-message symmetric AES key.

Constructor Summary

Constructors

Constructor and Description
RSAEncryptionHandler(EncryptionMethod encryptionMethod, JweAlgorithm jweAlgorithm) Constructs a new RSAEncryptionHandler instance.
RSAEncryptionHandler(EncryptionMethod encryptionMethod, JweAlgorithm jweAlgorithm, Options options) Constructs a new RSAEncryptionHandler instance with the given options.

Method Summary

Modifier and Type	Method and Description
byte[]	decryptCiphertext(Key contentEncryptionKey, byte[] initialisationVector, byte[] ciphertext, byte[] authenticationTag, byte[] additionalAuthenticatedData) Decrypts the ciphertext with the Content Encryption Key, using the initialisation vector and additional authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.
Key	decryptContentEncryptionKey(Key key, byte[] encryptedContentEncryptionKey) Decrypts the JWE Encrypted Key to produce the Content Encryption Key (CEK).
JweEncryption	encryptPlaintext(Key contentEncryptionKey, byte[] initialisationVector, byte[] plaintext, byte[] additionalAuthenticatedData) Encrypts the plaintext with the Content Encryption Key, using the initialisation vector and additional authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.
byte[]	generateInitialisationVector() Generates a random JWE Initialisation Vector of the correct size for the encryption algorithm.
byte[]	generateJWEEncryptedKey(Key key, Key contentEncryptionKey) Generates the JWE Encrypted Key by encrypting the Content Encryption Key (CEK) using the JweAlgorithm RSAES_PCKCS1_V1_5.
Key	getContentEncryptionKey() Creates a Content Encryption Key (CEK) by generating a random key value with a length equal to the EncryptionMethod A128CBC_HS256 key size.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.forgerock.json.jose.jwe.handlers.encryption.EncryptionHandler

decryptContentEncryptionKey, generateJWEEncryptedKey

Field Detail

USE_WRAP_UNWRAP_OPERATIONS

public static final Option<Boolean> USE_WRAP_UNWRAP_OPERATIONS

Indicates whether the handler should use Cipher.wrap(Key) and Cipher.unwrap(byte[], String, int) operations or normal encrypt/decrypt operations for encrypting the per-message symmetric AES key. This distinction only matters when using a PKCS#11 Hardware Security Module, in which case the unwrap operation will install the AES key on the HSM. This may cause problems if the key is marked as unextractable as some of the JWE EncryptionMethods (e.g. EncryptionMethod.A128CBC_HS256 and related methods) need to access the raw bytes of the key. The default is specified by the system property org.forgerock.jwe.rsa.use_wrap_unwrap, or false if not specified.

Constructor Detail

RSAEncryptionHandler

public RSAEncryptionHandler(EncryptionMethod encryptionMethod,
                            JweAlgorithm jweAlgorithm)

Constructs a new RSAEncryptionHandler instance. This constructor will read the system property org.forgerock.jwe.rsa.use_wrap_unwrap to determine whether to use wrap/unwrap operations or normal encrypt/decrypt operations for encrypting and decrypting the AES message key. Use RSAEncryptionHandler(EncryptionMethod, JweAlgorithm, Options) to manually specify this option.

Parameters:

encryptionMethod - the content encryption method. Must not be null.

jweAlgorithm - the JWE algorithm. Must not be null. Must be an RSA encryption algorithm.

RSAEncryptionHandler

public RSAEncryptionHandler(EncryptionMethod encryptionMethod,
                            JweAlgorithm jweAlgorithm,
                            Options options)

Constructs a new RSAEncryptionHandler instance with the given options. The allowed options are:

• USE_WRAP_UNWRAP_OPERATIONS

Parameters:

encryptionMethod - the content encryption method. Must not be null.

jweAlgorithm - the JWE algorithm. Must not be null. Must be an RSA encryption algorithm.

options - the options. Must not be null. See above for allowed options.

Method Detail

getContentEncryptionKey

public Key getContentEncryptionKey()

Creates a Content Encryption Key (CEK) by generating a random key value with a length equal to the EncryptionMethod A128CBC_HS256 key size.

See point 2 in Section 5.1 of the JWE Specification.

Specified by:

getContentEncryptionKey in interface EncryptionHandler

Returns:

The Content Encryption Key or null if the shared key should be used directly.

generateJWEEncryptedKey

public byte[] generateJWEEncryptedKey(Key key,
                                      Key contentEncryptionKey)

Generates the JWE Encrypted Key by encrypting the Content Encryption Key (CEK) using the JweAlgorithm RSAES_PCKCS1_V1_5.

See point 4 in Section 5.1 of the JWE Specification.

Specified by:

generateJWEEncryptedKey in interface EncryptionHandler

Parameters:

key - The key to use to encrypt the Content Encryption Key, if the EncryptionHandler JweAlgorithm requires.

contentEncryptionKey - The Content Encryption Key (CEK).

Returns:

A byte array of the JWE Encrypted Key.

generateInitialisationVector

public byte[] generateInitialisationVector()

Generates a random JWE Initialisation Vector of the correct size for the encryption algorithm.

See points 9 in Section 5.1 of the JWE Specification.

Specified by:

generateInitialisationVector in interface EncryptionHandler

Returns:

The Initialisation Vector.

encryptPlaintext

public JweEncryption encryptPlaintext(Key contentEncryptionKey,
                                      byte[] initialisationVector,
                                      byte[] plaintext,
                                      byte[] additionalAuthenticatedData)

Encrypts the plaintext with the Content Encryption Key, using the initialisation vector and additional authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.

See points 15, 16 in Section 5.1 of the JWE Specification.

Specified by:

encryptPlaintext in interface EncryptionHandler

Parameters:

contentEncryptionKey - The Content Encryption Key.

initialisationVector - The Initialisation Vector.

plaintext - The plaintext to encrypt.

additionalAuthenticatedData - An array of bytes representing the additional authenticated data.

Returns:

The JweEncryption object containing the ciphertext and authentication tag.

decryptContentEncryptionKey

public Key decryptContentEncryptionKey(Key key,
                                       byte[] encryptedContentEncryptionKey)

Decrypts the JWE Encrypted Key to produce the Content Encryption Key (CEK).

See points 10 in Section 5.2 of the JWE Specification.

Specified by:

decryptContentEncryptionKey in interface EncryptionHandler

Parameters:

key - The private key pair to the public key that encrypted the JWT.

encryptedContentEncryptionKey - The encrypted Content Encryption Key.

Returns:

The decrypted Content Encryption Key.

decryptCiphertext

public byte[] decryptCiphertext(Key contentEncryptionKey,
                                byte[] initialisationVector,
                                byte[] ciphertext,
                                byte[] authenticationTag,
                                byte[] additionalAuthenticatedData)

Decrypts the ciphertext with the Content Encryption Key, using the initialisation vector and additional authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.

See points 14, 15 in Section 5.2 of the JWE Specification.

Specified by:

decryptCiphertext in interface EncryptionHandler

Parameters:

contentEncryptionKey - The Content Encryption Key.

initialisationVector - The Initialisation Vector.

ciphertext - The ciphertext to decrypt.

authenticationTag - The authentication tag.

additionalAuthenticatedData - An array of bytes representing the additional authenticated data.

Returns:

An array of bytes representing the decrypted ciphertext.