Package 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:

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • 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.