Interface HpkeSpi

All Known Implementing Classes:

DuckTypedHpkeSpi, HpkeImpl, HpkeImpl.HpkeMlKemImpl, HpkeImpl.HpkeX25519Impl, HpkeImpl.HpkeXwingImpl, HpkeImpl.MlKem1024HkdfSha256Aes128Gcm, HpkeImpl.MlKem1024HkdfSha256Aes256Gcm, HpkeImpl.MlKem1024HkdfSha256ChaCha20Poly1305, HpkeImpl.MlKem768HkdfSha256Aes128Gcm, HpkeImpl.MlKem768HkdfSha256Aes256Gcm, HpkeImpl.MlKem768HkdfSha256ChaCha20Poly1305, HpkeImpl.X25519_AES_128, HpkeImpl.X25519_AES_256, HpkeImpl.X25519_CHACHA20, HpkeImpl.XwingHkdfSha256Aes128Gcm, HpkeImpl.XwingHkdfSha256Aes256Gcm, HpkeImpl.XwingHkdfSha256ChaCha20Poly1305

public interface HpkeSpi

SPI for HPKE clients to communicate with implementations. The client API can use any implementation which implements this interface, by duck-typing if necessary.

Field Summary

Fields

Modifier and Type	Field	Description
static final byte[]	DEFAULT_PSK
static final byte[]	DEFAULT_PSK_ID

Method Summary

Modifier and Type	Method	Description
byte[]	engineExport(int length, byte[] context)	Exports secret key material from this SPI as described in RFC 9180.
void	engineInitRecipient(byte[] encapsulated, PrivateKey recipientKey, byte[] info, PublicKey senderKey, byte[] psk, byte[] psk_id)	Initialises an HPKE recipient SPI.
void	engineInitSender(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id)	Initialises an HPKE sender SPI.
void	engineInitSenderForTesting(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id, byte[] sKe)	Initialises an HPKE sender SPI.
byte[]	engineOpen(byte[] ciphertext, byte[] aad)	Opens a message, using the internal key schedule maintained by an HPKE recipient.
byte[]	engineSeal(byte[] plaintext, byte[] aad)	Seals a message, using the internal key schedule maintained by an HPKE sender.
byte[]	getEncapsulated()	Returns the encapsulated key material for an HPKE sender.

Field Details

DEFAULT_PSK

static final byte[] DEFAULT_PSK

DEFAULT_PSK_ID

static final byte[] DEFAULT_PSK_ID

Method Details

engineInitSender

void engineInitSender(PublicKey recipientKey,
 byte[] info,
 PrivateKey senderKey,
 byte[] psk,
 byte[] psk_id)
               throws InvalidKeyException

Initialises an HPKE sender SPI.

Parameters:

recipientKey - public key of the recipient

info - application-supplied information, may be null or empty

senderKey - private key of the sender, for symmetric auth modes only, else null

psk - pre-shared key, for PSK auth modes only, else null

psk_id - pre-shared key ID, for PSK auth modes only, else null

Throws:

InvalidKeyException - if recipientKey is null or an unsupported key format

UnsupportedOperationException - if mode is not a supported HPKE mode

IllegalStateException - if this SPI has already been initialised

engineInitSenderForTesting

void engineInitSenderForTesting(PublicKey recipientKey,
 byte[] info,
 PrivateKey senderKey,
 byte[] psk,
 byte[] psk_id,
 byte[] sKe)
                         throws InvalidKeyException

Initialises an HPKE sender SPI.

Parameters:

recipientKey - public key of the recipient

info - application-supplied information, may be null or empty

senderKey - private key of the sender, for symmetric auth modes only, else null

psk - pre-shared key, for PSK auth modes only, else null

psk_id - pre-shared key ID, for PSK auth modes only, else null

sKe - optional random seed, should be null for all uses except for validation against known test vectors

Throws:

InvalidKeyException - if recipientKey is null or an unsupported key format or senderKey is an unsupported key format

UnsupportedOperationException - if mode is not a supported HPKE mode

IllegalStateException - if this SPI has already been initialised

engineInitRecipient

void engineInitRecipient(byte[] encapsulated,
 PrivateKey recipientKey,
 byte[] info,
 PublicKey senderKey,
 byte[] psk,
 byte[] psk_id)
                  throws InvalidKeyException

Initialises an HPKE recipient SPI.

Parameters:

encapsulated - encapsulated ephemeral key from a sender

recipientKey - private key of the recipient

info - application-supplied information, may be null or empty

senderKey - public key of sender, for asymmetric auth modes only, else null

psk - pre-shared key, for PSK auth modes only, else null

psk_id - pre-shared key ID, for PSK auth modes only, else null

Throws:

InvalidKeyException - if recipientKey is null or an unsupported key format or senderKey is an unsupported key format

UnsupportedOperationException - if mode is not a supported HPKE mode

IllegalStateException - if this SPI has already been initialised

engineSeal

byte[] engineSeal(byte[] plaintext,
 byte[] aad)

Seals a message, using the internal key schedule maintained by an HPKE sender.

Parameters:

plaintext - the plaintext

aad - optional associated data, may be null or empty

Returns:

the ciphertext

Throws:

NullPointerException - if the plaintext is null

IllegalStateException - if this SPI has not been initialised or if it was initialised as a recipient

engineOpen

byte[] engineOpen(byte[] ciphertext,
 byte[] aad)
           throws GeneralSecurityException

Opens a message, using the internal key schedule maintained by an HPKE recipient.

Parameters:

ciphertext - the ciphertext

aad - optional associated data, may be null or empty

Returns:

the plaintext

Throws:

IllegalStateException - if this SPI has not been initialised or if it was initialised as a sender

GeneralSecurityException - on decryption failures

engineExport

byte[] engineExport(int length,
 byte[] context)

Exports secret key material from this SPI as described in RFC 9180.

Parameters:

length - expected output length

context - optional context string, may be null or empty

Returns:

exported value

Throws:

IllegalArgumentException - if the length is not valid for the KDF in use

IllegalStateException - if this SPI has not been initialised

getEncapsulated

byte[] getEncapsulated()

Returns the encapsulated key material for an HPKE sender.

Returns:

the key material

Throws:

IllegalStateException - if this SPI has not been initialised or if it was initialised as a recipient