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 |