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

Class ECDHEncryptionHandler

java.lang.Object

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

All Implemented Interfaces:

EncryptionHandler

public final class ECDHEncryptionHandler
extends Object
implements EncryptionHandler

Implements Elliptic Curve Diffie-Hellman (ECDH) key agreement in ephemeral-static (ECDH-ES) mode. In this mode, the party we are sending data to has a static key pair for which we know (and trust) the public key. We then generate an ephemeral key pair, and perform a ECDH key agreement using our ephemeral private key and the destination's static public key to derive a shared secret. This is then ran through the Concat-KDF key derivation function to derive a symmetric encryption key, which we either use directly or with AES Key Wrapping to encrypt the content of the JWT. We attach our ephemeral public key to the (integrity protected) JWT header and send the result to the other party. They can then perform the same ECDH key agreement using their static private key and the public key from the message to derive the same content encryption (or wrapping) key and decrypt the contents.

Some points to note:

• Static-ephemeral key agreement can be performed "offline" (i.e., without the recipient being actively involved), however it lacks the forward-secrecy of fully ephemeral ECDH: any compromise of the recipient's long-term private key will result in decryption of all previously captured traffic.
• The "static" recipient key does not need to be long-lived, and it is good practice to rotate it frequently and/or use a different public key for each sender (e.g., provide individual JWK URIs for each client).
• In the limit, the "static" key can be generated fresh for every message (using some online protocol), in which case it is effectively equivalent to ephemeral-ephemeral ECDH.
• ECDH does not on its own provide any authentication of either party. If the static public key of the recipient is trusted (e.g., is signed by a trusted CA or received over a trusted channel) then this is sufficient to authenticate the recipient. For the sender, an ephemeral key is used so authentication must be achieved by other means: for example, including a signed hash of the public key in the UPartyInfo/apu claim (signed with a long-term signature key whose public key is known and trusted by the other party). This is an application protocol concern.

This encryption scheme is also generally known as ECIES - Elliptic Curve Integrated Encryption Scheme.

See Also:

NIST SP 800-56A (rev 2) provides detailed recommendations for DH and ECDH protocols.

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, JweHeader header) Decrypts the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.
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, if the EncryptionHandler JweAlgorithm does not required an initialisation vector then the initialisation vector will be an empty octet sequence.
byte[]	generateJWEEncryptedKey(Key key, Key ephemeralKey, JweHeader header) Generates the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.
Key	getContentEncryptionKey() Creates a Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.
static ECDHEncryptionHandler	getInstance(EncryptionHandler keyWrappingHandler, JweAlgorithm algorithm, EncryptionMethod encryptionMethod) Get an instance of the ECDH-ES encryption handler for the given parameters.

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

Method Detail

getInstance

public static ECDHEncryptionHandler getInstance(EncryptionHandler keyWrappingHandler,
                                                JweAlgorithm algorithm,
                                                EncryptionMethod encryptionMethod)

Get an instance of the ECDH-ES encryption handler for the given parameters.

Parameters:

keyWrappingHandler - the underlying key wrapping or direct encryption mode.

algorithm - the overall JWE algorithm to be used. Must be an ECDH-ES type.

encryptionMethod - the content encryption method.

Returns:

a configured ECDH encryption handler.

getContentEncryptionKey

public Key getContentEncryptionKey()

Description copied from interface: EncryptionHandler

Creates a Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.

See points 1, 2, 3 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 ephemeralKey,
                                      JweHeader header)

Description copied from interface: EncryptionHandler

Generates the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.

See points 4, 5, 6 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.

ephemeralKey - The Content Encryption Key (CEK).

header - The JWE header.

Returns:

A byte array of the JWE Encrypted Key.

generateInitialisationVector

public byte[] generateInitialisationVector()

Description copied from interface: EncryptionHandler

Generates a random JWE Initialisation Vector of the correct size for the encryption algorithm, if the EncryptionHandler JweAlgorithm does not required an initialisation vector then the initialisation vector will be an empty octet sequence.

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)

Description copied from interface: EncryptionHandler

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,
                                       JweHeader header)

Description copied from interface: EncryptionHandler

Decrypts the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler JweAlgorithm.

See points 9, 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.

header - The JWE header.

Returns:

The decrypted Content Encryption Key.

decryptCiphertext

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

Description copied from interface: EncryptionHandler

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.