HPKE support in wolfCrypt

HPKE (Hybrid Public Key Encryption) is a key encapsulation and encryption standard that allows two parties to derive a common secret and encrypt/decrypt messages using that common secret ([https://www.ietf.org/archive/id/draft-irtf-cfrg-hpke-12.txt](https://www.ietf.org/archive/id/draft-irtf-cfrg-hpke-12.txt))  HPKE has three steps in single-shot mode: 

Key encapsulation (KEM) - ECC P256, P384, P521 or X25519 Hash based Key Derivation (HKDF) - SHA2-256, SHA2-384, SHA2-512 Authenticated Encryption with Associated Data (AEAD). AES-GCM 128/256 bit

Here is an example of how HPKE is used: https://gist.github.com/jpbland1/b2a1c46bc934fd8ee0dc4d148a8b9eab The Hpke struct is used for the HPKE operations and we initialize it with our KEM, KDF and AEAD algorithms using wc_HpkeInit. Here we’re using X25519, SHA256 and AES128. Then we need to generate keypairs to use, with the ephemeralKey being used by the client to seal messages and the receiverKey being used by the server to open them. They’re both generated using wc_HpkeGenerateKeyPair and have a type of void* because they can actually be one of many types depending on the KEM algorithm chosen, which wolfCrypt takes care of internally. The client then seals our message using wc_HpkeSealBase which takes the client’s private key, the server’s public key, an optional info field, an optional AAD field, the message to encrypt start_text and the buffer to put the encrypted message into ciphertext. NOTE that ciphertext MUST be 16 bytes longer than the message we’re trying to encrypt to store the AEAD tag needed to decrypt it. wc_HpkeSerializePublicKey will serialize an HPKE public key into a bytestring so it can be shared with the other party. Keys can later be deserialized using wc_HpkeDeserializePublicKey. These functions should be used to share the KEM public keys between client and server. Then for the server to decrypt, wc_HpkeOpenBase takes the receiverKey, the serialized public ephemeralKey, an optional info field, an optional AAD field, the ciphertext and tag to decrypt and the buffer to store the decrypted message. When finished the plaintext buffer will have the same data in it as the original start_text buffer. To free the keys when we’re done using them we call wc_HpkeFreeKey with the kem and key. Support for ECH and HPKE was added in PR https://github.com/wolfSSL/wolfssl/pull/5623 If you have any questions or run into any issues, contact us at facts@wolfssl.com, or call us at +1 425 245 8247.