Package: org.conscrypt
HpkeSpi
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.
Fields
DEFAULT_PSK
DEFAULT_PSK_ID
Public Methods
engineInitSender
public abstract void engineInitSender(PublicKey recipientKey, byte[] info, 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 |
| 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
public abstract void engineInitSenderForTesting(PublicKey recipientKey, byte[] info, 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 |
| 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
public abstract void engineInitRecipient(byte[] encapsulated, PrivateKey recipientKey, byte[] info, 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 |
| 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
public abstract 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 |
| byte[] |
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
public abstract 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 |
| byte[] |
the plaintext |
| Throws |
| IllegalStateException |
if this SPI has not been initialised or if it was initialised
as a sender |
| GeneralSecurityException |
on decryption failures |
engineExport
public abstract 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 |
| byte[] |
exported value |
| Throws |
| IllegalArgumentException |
if the length is not valid for the KDF in use |
| IllegalStateException |
if this SPI has not been initialised |
getEncapsulated
public abstract byte[] getEncapsulated()
Returns the encapsulated key material for an HPKE sender.
| Returns |
| byte[] |
the key material |
| Throws |
| IllegalStateException |
if this SPI has not been initialised or if it was initialised
as a recipient |