Hpke

open class Hpke
kotlin.Any
   ↳ android.crypto.hpke.Hpke

Provides access to implementations of HPKE hybrid cryptography as per RFC 9180.

Provider and HPKE suite selection are done via the getInstance methods, and then instances of senders and receivers can be created using newSender or {newReceiver}. Each sender and receiver is independent, i.e. does not share any encapsulated state with other senders or receivers created via this Hpke.

HPKE suites are composed of a key encapsulation mechanism (KEM), a key derivation function (KDF) and an authenticated cipher algorithm (AEAD) as defined in RFC 9180 section 7. NamedParameterSpecs for these can be found in KemParameterSpec, KdfParameterSpec and AeadParameterSpec. These can be composed into a full HPKE suite name used to request a particular implementation using Hpke.getSuiteName(KemParameterSpec, KdfParameterSpec, AeadParameterSpec).

Summary

Public methods
open static Hpke
getInstance(suiteName: String)

Returns an Hpke instance configured for the requested HPKE suite, using the highest priority Provider which implements it.
open static Hpke
getInstance(suiteName: String, providerName: String)

Returns an Hpke instance configured for the requested HPKE suite, using the requested Provider by name.
open static Hpke
getInstance(suiteName: String, provider: Provider)

Returns an Hpke instance configured for the requested HPKE suite, using the requested Provider.
open Provider

Returns the Provider being used by this Hpke instance.
open static String

Generates a full HPKE suite name from the named parameter specifications of its components, which have names reflecting their usage in RFC 9180.
open ByteArray
open(recipientKey: PrivateKey, info: ByteArray?, message: Message, aad: ByteArray?)

One shot API to open a single ciphertext using BASE mode (no authentication).
open Message
seal(recipientKey: PublicKey, info: ByteArray?, plaintext: ByteArray, aad: ByteArray?)

One shot API to seal a single message using BASE mode (no authentication).

Public methods

getInstance

open static fun getInstance(suiteName: String): Hpke

Returns an Hpke instance configured for the requested HPKE suite, using the highest priority Provider which implements it.

Use Hpke.getSuiteName(KemParameterSpec, KdfParameterSpec, AeadParameterSpec) for generating HPKE suite names from NamedParameterSpecs

Parameters
suiteName String: the HPKE suite to use.
This value cannot be null.
Return
Hpke an Hpke instance configured for the requested suite.
This value cannot be null.
Exceptions
java.security.NoSuchAlgorithmException if no Providers can be found for the requested suite

getInstance

open static fun getInstance(
    suiteName: String, 
    providerName: String
): Hpke

Returns an Hpke instance configured for the requested HPKE suite, using the requested Provider by name.

Parameters
suiteName String: the HPKE suite to use.
This value cannot be null.
providerName String: the name of the provider to use.
This value cannot be null.
Return
Hpke an Hpke instance configured for the requested suite and Provider.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if providerName is null or empty
java.security.NoSuchAlgorithmException if the named Provider does not implement this suite
java.security.NoSuchProviderException if no Provider with the requested name can be found

getInstance

open static fun getInstance(
    suiteName: String, 
    provider: Provider
): Hpke

Returns an Hpke instance configured for the requested HPKE suite, using the requested Provider.

Parameters
suiteName String: the HPKE suite to use.
This value cannot be null.
provider Provider: the provider to use.
This value cannot be null.
Return
Hpke an Hpke instance configured for the requested suite and Provider.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if provider is null
java.security.NoSuchAlgorithmException if the Provider does not implement this suite

getProvider

open fun getProvider(): Provider

Returns the Provider being used by this Hpke instance.

Return
Provider the Provider.
This value cannot be null.

getSuiteName

open static fun getSuiteName(
    kem: KemParameterSpec, 
    kdf: KdfParameterSpec, 
    aead: AeadParameterSpec
): String

Generates a full HPKE suite name from the named parameter specifications of its components, which have names reflecting their usage in RFC 9180.

HPKE suites are composed of a key encapsulation mechanism (KEM), a key derivation function (KDF) and an authenticated cipher algorithm (AEAD) as defined in RFC 9180 section 7. NamedParameterSpecs for these can be foundu in KemParameterSpec, KdfParameterSpec and AeadParameterSpec.

Parameters
kem KemParameterSpec: the key encapsulation mechanism to use.
This value cannot be null.
kdf KdfParameterSpec: the key derivation function to use.
This value cannot be null.
aead AeadParameterSpec: the AEAD cipher to use.
This value cannot be null.
Return
String a fully composed HPKE suite name.
This value cannot be null.

open

open fun open(
    recipientKey: PrivateKey, 
    info: ByteArray?, 
    message: Message, 
    aad: ByteArray?
): ByteArray

One shot API to open a single ciphertext using BASE mode (no authentication).

Parameters
recipientKey PrivateKey: private key of the recipient.
This value cannot be null.
info ByteArray?: application-supplied information, may be null or empty
message Message: the Message to open.
This value cannot be null.
aad ByteArray?: optional additional authenticated data, may be null or empty
Return
ByteArray decrypted plaintext.
This value cannot be null.
Exceptions
java.security.GeneralSecurityException if the decryption fails
java.security.InvalidKeyException if recipientKey is null or an unsupported key format

See Also

    seal

    open fun seal(
        recipientKey: PublicKey, 
        info: ByteArray?, 
        plaintext: ByteArray, 
        aad: ByteArray?
    ): Message

    One shot API to seal a single message using BASE mode (no authentication).

    Parameters
    recipientKey PublicKey: public key of the recipient.
    This value cannot be null.
    info ByteArray?: additional application-supplied information, may be null or empty
    plaintext ByteArray: the message to send.
    This value cannot be null.
    aad ByteArray?: optional additional authenticated data, may be null or empty
    Return
    Message a Message object containing the encapsulated key, ciphertext and aad.
    This value cannot be null.
    Exceptions
    java.security.InvalidKeyException if recipientKey is null or an unsupported key format

    See Also