[*New in v22.0*]
This toolkit has all the basic cryptographic primitives required to carry out the hybrid public key encryption (HPKE) scheme
described in [RFC9180]; namely
Elliptic Curve Diffie-Hellman (ECDH) key agreement (see ECC_DHSharedSecret),
HMAC-based key derivation function (HKDF) using SHA2 (see KDF_Bytes),
and authenticated encryption with additional data (AEAD)
(see CIPHER_EncryptAEAD).

Specific functions
HPKE_LabeledExtract and HPKE_LabeledExpand
are provided here to carry out `LabeledExtract()`

and `LabeledExpand()`

.
The function HPKE_DerivePrivateKey is provided to derive an EC private key using the deterministic method
described in HKPE. The corresponding public key can be derived using ECC_PublicKeyFromPrivate.

Note that these functions are intended to be used in an object-oriented language like C# or Python, not in raw ANSI C or VB6.
See the code `hpke_test.py`

on our web site for an example.

In this implementation, the KDF algorithm is chosen automatically to match the KEM ECDH group curve as follows (from Table 2 in [RFC9180]).

KEM | ECDH group | KDF |
---|---|---|

DHKEM(P-256, HKDF-SHA256 |
P-256 | HKDF-SHA256 |

DHKEM(P-384, HKDF-SHA384 |
P-384 | HKDF-SHA384 |

DHKEM(P-521, HKDF-SHA512 |
P-521 | HKDF-SHA512 |

DHKEM(X25519, HKDF-SHA256 |
X25519 | HKDF-SHA256 |

DHKEM(X448, HKDF-SHA512 |
X448 | HKDF-SHA512 |

Furthermore, the ciphersuite's KDF is assumed to be always equal to the DHKEM's associated KDF from the above table.

Because these are all standalone functions with no context, the ECDH curve group used in the scheme must be specified. This automatically defines the KDF and associated HMAC algorithm to be used as per the above table.

The `LabeledExtract()`

and `LabeledExpand()`

functions facilitate domain separation of KDF calls by incorporating a `label`

and a `suite_id`

which has a value derived from identifiers for the EC curve group, the KDF algorithm and, sometimes, the AEAD algorithm.
Note that the `suite_id`

value is different depending on where the KDF is used.
In this implementation, specifying the curve name will automatically select the corresponding KDF algorithm, and the absence or presence of an option flag for
an AEAD algorithm dictates whether the KDF is being used inside a KEM algorithm (zero flag) or in the remainder of HPKE (specific AEAD algorithm flag).

The string literal "HPKE-v1" is currently hardcoded into the `LabeledExtract()`

and `LabeledExpand()`

functions.
Future implementations may offer an alternative if the specification is changed.