HPKE support in wolfCrypt

    • 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)

     HPKE has three steps in single-shot mode: 

    1. Key encapsulation (KEM) - ECC P256, P384, P521 or X25519
    2. Hash based Key Derivation (HKDF) - SHA2-256, SHA2-384, SHA2-512
    3. 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.