Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

# HpkeSpi

*** ** * ** ***

` public interface HpkeSpi `   
` `

|---|
| android.crypto.hpke.HpkeSpi |

<br />

*** ** * ** ***

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[]` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineExport(int,%20byte[])(int length, byte[] context) ` Exports secret key material from this SPI as described in RFC 9180. |
| ` abstract void` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineInitRecipient(byte[],%20java.security.PrivateKey,%20byte[],%20java.security.PublicKey,%20byte[],%20byte[])(byte[] encapsulated, https://developer.android.com/reference/java/security/PrivateKey recipientKey, byte[] info, https://developer.android.com/reference/java/security/PublicKey senderKey, byte[] psk, byte[] psk_id) ` Initialises an HPKE SPI in one of the recipient modes described in RFC 9180. |
| ` abstract void` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineInitSender(java.security.PublicKey,%20byte[],%20java.security.PrivateKey,%20byte[],%20byte[])(https://developer.android.com/reference/java/security/PublicKey recipientKey, byte[] info, https://developer.android.com/reference/java/security/PrivateKey senderKey, byte[] psk, byte[] psk_id) ` Initialises an HPKE SPI in one of the sender modes described in RFC 9180. |
| ` abstract void` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineInitSenderWithSeed(java.security.PublicKey,%20byte[],%20java.security.PrivateKey,%20byte[],%20byte[],%20byte[])(https://developer.android.com/reference/java/security/PublicKey recipientKey, byte[] info, https://developer.android.com/reference/java/security/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[]` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineOpen(byte[],%20byte[])(byte[] ciphertext, byte[] aad) ` Opens a message, using the internal key schedule maintained by an HPKE recipient SPI. |
| ` abstract byte[]` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#engineSeal(byte[],%20byte[])(byte[] plaintext, byte[] aad) ` Seals a message, using the internal key schedule maintained by an HPKE sender SPI. |
| ` abstract byte[]` | ` https://developer.android.com/reference/android/crypto/hpke/HpkeSpi#getEncapsulated()() ` Returns the encapsulated key material for an HPKE sender. |

## Public methods

### engineExport

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

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

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

<br />

| Parameters ||
|---|---|
| `length` | `int`: expected output length <br /> |
| `context` | `byte`: optional context string, may be null or empty <br /> |

| Returns ||
|---|---|
| `byte[]` | exported value. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the length is not valid for the KDF in use |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has not been initialised |

### engineInitRecipient

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 recipient modes described in RFC 9180.

If `senderKey` is supplied then Asymmetric Key Authentication will be used, (MODE_AUTH)

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

If all of `senderKey`, `psk` and `psk_id` are supplied then both Key and PSK authentication will be used (MODE_AUTH_PSK).

If neither is supplied then no sender authentication will be used (MODE_BASE).

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"` `https://developer.android.com/reference/java/security/KeyFactory` can be used to translate `KeySpecs` or keys from another `https://developer.android.com/reference/java/security/Provider`

<br />

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

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has already been initialised |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the mode is not supported by this implementation |
| `https://developer.android.com/reference/java/security/InvalidKeyException` | if recipientKey is null or an unsupported key format or senderKey is an unsupported key format |

### engineInitSender

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `senderKey` is supplied then Asymmetric Key Authentication will be used, (MODE_AUTH)

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

If all of `senderKey`, `psk` and `psk_id` are supplied then both Key and PSK authentication will be used (MODE_AUTH_PSK).

If neither is supplied then no sender authentication will be used (MODE_BASE).

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"` `https://developer.android.com/reference/java/security/KeyFactory` can be used to translate `KeySpecs` or keys from another `https://developer.android.com/reference/java/security/Provider`

<br />

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

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has already been initialised |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the mode is not supported by this implementation |
| `https://developer.android.com/reference/java/security/InvalidKeyException` | if recipientKey is null or an unsupported key format |

### engineInitSenderWithSeed

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `senderKey` is supplied then Asymmetric Key Authentication will be used, (MODE_AUTH)

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

If all of `senderKey`, `psk` and `psk_id` are supplied then both Key and PSK authentication will be used (MODE_AUTH_PSK).

If neither is supplied then no sender authentication will be used (MODE_BASE).

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"` `https://developer.android.com/reference/java/security/KeyFactory` can be used to translate `KeySpecs` or keys from another `https://developer.android.com/reference/java/security/Provider`

<br />

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

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has already been initialised |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the mode is not supported by this implementation |
| `https://developer.android.com/reference/java/security/InvalidKeyException` | if recipientKey is null or an unsupported key format or senderKey is an unsupported key format |

### engineOpen

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

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

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

<br />

| Parameters ||
|---|---|
| `ciphertext` | `byte`: the ciphertext. This value cannot be `null`. <br /> |
| `aad` | `byte`: optional associated data, may be null or empty <br /> |

| Returns ||
|---|---|
| `byte[]` | the plaintext. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has not been initialised or if it was initialised as a sender |
| `https://developer.android.com/reference/java/security/GeneralSecurityException` | on decryption failures |

### engineSeal

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

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

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

<br />

| Parameters ||
|---|---|
| `plaintext` | `byte`: the plaintext. This value cannot be `null`. <br /> |
| `aad` | `byte`: optional associated data, may be null or empty <br /> |

| Returns ||
|---|---|
| `byte[]` | the ciphertext. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has not been initialised or if it was initialised as a recipient |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the plaintext is null |

### getEncapsulated

Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract byte[] getEncapsulated ()
```

Returns the encapsulated key material for an HPKE sender.

<br />

| Returns ||
|---|---|
| `byte[]` | the key material. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if this SPI has not been initialised or if it was initialised as a recipient |