OpenJDK 27 · javax.crypto.spec.HPKEParameterSpec · APIdia, the JavaDoc alternative

This immutable class specifies the set of parameters used with a Cipher for the Hybrid Public Key Encryption (HPKE) algorithm. HPKE is a public key encryption scheme for encrypting arbitrary-sized plaintexts with a recipient's public key. It combines a key encapsulation mechanism (KEM), a key derivation function (KDF), and an authenticated encryption with additional data (AEAD) cipher.

The standard algorithm name for the cipher is "HPKE". Unlike most other ciphers, HPKE is not expressed as a transformation string of the form "algorithm/mode/padding". Therefore, the argument to Cipher.getInstance must be the single algorithm name "HPKE".

In HPKE, the sender's Cipher is always initialized with the recipient's public key in encrypt mode, while the recipient's Cipher object is initialized with its own private key in decrypt mode.

An HPKEParameterSpec object must be provided at HPKE cipher initialization.

The of(int, int, int) static method returns an HPKEParameterSpec object with the specified KEM, KDF, and AEAD algorithm identifiers. The terms "KEM algorithm identifiers", "KDF algorithm identifiers", and "AEAD algorithm identifiers" refer to their respective numeric values (specifically, kem_id, kdf_id, and aead_id) as defined in Section 7 of RFC 9180 and maintained on the IANA HPKE page.

Once an HPKEParameterSpec object is created, additional methods are available to generate new HPKEParameterSpec objects with different features:

Application-supplied information can be provided using the withInfo(byte[]) method by both sides.
To authenticate using a pre-shared key (mode_psk), the pre-shared key and its identifier must be provided using the withPsk(SecretKey, byte[]) method by both sides.
To authenticate using an asymmetric key (mode_auth), the asymmetric keys must be provided using the withAuthKey(AsymmetricKey) method. Precisely, the sender must call this method with its own private key and the recipient must call it with the sender's public key.
To authenticate using both a PSK and an asymmetric key (mode_auth_psk), both withAuthKey(AsymmetricKey) and withPsk(SecretKey, byte[]) methods must be called as described above.
In HPKE, a shared secret is negotiated during the KEM step and a key encapsulation message must be transmitted from the sender to the recipient so that the recipient can recover the shared secret. On the sender side, after the cipher is initialized, the key encapsulation message can be retrieved using the Cipher#getIV() method. On the recipient side, this message must be supplied as part of an HPKEParameterSpec object obtained from the withEncapsulation(byte[]) method.

For successful interoperability, both sides need to have identical algorithm identifiers, and supply identical info, psk, and psk_id or matching authentication keys if provided. For details about HPKE modes, refer to Section 5 of RFC 9180.

If an HPKE cipher is initialized without parameters, an InvalidKeyException is thrown.

At HPKE cipher initialization, if no HPKE implementation supports the provided key type, an InvalidKeyException is thrown. If the provided HPKEParameterSpec is not accepted by any HPKE implementation, an InvalidAlgorithmParameterException is thrown. For example:

An algorithm identifier is unsupported or does not match the provided key type.
A key encapsulation message is provided on the sender side.
A key encapsulation message is not provided on the recipient side.
An attempt to use withAuthKey(key) is made with an incompatible key.
An attempt to use withAuthKey(key) is made but mode_auth or mode_auth_psk is not supported by the KEM algorithm used.

After initialization, both the sender and recipient can process multiple messages in sequence with repeated doFinal calls, optionally preceded by one or more updateAAD and update. Each doFinal performs a complete HPKE encryption or decryption operation using a distinct IV derived from an internal sequence counter, as specified in Section 5.2 of RFC 9180. On the recipient side, each doFinal call must correspond to exactly one complete ciphertext, and the number and order of calls must match those on the sender side. This differs from the direct use of an AEAD cipher, where the caller must provide a fresh IV and reinitialize the cipher for each message. By managing IVs internally, HPKE allows a single initialization to support multiple messages while still ensuring IV uniqueness and preserving AEAD security guarantees.

This example shows a sender and a recipient using HPKE to securely exchange messages with an X25519 key pair.

// Recipient key pair generation
KeyPairGenerator g = KeyPairGenerator.getInstance("X25519");
KeyPair kp = g.generateKeyPair();

