HpkeSpi

public interface HpkeSpi

android.crypto.hpke.HpkeSpi

Service Provider Interface for HPKE client API classes to communicate with implementations of HPKE as described in RFC 9180.

There are no standard Java Cryptography Architecture names or interface classes for HPKE, but instances of this class can be obtained by calling Provider.getService("ConscryptHpke", String SuiteName) where suiteName is the name of the HPKE suite, e.g. "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM".

Summary

Public methods

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

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

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

Initialises an HPKE SPI in one of the sender modes described in RFC 9180.

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

Initialises an HPKE SPI in one of the sender modes described in RFC 9180.

abstract void engineInitSenderWithSeed(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id, byte[] sKe)

Initialises an HPKE SPI in one of the sender modes described in RFC 9180 with a predefined random seed to allow testing against known test vectors.

abstract byte[] engineOpen(byte[] ciphertext, byte[] aad)

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

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

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

abstract byte[] getEncapsulated()

Returns the encapsulated key material for an HPKE sender.

Public methods

engineExport

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

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

Parameters
length int: expected output length
context byte: optional context string, may be null or empty
Returns
byte[] exported value This value cannot be null.
Throws
IllegalArgumentException if the length is not valid for the KDF in use
IllegalStateException if this SPI has not been initialised

engineInitRecipient

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

Initialises an HPKE SPI in one of the sender modes described in RFC 9180.

If psk and psk_id are supplied then Pre-Shared Key Authentication will be used.

If senderKey is supplied then Asymmetric Key Authentication will be used.

If neither is supplied then "base" mode (no sender authentication) will be used.

Note that only base mode is currently supported on Android.

Public and private keys must be supplied in a format that can be used by the implementation. An instance of the "XDH" KeyFactory can be used to translate KeySpecs or keys from another Provider

Parameters
encapsulated byte: encapsulated ephemeral key from a sender This value cannot be null.
recipientKey PrivateKey: private key of the recipient This value cannot be null.
info byte: application-supplied information, may be null or empty
senderKey PublicKey: public key of sender, for asymmetric auth modes only, else null
psk byte: pre-shared key, for PSK auth modes only, else null
psk_id byte: 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

engineInitSender

public abstract void engineInitSender (PublicKey recipientKey, 
                byte[] info, 
                PrivateKey senderKey, 
                byte[] psk, 
                byte[] psk_id)

Initialises an HPKE SPI in one of the sender modes described in RFC 9180.

If psk and psk_id are supplied then Pre-Shared Key Authentication will be used.

If senderKey is supplied then Asymmetric Key Authentication will be used.

If neither is supplied then "base" mode (no sender authentication) will be used.

Note that only base mode is currently supported on Android.

Public and private keys must be supplied in a format that can be used by the implementation. An instance of the "XDH" KeyFactory can be used to translate KeySpecs or keys from another Provider

Parameters
recipientKey PublicKey: public key of the recipient This value cannot be null.
info byte: application-supplied information, may be null or empty
senderKey PrivateKey: private key of the sender, for symmetric auth modes only, else null
psk byte: pre-shared key, for PSK auth modes only, else null
psk_id byte: 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

engineInitSenderWithSeed

public abstract void engineInitSenderWithSeed (PublicKey recipientKey, 
                byte[] info, 
                PrivateKey senderKey, 
                byte[] psk, 
                byte[] psk_id, 
                byte[] sKe)

Initialises an HPKE SPI in one of the sender modes described in RFC 9180 with a predefined random seed to allow testing against known test vectors.

This mode provides absolutely no security and should only be used for testing purposes.

If psk and psk_id are supplied then Pre-Shared Key Authentication will be used.

If senderKey is supplied then Asymmetric Key Authentication will be used.

If neither is supplied then "base" mode (no sender authentication) will be used.

Note that only base mode is currently supported on Android.

Public and private keys must be supplied in a format that can be used by the implementation. An instance of the "XDH" KeyFactory can be used to translate KeySpecs or keys from another Provider

Parameters
recipientKey PublicKey: public key of the recipient This value cannot be null.
info byte: application-supplied information, may be null or empty
senderKey PrivateKey: private key of the sender, for symmetric auth modes only, else null
psk byte: pre-shared key, for PSK auth modes only, else null
psk_id byte: pre-shared key ID, for PSK auth modes only, else null
sKe byte: Predetermined random seed, should only be usesd for validation against known test vectors This value cannot be 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

engineOpen

public abstract byte[] engineOpen (byte[] ciphertext, 
                byte[] aad)

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

Parameters
ciphertext byte: the ciphertext This value cannot be null.
aad byte: optional associated data, may be null or empty
Returns
byte[] the plaintext This value cannot be null.
Throws
IllegalStateException if this SPI has not been initialised or if it was initialised as a sender
GeneralSecurityException on decryption failures

engineSeal

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

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

Parameters
plaintext byte: the plaintext This value cannot be null.
aad byte: optional associated data, may be null or empty
Returns
byte[] the ciphertext This value cannot be null.
Throws
NullPointerException if the plaintext is null
IllegalStateException if this SPI has not been initialised or if it was initialised as a recipient

getEncapsulated

public abstract byte[] getEncapsulated ()

Returns the encapsulated key material for an HPKE sender.

Returns
byte[] the key material This value cannot be null.
Throws
IllegalStateException if this SPI has not been initialised or if it was initialised as a recipient