Added in API level 35

HpkeSpi


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 ByteArray
engineExport(length: Int, context: ByteArray?)

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

abstract Unit
engineInitRecipient(encapsulated: ByteArray, recipientKey: PrivateKey, info: ByteArray?, senderKey: PublicKey?, psk: ByteArray?, psk_id: ByteArray?)

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

abstract Unit
engineInitSender(recipientKey: PublicKey, info: ByteArray?, senderKey: PrivateKey?, psk: ByteArray?, psk_id: ByteArray?)

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

abstract Unit
engineInitSenderWithSeed(recipientKey: PublicKey, info: ByteArray?, senderKey: PrivateKey?, psk: ByteArray?, psk_id: ByteArray?, sKe: ByteArray)

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 ByteArray
engineOpen(ciphertext: ByteArray, aad: ByteArray?)

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

abstract ByteArray
engineSeal(plaintext: ByteArray, aad: ByteArray?)

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

abstract ByteArray

Returns the encapsulated key material for an HPKE sender.

Public methods

engineExport

Added in API level 35
abstract fun engineExport(
    length: Int,
    context: ByteArray?
): ByteArray

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

Parameters
length Int: expected output length
context ByteArray?: optional context string, may be null or empty
Return
ByteArray exported value This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the length is not valid for the KDF in use
java.lang.IllegalStateException if this SPI has not been initialised

engineInitRecipient

Added in API level 35
abstract fun engineInitRecipient(
    encapsulated: ByteArray,
    recipientKey: PrivateKey,
    info: ByteArray?,
    senderKey: PublicKey?,
    psk: ByteArray?,
    psk_id: ByteArray?
): Unit

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" java.security.KeyFactory can be used to translate KeySpecs or keys from another java.security.Provider

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

engineInitSender

Added in API level 35
abstract fun engineInitSender(
    recipientKey: PublicKey,
    info: ByteArray?,
    senderKey: PrivateKey?,
    psk: ByteArray?,
    psk_id: ByteArray?
): Unit

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" java.security.KeyFactory can be used to translate KeySpecs or keys from another java.security.Provider

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

engineInitSenderWithSeed

Added in API level 35
abstract fun engineInitSenderWithSeed(
    recipientKey: PublicKey,
    info: ByteArray?,
    senderKey: PrivateKey?,
    psk: ByteArray?,
    psk_id: ByteArray?,
    sKe: ByteArray
): Unit

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" java.security.KeyFactory can be used to translate KeySpecs or keys from another java.security.Provider

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

engineOpen

Added in API level 35
abstract fun engineOpen(
    ciphertext: ByteArray,
    aad: ByteArray?
): ByteArray

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

Parameters
ciphertext ByteArray: the ciphertext This value cannot be null.
aad ByteArray?: optional associated data, may be null or empty
Return
ByteArray the plaintext This value cannot be null.
Exceptions
java.lang.IllegalStateException if this SPI has not been initialised or if it was initialised as a sender
java.security.GeneralSecurityException on decryption failures

engineSeal

Added in API level 35
abstract fun engineSeal(
    plaintext: ByteArray,
    aad: ByteArray?
): ByteArray

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

Parameters
plaintext ByteArray: the plaintext This value cannot be null.
aad ByteArray?: optional associated data, may be null or empty
Return
ByteArray the ciphertext This value cannot be null.
Exceptions
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

getEncapsulated

Added in API level 35
abstract fun getEncapsulated(): ByteArray

Returns the encapsulated key material for an HPKE sender.

Return
ByteArray the key material This value cannot be null.
Exceptions
java.lang.IllegalStateException if this SPI has not been initialised or if it was initialised as a recipient