// The HPKE sender cipher is initialized with the recipient's public
// key and an HPKEParameterSpec using specified algorithm identifiers
// and application-supplied info.
Cipher senderCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec ps = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"));
senderCipher.init(Cipher.ENCRYPT_MODE, kp.getPublic(), ps);

// Retrieve the key encapsulation message (from the KEM step) from
// the sender.
byte[] kemEncap = senderCipher.getIV();

// The HPKE recipient cipher is initialized with its own private key,
// an HPKEParameterSpec using the same algorithm identifiers as used by
// the sender, and the key encapsulation message from the sender.
Cipher recipientCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec pr = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"))
        .withEncapsulation(kemEncap);
recipientCipher.init(Cipher.DECRYPT_MODE, kp.getPrivate(), pr);

// Encryption and decryption
byte[] msg = "Hello World".getBytes(StandardCharsets.UTF_8);
byte[] ct = senderCipher.doFinal(msg);
byte[] pt = recipientCipher.doFinal(ct);

assert Arrays.equals(msg, pt);

Field Summary

Modifier and Type	Field and Description
public static final int	AEAD_AES_128_GCM AEAD algorithm identifier for AES-128-GCM as defined in RFC 9180.
public static final int	AEAD_AES_256_GCM AEAD algorithm identifier for AES-256-GCM as defined in RFC 9180.
public static final int	AEAD_CHACHA20_POLY1305 AEAD algorithm identifier for ChaCha20Poly1305 as defined in RFC 9180.
private final int	aead_id
private final byte[]	encapsulation
public static final int	EXPORT_ONLY AEAD algorithm identifier for Export-only as defined in RFC 9180.
private final byte[]	info
public static final int	KDF_HKDF_SHA256 KDF algorithm identifier for HKDF-SHA256 as defined in RFC 9180.
public static final int	KDF_HKDF_SHA384 KDF algorithm identifier for HKDF-SHA384 as defined in RFC 9180.
public static final int	KDF_HKDF_SHA512 KDF algorithm identifier for HKDF-SHA512 as defined in RFC 9180.
private final int	kdf_id
public static final int	KEM_DHKEM_P_256_HKDF_SHA256 KEM algorithm identifier for DHKEM(P-256, HKDF-SHA256) as defined in RFC 9180.
public static final int	KEM_DHKEM_P_384_HKDF_SHA384 KEM algorithm identifier for DHKEM(P-384, HKDF-SHA384) as defined in RFC 9180.
public static final int	KEM_DHKEM_P_521_HKDF_SHA512 KEM algorithm identifier for DHKEM(P-521, HKDF-SHA512) as defined in RFC 9180.
public static final int	KEM_DHKEM_X25519_HKDF_SHA256 KEM algorithm identifier for DHKEM(X25519, HKDF-SHA256) as defined in RFC 9180.
public static final int	KEM_DHKEM_X448_HKDF_SHA512 KEM algorithm identifier for DHKEM(X448, HKDF-SHA512) as defined in RFC 9180.
private final int	kem_id
private final AsymmetricKey	kS
private final SecretKey	psk
private final byte[]	psk_id

Access	Constructor and Description
private	HPKEParameterSpec(int kem_id, int kdf_id, int aead_id, byte[] info, SecretKey psk, byte[] psk_id, AsymmetricKey kS, byte[] encapsulation)

Method Summary

