Package org.conscrypt

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 byte[]	DEFAULT_PSK
static 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, java.security.PrivateKey recipientKey, byte[] info, java.security.PublicKey senderKey, byte[] psk, byte[] psk_id)	Initialises an HPKE recipient SPI.
void	engineInitSender(java.security.PublicKey recipientKey, byte[] info, java.security.PrivateKey senderKey, byte[] psk, byte[] psk_id)	Initialises an HPKE sender SPI.
void	engineInitSenderForTesting(java.security.PublicKey recipientKey, byte[] info, java.security.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 Detail

DEFAULT_PSK

static final byte[] DEFAULT_PSK

DEFAULT_PSK_ID

static final byte[] DEFAULT_PSK_ID

Method Detail

engineInitSender

void engineInitSender(java.security.PublicKey recipientKey,
                      byte[] info,
                      java.security.PrivateKey senderKey,
                      byte[] psk,
                      byte[] psk_id)
               throws java.security.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:

java.security.InvalidKeyException - if recipientKey is null or an unsupported key format

java.lang.UnsupportedOperationException - if mode is not a supported HPKE mode

java.lang.IllegalStateException - if this SPI has already been initialised

engineInitSenderForTesting

void engineInitSenderForTesting(java.security.PublicKey recipientKey,
                                byte[] info,
                                java.security.PrivateKey senderKey,
                                byte[] psk,
                                byte[] psk_id,
                                byte[] sKe)
                         throws java.security.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:

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

java.lang.UnsupportedOperationException - if mode is not a supported HPKE mode

java.lang.IllegalStateException - if this SPI has already been initialised

engineInitRecipient

void engineInitRecipient(byte[] encapsulated,
                         java.security.PrivateKey recipientKey,
                         byte[] info,
                         java.security.PublicKey senderKey,
                         byte[] psk,
                         byte[] psk_id)
                  throws java.security.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:

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

java.lang.UnsupportedOperationException - if mode is not a supported HPKE mode

java.lang.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:

java.lang.NullPointerException - if the plaintext is null

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

engineOpen

byte[] engineOpen(byte[] ciphertext,
                  byte[] aad)
           throws java.security.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:

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

java.security.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:

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

java.lang.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:

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