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
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
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
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
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
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
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
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 |