Modifier and Type	Method and Description
public int	Returns: the algorithm identifier for AEAD aead_id() Returns the algorithm identifier for AEAD.
public AsymmetricKey	Returns: the key for authentication, `null` if none authKey() Returns the key for authentication, `null` if none.
private static String	bytesToString(byte[] input)
public byte[]	Returns: a copy of the key encapsulation message, `null` if none encapsulation() Returns a copy of the key encapsulation message, `null` if none.
public byte[]	Returns: a copy of the application-supplied information, empty if none info() Returns a copy of the application-supplied information, empty if none.
public int	Returns: the algorithm identifier for KDF kdf_id() Returns the algorithm identifier for KDF.
public int	Returns: the algorithm identifier for KEM kem_id() Returns the algorithm identifier for KEM.
public static HPKEParameterSpec	Returns: a new `HPKEParameterSpec` object of(int algorithm identifier for KEM, must be between 0 and 65535 (inclusive) kem_id, int algorithm identifier for KDF, must be between 0 and 65535 (inclusive) kdf_id, int algorithm identifier for AEAD, must be between 0 and 65535 (inclusive) aead_id) A factory method to create a new `HPKEParameterSpec` object with specified KEM, KDF, and AEAD algorithm identifiers in `mode_base` mode with an empty `info`.
public SecretKey	Returns: pre-shared key, `null` if none psk() Returns pre-shared key, `null` if none.
public byte[]	Returns: a copy of the identifier for PSK, empty if none psk_id() Returns a copy of the identifier for PSK, empty if none.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public HPKEParameterSpec	Returns: a new `HPKEParameterSpec` object withAuthKey(AsymmetricKey the authentication key kS) Creates a new `HPKEParameterSpec` object with the specified authentication key value.
public HPKEParameterSpec	Returns: a new `HPKEParameterSpec` object withEncapsulation(byte[] the key encapsulation message. The contents of the array are copied to protect against subsequent modification. encapsulation) Creates a new `HPKEParameterSpec` object with the specified key encapsulation message value that will be used by the recipient.
public HPKEParameterSpec	Returns: a new `HPKEParameterSpec` object withInfo(byte[] application-supplied information. The contents of the array are copied to protect against subsequent modification. info) Creates a new `HPKEParameterSpec` object with the specified `info` value.
public HPKEParameterSpec	Returns: a new `HPKEParameterSpec` object withPsk(SecretKey pre-shared key psk, byte[] identifier for PSK. The contents of the array are copied to protect against subsequent modification. psk_id) Creates a new `HPKEParameterSpec` object with the specified `psk` and `psk_id` values.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

AEAD_AES_128_GCM	back to summary
public static final int AEAD_AES_128_GCM AEAD algorithm identifier for AES-128-GCM as defined in RFC 9180.

AEAD_AES_256_GCM	back to summary
public static final int AEAD_AES_256_GCM AEAD algorithm identifier for AES-256-GCM as defined in RFC 9180.

AEAD_CHACHA20_POLY1305	back to summary
public static final int AEAD_CHACHA20_POLY1305 AEAD algorithm identifier for ChaCha20Poly1305 as defined in RFC 9180.

aead_id	back to summary
private final int aead_id

encapsulation	back to summary
private final byte[] encapsulation

EXPORT_ONLY	back to summary
public static final int EXPORT_ONLY AEAD algorithm identifier for Export-only as defined in RFC 9180.

info	back to summary
private final byte[] info

KDF_HKDF_SHA256	back to summary
public static final int KDF_HKDF_SHA256 KDF algorithm identifier for HKDF-SHA256 as defined in RFC 9180.

KDF_HKDF_SHA384	back to summary
public static final int KDF_HKDF_SHA384 KDF algorithm identifier for HKDF-SHA384 as defined in RFC 9180.

KDF_HKDF_SHA512	back to summary
public static final int KDF_HKDF_SHA512 KDF algorithm identifier for HKDF-SHA512 as defined in RFC 9180.

kdf_id	back to summary
private final int kdf_id

KEM_DHKEM_P_256_HKDF_SHA256	back to summary
public static final int KEM_DHKEM_P_256_HKDF_SHA256 KEM algorithm identifier for DHKEM(P-256, HKDF-SHA256) as defined in RFC 9180.

KEM_DHKEM_P_384_HKDF_SHA384	back to summary
public static final int KEM_DHKEM_P_384_HKDF_SHA384 KEM algorithm identifier for DHKEM(P-384, HKDF-SHA384) as defined in RFC 9180.

KEM_DHKEM_P_521_HKDF_SHA512	back to summary
public static final int KEM_DHKEM_P_521_HKDF_SHA512 KEM algorithm identifier for DHKEM(P-521, HKDF-SHA512) as defined in RFC 9180.

KEM_DHKEM_X25519_HKDF_SHA256	back to summary
public static final int KEM_DHKEM_X25519_HKDF_SHA256 KEM algorithm identifier for DHKEM(X25519, HKDF-SHA256) as defined in RFC 9180.

KEM_DHKEM_X448_HKDF_SHA512	back to summary
public static final int KEM_DHKEM_X448_HKDF_SHA512 KEM algorithm identifier for DHKEM(X448, HKDF-SHA512) as defined in RFC 9180.

kem_id	back to summary
private final int kem_id

kS	back to summary
private final AsymmetricKey kS

psk	back to summary
private final SecretKey psk

psk_id	back to summary
private final byte[] psk_id

