Summary

Introduce exportKey and exportData methods in Cipher to let a pair of encrypting and decrypting ciphers derive shared secrets for additional operations. This will be first used by HPKE.

Problem

HPKE defined a mechanism for exporting keying materials shared between the sender and receiver. This is useful if the application needs extra keys for other cryptographic operations like Mac, token signing, or additional session keys to chain to another protocol. This capability is required by higher-level protocols such as Encrypted ClientHello, and the Messaging Layer Security (MLS) Protocol.

In Java, HPKE is implemented as a Cipher. To support the export function, corresponding methods must be added to the Cipher class.

Solution

Add new exportKey and exportData methods to Cipher that take a context string and expected output length as arguments, returning either a SecretKey or a byte array representing shared secrets. This allows flexibility depending on whether the underlying cipher implementation can safely expose sensitive material. Precisely,

1. If the cipher permits exposing sensitive data, exportData returns a byte array and exportKey returns an extractable key (i.e. its getEncoded method returns a non-null byte array).
2. If the cipher partially allows exposing sensitive data, exportData returns a byte array and exportKey returns an non-extractable key.
3. If the cipher disallows exposing sensitive data, exportData throws UnsupportedOperationException and exportKey returns an non-extractable key.

The policy can vary by context string. For example, a well-known context string used to export an IV (initialization vector) should allow the exported data to be extractable, while another one for a encryption key might not. This is already practiced in PKCS #11 on HKDF Expand.

Corresponding SPI methods, engineExportKey and engineExportData, are added to CipherSpi.

This design is inspired by the TLS Keying Material export function.

Specification

For javax.crypto.Cipher class:

/**
 * Export a derived key based on the current cryptographic state and
 * additional context.
 *
 * <p>This method is designed to enable the generation of additional
 * keys for use in various cryptographic operations, ensuring that key
 * material can be securely derived from the existing encryption or
 * decryption state.
 *
 * <p>This method guarantees that an encryption cipher and a decryption
 * cipher, if initialized with the same symmetric key or a matching
 * asymmetric key pair and equivalent parameters, will produce identical
 * derived keys when the same arguments are provided.
 *
 * @param algorithm the algorithm of the derived key
 * @param context a byte array representing additional data or context
 *          information that influences the key derivation process.
 *          The derived key should be unique to the given context.
 *          A cipher implementation may accept a {@code null} value.
 * @param length the desired length of the derived key in bytes
 *          (must be greater than 0)
 *
 * @return the derived key
 *
 * @throws UnsupportedOperationException if the corresponding method in the
 *          {@code CipherSpi} is not supported
 * @throws IllegalArgumentException if one or more of the input arguments
 *          are invalid
 * @throws IllegalStateException if this {@code Cipher} object is in a wrong
 *          state (e.g., has not been initialized)
 * @throws NullPointerException if {@code algorithm} is {@code null}
 *
 * @since 26
 */
public SecretKey exportKey(String algorithm, byte[] context, int length);

/**
 * Export derived data based on the current cryptographic state and
 * additional context.
 *
 * <p>This method is designed to enable the generation of additional
 * secret data for use in various later operations, ensuring that data
 * can be securely derived from the existing encryption or
 * decryption state.
 *
 * <p>This method guarantees that an encryption cipher and a decryption
 * cipher, if initialized with the same symmetric key or a matching
 * asymmetric key pair and equivalent parameters, will produce identical
 * derived data when the same arguments are provided.
 *
 * @param context a byte array representing additional data or context
 *          information that influences the key derivation process.
 *          The derived key should be unique to the given context.
 *          A cipher implementation may accept a {@code null} value.
 * @param length the desired length of the derived data
 *          (must be greater than 0)
 *
 * @return the derived data
 *
 * @throws UnsupportedOperationException if the corresponding method in the
 *          {@code CipherSpi} is not supported or the derived data is not
 *          extractable
 * @throws IllegalArgumentException if one or more of the input arguments
 *          are invalid
 * @throws IllegalStateException if this {@code Cipher} object is in a wrong
 *          state (e.g., has not been initialized)
 *
 * @since 26
 */
public byte[] exportData(byte[] context, int length);

For javax.crypto.CipherSpi class:

/**
 * Export a derived key based on the current cryptographic state and
 * additional context.
 *
 * <p>This method is designed to enable the generation of additional
 * keys for use in various cryptographic operations, ensuring that key
 * material can be securely derived from the existing encryption or
 * decryption state.
 *
 * <p>This method guarantees that an encryption cipher and a decryption
 * cipher, if initialized with the same symmetric key or a matching
 * asymmetric key pair and equivalent parameters, will produce identical
 * derived keys when the same arguments are provided.
 *
 * @param algorithm the algorithm of the derived key
 * @param context a byte array representing additional data or context
 *          information that influences the key derivation process.
 *          The derived key should be unique to the given context.
 *          A cipher implementation may accept a {@code null} value.
 * @param length the desired length of the derived key in bytes
 *
 * @return the derived key
 *
 * @throws UnsupportedOperationException if this method has not been
 *          overridden by an implementation
 * @throws IllegalArgumentException if one or more of the input arguments
 *          are invalid
 * @throws IllegalStateException if this {@code Cipher} object is in a wrong
 *          state (e.g., has not been initialized)
 *
 * @implSpec The default implementation throws an
 * {@code UnsupportedOperationException}.
 *
 * @since 26
 */
protected SecretKey engineExportKey(String algorithm, byte[] context, int length);

/**
 * Export derived data based on the current cryptographic state and
 * additional context.
 *
 * <p>This method is designed to enable the generation of additional
 * secret data for use in various later operations, ensuring that data
 * can be securely derived from the existing encryption or
 * decryption state.
 *
 * <p>This method guarantees that an encryption cipher and a decryption
 * cipher, if initialized with the same symmetric key or a matching
 * asymmetric key pair and equivalent parameters, will produce identical
 * derived data when the same arguments are provided.
 *
 * @param context a byte array representing additional data or context
 *          information that influences the key derivation process.
 *          The derived key should be unique to the given context.
 *          A cipher implementation may accept a {@code null} value.
 * @param length the desired length of the derived data
 *
 * @return the derived data
 *
 * @throws UnsupportedOperationException if this method has not been
 *          overridden by an implementation or the derived data is not
 *          extractable

 * @throws IllegalArgumentException if one or more of the input arguments
 *          are invalid
 * @throws IllegalStateException if this {@code Cipher} object is in a wrong
 *          state (e.g., has not been initialized)
 *
 * @implSpec The default implementation throws an
 * {@code UnsupportedOperationException}.
 *
 * @since 26
 */
protected byte[] engineExportData(byte[] context, int length);