HPKEParameterSpec	back to summary
private HPKEParameterSpec(int kem_id, int kdf_id, int aead_id, byte[] info, SecretKey psk, byte[] psk_id, AsymmetricKey kS, byte[] encapsulation)

Method Detail

aead_id	back to summary
public int aead_id() Returns the algorithm identifier for AEAD. Returns:int the algorithm identifier for AEAD

aead_id

back to summary

public int aead_id()

Returns the algorithm identifier for AEAD.

Returns:int: the algorithm identifier for AEAD

authKey back to summary

authKey	back to summary
public AsymmetricKey authKey() Returns the key for authentication, `null` if none. Returns:AsymmetricKey the key for authentication, `null` if none

public AsymmetricKey authKey()

Returns the key for authentication, null if none.

Returns:AsymmetricKey: the key for authentication, null if none

bytesToString	back to summary
private static String bytesToString(byte[] input)

encapsulation back to summary

encapsulation	back to summary
public byte[] encapsulation() Returns a copy of the key encapsulation message, `null` if none. Returns:byte[] a copy of the key encapsulation message, `null` if none

public byte[] encapsulation()

Returns a copy of the key encapsulation message, null if none.

Returns:byte[]: a copy of the key encapsulation message, null if none

info	back to summary
public byte[] info() Returns a copy of the application-supplied information, empty if none. Returns:byte[] a copy of the application-supplied information, empty if none

info

back to summary

public byte[] info()

Returns a copy of the application-supplied information, empty if none.

Returns:byte[]: a copy of the application-supplied information, empty if none

kdf_id	back to summary
public int kdf_id() Returns the algorithm identifier for KDF. Returns:int the algorithm identifier for KDF

kdf_id

back to summary

public int kdf_id()

Returns the algorithm identifier for KDF.

Returns:int: the algorithm identifier for KDF

kem_id	back to summary
public int kem_id() Returns the algorithm identifier for KEM. Returns:int the algorithm identifier for KEM

kem_id

back to summary

public int kem_id()

Returns the algorithm identifier for KEM.

Returns:int: the algorithm identifier for KEM

of back to summary

of	back to summary
public static HPKEParameterSpec of(int kem_id, int kdf_id, int aead_id) A factory method to create a new `HPKEParameterSpec` object with specified KEM, KDF, and AEAD algorithm identifiers in `mode_base` mode with an empty `info`. Parameters kem_id:int algorithm identifier for KEM, must be between 0 and 65535 (inclusive) kdf_id:int algorithm identifier for KDF, must be between 0 and 65535 (inclusive) aead_id:int algorithm identifier for AEAD, must be between 0 and 65535 (inclusive) Returns:HPKEParameterSpec a new `HPKEParameterSpec` object Exceptions IllegalArgumentException: if any input value is out of range (must be between 0 and 65535, inclusive).

public static HPKEParameterSpec of(int kem_id, int kdf_id, int aead_id)

A factory method to create a new HPKEParameterSpec object with specified KEM, KDF, and AEAD algorithm identifiers in mode_base mode with an empty info.

Parameters

kem_id:int: algorithm identifier for KEM, must be between 0 and 65535 (inclusive)
kdf_id:int: algorithm identifier for KDF, must be between 0 and 65535 (inclusive)
aead_id:int: algorithm identifier for AEAD, must be between 0 and 65535 (inclusive)

Returns:HPKEParameterSpec

a new HPKEParameterSpec object

Exceptions

IllegalArgumentException:: if any input value is out of range (must be between 0 and 65535, inclusive).

psk back to summary

psk	back to summary
public SecretKey psk() Returns pre-shared key, `null` if none. Returns:SecretKey pre-shared key, `null` if none

public SecretKey psk()

Returns pre-shared key, null if none.

Returns:SecretKey: pre-shared key, null if none

psk_id	back to summary
public byte[] psk_id() Returns a copy of the identifier for PSK, empty if none. Returns:byte[] a copy of the identifier for PSK, empty if none

psk_id

back to summary

public byte[] psk_id()

Returns a copy of the identifier for PSK, empty if none.

Returns:byte[]: a copy of the identifier for PSK, empty if none

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations

@Override

withAuthKey back to summary

withAuthKey	back to summary
public HPKEParameterSpec withAuthKey(AsymmetricKey kS) Creates a new `HPKEParameterSpec` object with the specified authentication key value. Note this method does not check whether the KEM algorithm supports `mode_auth` or `mode_auth_psk`. If the resulting object is used to initialize an HPKE cipher with an unsupported mode, an `InvalidAlgorithmParameterException` will be thrown at that time. Parameters kS:AsymmetricKey the authentication key Returns:HPKEParameterSpec a new `HPKEParameterSpec` object Exceptions NullPointerException: if `kS` is `null`

public HPKEParameterSpec withAuthKey(AsymmetricKey kS)

Creates a new HPKEParameterSpec object with the specified authentication key value.

Note

this method does not check whether the KEM algorithm supports mode_auth or mode_auth_psk. If the resulting object is used to initialize an HPKE cipher with an unsupported mode, an InvalidAlgorithmParameterException will be thrown at that time.

Parameters

kS:AsymmetricKey: the authentication key

Returns:HPKEParameterSpec

a new HPKEParameterSpec object

Exceptions

NullPointerException:: if kS is null

withEncapsulation back to summary

withEncapsulation	back to summary
public HPKEParameterSpec withEncapsulation(byte[] encapsulation) Creates a new `HPKEParameterSpec` object with the specified key encapsulation message value that will be used by the recipient. Parameters encapsulation:byte[] the key encapsulation message. The contents of the array are copied to protect against subsequent modification. Returns:HPKEParameterSpec a new `HPKEParameterSpec` object Exceptions NullPointerException: if `encapsulation` is `null`

public HPKEParameterSpec withEncapsulation(byte[] encapsulation)

Creates a new HPKEParameterSpec object with the specified key encapsulation message value that will be used by the recipient.

Parameters

encapsulation:byte[]: the key encapsulation message. The contents of the array are copied to protect against subsequent modification.

Returns:HPKEParameterSpec

a new HPKEParameterSpec object

Exceptions

NullPointerException:: if encapsulation is null

withInfo back to summary

withInfo	back to summary
public HPKEParameterSpec withInfo(byte[] info) Creates a new `HPKEParameterSpec` object with the specified `info` value. For interoperability, RFC 9180 Section 7.2.1 recommends limiting this value to a maximum of 64 bytes. Parameters info:byte[] application-supplied information. The contents of the array are copied to protect against subsequent modification. Returns:HPKEParameterSpec a new `HPKEParameterSpec` object Exceptions NullPointerException: if `info` is `null` IllegalArgumentException: if `info` is empty.

public HPKEParameterSpec withInfo(byte[] info)

Creates a new HPKEParameterSpec object with the specified info value.

For interoperability, RFC 9180 Section 7.2.1 recommends limiting this value to a maximum of 64 bytes.

Parameters

info:byte[]: application-supplied information. The contents of the array are copied to protect against subsequent modification.

Returns:HPKEParameterSpec

a new HPKEParameterSpec object

Exceptions

NullPointerException:: if info is null
IllegalArgumentException:: if info is empty.

withPsk back to summary

withPsk	back to summary
public HPKEParameterSpec withPsk(SecretKey psk, byte[] psk_id) Creates a new `HPKEParameterSpec` object with the specified `psk` and `psk_id` values. RFC 9180 Section 5.1.2 requires the PSK MUST have at least 32 bytes of entropy. For interoperability, RFC 9180 Section 7.2.1 recommends limiting the key size and identifier length to a maximum of 64 bytes. Parameters psk:SecretKey pre-shared key psk_id:byte[] identifier for PSK. The contents of the array are copied to protect against subsequent modification. Returns:HPKEParameterSpec a new `HPKEParameterSpec` object Exceptions NullPointerException: if `psk` or `psk_id` is `null` IllegalArgumentException: if `psk` is shorter than 32 bytes or `psk_id` is empty

public HPKEParameterSpec withPsk(SecretKey psk, byte[] psk_id)

Creates a new HPKEParameterSpec object with the specified psk and psk_id values.

RFC 9180 Section 5.1.2 requires the PSK MUST have at least 32 bytes of entropy. For interoperability, RFC 9180 Section 7.2.1 recommends limiting the key size and identifier length to a maximum of 64 bytes.

Parameters

psk:SecretKey: pre-shared key
psk_id:byte[]: identifier for PSK. The contents of the array are copied to protect against subsequent modification.

Returns:HPKEParameterSpec

a new HPKEParameterSpec object

Exceptions

NullPointerException:: if psk or psk_id is null
IllegalArgumentException:: if psk is shorter than 32 bytes or psk_id is empty

public final Class HPKEParameterSpec

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail