include/openssl/hpke.h - boringssl.git - Git at Google


            
            // Copyright 2020 The BoringSSL Authors

            
            //

            
            // Licensed under the Apache License, Version 2.0 (the "License");

            
            // you may not use this file except in compliance with the License.

            
            // You may obtain a copy of the License at

            
            //

            
            //     https://www.apache.org/licenses/LICENSE-2.0

            
            //

            
            // Unless required by applicable law or agreed to in writing, software

            
            // distributed under the License is distributed on an "AS IS" BASIS,

            
            // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

            
            // See the License for the specific language governing permissions and

            
            // limitations under the License.


            #ifndef OPENSSL_HEADER_HPKE_H

            
            #define OPENSSL_HEADER_HPKE_H


            #include <openssl/aead.h>

            
            #include <openssl/base.h>  // IWYU pragma: export

            
            #include <openssl/curve25519.h>

            
            #include <openssl/digest.h>


            #if defined(__cplusplus)

            
            extern "C" {

            
            #endif


            // Hybrid Public Key Encryption.

            
            //

            
            // Hybrid Public Key Encryption (HPKE) enables a sender to encrypt messages to a

            
            // receiver with a public key.

            
            //

            
            // See RFC 9180.


            // Parameters.

            
            //

            
            // An HPKE context is parameterized by KEM, KDF, and AEAD algorithms,

            
            // represented by `EVP_HPKE_KEM`, `EVP_HPKE_KDF`, and `EVP_HPKE_AEAD` types,

            
            // respectively.


            // The following constants are KEM identifiers.

            
            #define EVP_HPKE_DHKEM_P256_HKDF_SHA256 0x0010

            
            #define EVP_HPKE_DHKEM_X25519_HKDF_SHA256 0x0020

            
            #define EVP_HPKE_XWING 0x647a

            
            #define EVP_HPKE_MLKEM768 0x0041

            
            #define EVP_HPKE_MLKEM1024 0x0042


            // The following functions are KEM algorithms which may be used with HPKE. Note

            
            // that, while some HPKE KEMs use KDFs internally, this is separate from the

            
            // `EVP_HPKE_KDF` selection.

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_x25519_hkdf_sha256(void);

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_p256_hkdf_sha256(void);

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_xwing(void);

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_mlkem768(void);

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_mlkem1024(void);


            // EVP_kem_dhkem_* implement DHKEM variants defined in RFC 9180.

            
            OPENSSL_EXPORT const EVP_KEM *EVP_kem_dhkem_p256_hkdf_sha256(void);

            
            OPENSSL_EXPORT const EVP_KEM *EVP_kem_dhkem_x25519_hkdf_sha256(void);


            // EVP_HPKE_KEM_id returns the HPKE KEM identifier for `kem`, which

            
            // will be one of the `EVP_HPKE_KEM_*` constants.

            
            OPENSSL_EXPORT uint16_t EVP_HPKE_KEM_id(const EVP_HPKE_KEM *kem);


            // EVP_HPKE_MAX_PUBLIC_KEY_LENGTH is the maximum length of an encoded public key

            
            // for all KEMs currently supported by this library.

            
            #define EVP_HPKE_MAX_PUBLIC_KEY_LENGTH 1568


            // EVP_HPKE_KEM_public_key_len returns the length of a public key for `kem`.

            
            // This value will be at most `EVP_HPKE_MAX_PUBLIC_KEY_LENGTH`.

            
            OPENSSL_EXPORT size_t EVP_HPKE_KEM_public_key_len(const EVP_HPKE_KEM *kem);


            // EVP_HPKE_MAX_PRIVATE_KEY_LENGTH is the maximum length of an encoded private

            
            // key for all KEMs currently supported by this library.

            
            #define EVP_HPKE_MAX_PRIVATE_KEY_LENGTH 64


            // EVP_HPKE_KEM_private_key_len returns the length of a private key for `kem`.

            
            // This value will be at most `EVP_HPKE_MAX_PRIVATE_KEY_LENGTH`.

            
            OPENSSL_EXPORT size_t EVP_HPKE_KEM_private_key_len(const EVP_HPKE_KEM *kem);


            // EVP_HPKE_MAX_ENC_LENGTH is the maximum length of "enc", the encapsulated

            
            // shared secret, for all KEMs currently supported by this library.

            
            #define EVP_HPKE_MAX_ENC_LENGTH 1568


            // EVP_HPKE_KEM_enc_len returns the length of the "enc", the encapsulated shared

            
            // secret, for `kem`. This value will be at most `EVP_HPKE_MAX_ENC_LENGTH`.

            
            OPENSSL_EXPORT size_t EVP_HPKE_KEM_enc_len(const EVP_HPKE_KEM *kem);


            // EVP_HPKE_KEM_shared_secret_len returns the length of the shared secret

            
            // produced by `kem`.

            
            OPENSSL_EXPORT size_t EVP_HPKE_KEM_shared_secret_len(const EVP_HPKE_KEM *kem);


            // The following constants are KDF identifiers.

            
            #define EVP_HPKE_HKDF_SHA256 0x0001

            
            #define EVP_HPKE_HKDF_SHA384 0x0002


            // The following functions are KDF algorithms which may be used with HPKE. If

            
            // unsure, use `EVP_hpke_hkdf_sha256`.

            
            OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(void);

            
            OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha384(void);


            // EVP_HPKE_KDF_id returns the HPKE KDF identifier for `kdf`.

            
            OPENSSL_EXPORT uint16_t EVP_HPKE_KDF_id(const EVP_HPKE_KDF *kdf);


            // EVP_HPKE_KDF_hkdf_md returns the HKDF hash function corresponding to `kdf`,

            
            // or NULL if `kdf` is not an HKDF-based KDF. All currently supported KDFs are

            
            // HKDF-based.

            
            OPENSSL_EXPORT const EVP_MD *EVP_HPKE_KDF_hkdf_md(const EVP_HPKE_KDF *kdf);


            // The following constants are AEAD identifiers.

            
            #define EVP_HPKE_AES_128_GCM 0x0001

            
            #define EVP_HPKE_AES_256_GCM 0x0002

            
            #define EVP_HPKE_CHACHA20_POLY1305 0x0003


            // The following functions are AEAD algorithms which may be used with HPKE.

            
            OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_128_gcm(void);

            
            OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_256_gcm(void);

            
            OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_chacha20_poly1305(void);


            // EVP_HPKE_AEAD_id returns the HPKE AEAD identifier for `aead`.

            
            OPENSSL_EXPORT uint16_t EVP_HPKE_AEAD_id(const EVP_HPKE_AEAD *aead);


            // EVP_HPKE_AEAD_aead returns the `EVP_AEAD` corresponding to `aead`.

            
            OPENSSL_EXPORT const EVP_AEAD *EVP_HPKE_AEAD_aead(const EVP_HPKE_AEAD *aead);


            // Recipient keys.

            
            //

            
            // An HPKE recipient maintains a long-term KEM key. This library represents keys

            
            // with the `EVP_HPKE_KEY` type.


            // EVP_HPKE_KEY_zero sets an uninitialized `EVP_HPKE_KEY` to the zero state. The

            
            // caller should then use `EVP_HPKE_KEY_init`, `EVP_HPKE_KEY_copy`, or

            
            // `EVP_HPKE_KEY_generate` to finish initializing `key`.

            
            //

            
            // It is safe, but not necessary to call `EVP_HPKE_KEY_cleanup` in this state.

            
            // This may be used for more uniform cleanup of `EVP_HPKE_KEY`.

            
            OPENSSL_EXPORT void EVP_HPKE_KEY_zero(EVP_HPKE_KEY *key);


            // EVP_HPKE_KEY_cleanup releases memory referenced by `key`.

            
            OPENSSL_EXPORT void EVP_HPKE_KEY_cleanup(EVP_HPKE_KEY *key);


            // EVP_HPKE_KEY_new returns a newly-allocated `EVP_HPKE_KEY`, or NULL on error.

            
            // The caller must call `EVP_HPKE_KEY_free` on the result to release it.

            
            //

            
            // This is a convenience function for callers that need a heap-allocated

            
            // `EVP_HPKE_KEY`.

            
            OPENSSL_EXPORT EVP_HPKE_KEY *EVP_HPKE_KEY_new(void);


            // EVP_HPKE_KEY_free releases memory associated with `key`, which must have been

            
            // created with `EVP_HPKE_KEY_new`.

            
            OPENSSL_EXPORT void EVP_HPKE_KEY_free(EVP_HPKE_KEY *key);


            // EVP_HPKE_KEY_copy sets `dst` to a copy of `src`. It returns one on success

            
            // and zero on error. On success, the caller must call `EVP_HPKE_KEY_cleanup` to

            
            // release `dst`. On failure, calling `EVP_HPKE_KEY_cleanup` is safe, but not

            
            // necessary.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_copy(EVP_HPKE_KEY *dst,

            
                                                 const EVP_HPKE_KEY *src);


            // EVP_HPKE_KEY_move sets `out`, which must be initialized or in the zero state,

            
            // to the key in `in`. `in` is mutated and left in the zero state.

            
            OPENSSL_EXPORT void EVP_HPKE_KEY_move(EVP_HPKE_KEY *out, EVP_HPKE_KEY *in);


            // EVP_HPKE_KEY_init decodes `priv_key` as a private key for `kem` and

            
            // initializes `key` with the result. It returns one on success and zero if

            
            // `priv_key` was invalid. On success, the caller must call

            
            // `EVP_HPKE_KEY_cleanup` to release the key. On failure, calling

            
            // `EVP_HPKE_KEY_cleanup` is safe, but not necessary.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_init(EVP_HPKE_KEY *key, const EVP_HPKE_KEM *kem,

            
                                                 const uint8_t *priv_key,

            
                                                 size_t priv_key_len);


            // EVP_HPKE_KEY_generate sets `key` to a newly-generated key using `kem`.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_generate(EVP_HPKE_KEY *key,

            
                                                     const EVP_HPKE_KEM *kem);


            // EVP_HPKE_KEY_derive deterministically derives a key from `ikm` for use with

            
            // `kem` and initializes `key` with the result. It returns one on success and

            
            // zero on error. This corresponds to the DeriveKeyPair operation in RFC 9180.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_derive(EVP_HPKE_KEY *key,

            
                                                   const EVP_HPKE_KEM *kem,

            
                                                   const uint8_t *ikm, size_t ikm_len);


            // EVP_HPKE_KEY_kem returns the HPKE KEM used by `key`.

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_HPKE_KEY_kem(const EVP_HPKE_KEY *key);


            // EVP_HPKE_KEY_public_key writes `key`'s public key to `out` and sets

            
            // `*out_len` to the number of bytes written. On success, it returns one and

            
            // writes at most `max_out` bytes. If `max_out` is too small, it returns zero.

            
            // Setting `max_out` to `EVP_HPKE_MAX_PUBLIC_KEY_LENGTH` will ensure the public

            
            // key fits. An exact size can also be determined by

            
            // `EVP_HPKE_KEM_public_key_len`.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_public_key(const EVP_HPKE_KEY *key,

            
                                                       uint8_t *out, size_t *out_len,

            
                                                       size_t max_out);


            // EVP_HPKE_KEY_private_key writes `key`'s private key to `out` and sets

            
            // `*out_len` to the number of bytes written. On success, it returns one and

            
            // writes at most `max_out` bytes. If `max_out` is too small, it returns zero.

            
            // Setting `max_out` to `EVP_HPKE_MAX_PRIVATE_KEY_LENGTH` will ensure the

            
            // private key fits. An exact size can also be determined by

            
            // `EVP_HPKE_KEM_private_key_len`.

            
            OPENSSL_EXPORT int EVP_HPKE_KEY_private_key(const EVP_HPKE_KEY *key,

            
                                                        uint8_t *out, size_t *out_len,

            
                                                        size_t max_out);


            // Encryption contexts.

            
            //

            
            // An HPKE encryption context is represented by the `EVP_HPKE_CTX` type.


            // EVP_HPKE_CTX_zero sets an uninitialized `EVP_HPKE_CTX` to the zero state. The

            
            // caller should then use one of the `EVP_HPKE_CTX_setup_*` functions to finish

            
            // setting up `ctx`.

            
            //

            
            // It is safe, but not necessary to call `EVP_HPKE_CTX_cleanup` in this state.

            
            // This may be used for more uniform cleanup of `EVP_HPKE_CTX`.

            
            OPENSSL_EXPORT void EVP_HPKE_CTX_zero(EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_cleanup releases memory referenced by `ctx`. `ctx` must have

            
            // been initialized with `EVP_HPKE_CTX_zero` or one of the

            
            // `EVP_HPKE_CTX_setup_*` functions.

            
            OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_new returns a newly-allocated `EVP_HPKE_CTX`, or NULL on error.

            
            // The caller must call `EVP_HPKE_CTX_free` on the result to release it.

            
            //

            
            // This is a convenience function for callers that need a heap-allocated

            
            // `EVP_HPKE_CTX`.

            
            OPENSSL_EXPORT EVP_HPKE_CTX *EVP_HPKE_CTX_new(void);


            // EVP_HPKE_CTX_free releases memory associated with `ctx`, which must have been

            
            // created with `EVP_HPKE_CTX_new`.

            
            OPENSSL_EXPORT void EVP_HPKE_CTX_free(EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_setup_sender implements the SetupBaseS HPKE operation. It

            
            // encapsulates a shared secret for `peer_public_key` and sets up `ctx` as a

            
            // sender context. It writes the encapsulated shared secret to `out_enc` and

            
            // sets `*out_enc_len` to the number of bytes written. It writes at most

            
            // `max_enc` bytes and fails if the buffer is too small. Setting `max_enc` to at

            
            // least `EVP_HPKE_MAX_ENC_LENGTH` will ensure the buffer is large enough. An

            
            // exact size may also be determined by `EVP_HPKE_KEM_enc_len`.

            
            //

            
            // This function returns one on success and zero on error. Note that

            
            // `peer_public_key` may be invalid, in which case this function will return an

            
            // error.

            
            //

            
            // On success, callers may call `EVP_HPKE_CTX_seal` to encrypt messages for the

            
            // recipient. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On

            
            // failure, calling `EVP_HPKE_CTX_cleanup` is safe, but not required.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender(

            
                EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,

            
                const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,

            
                const uint8_t *peer_public_key, size_t peer_public_key_len,

            
                const uint8_t *info, size_t info_len);


            // EVP_HPKE_CTX_setup_sender_with_seed_for_testing behaves like

            
            // `EVP_HPKE_CTX_setup_sender`, but takes a seed to behave deterministically.

            
            // The seed's format depends on `kem`. For X25519, it is the sender's

            
            // ephemeral private key. For P256, it's an HKDF input.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender_with_seed_for_testing(

            
                EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,

            
                const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,

            
                const uint8_t *peer_public_key, size_t peer_public_key_len,

            
                const uint8_t *info, size_t info_len, const uint8_t *seed, size_t seed_len);


            // EVP_HPKE_CTX_setup_recipient implements the SetupBaseR HPKE operation. It

            
            // decapsulates the shared secret in `enc` with `key` and sets up `ctx` as a

            
            // recipient context. It returns one on success and zero on failure. Note that

            
            // `enc` may be invalid, in which case this function will return an error.

            
            //

            
            // On success, callers may call `EVP_HPKE_CTX_open` to decrypt messages from the

            
            // sender. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On failure,

            
            // calling `EVP_HPKE_CTX_cleanup` is safe, but not required.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient(

            
                EVP_HPKE_CTX *ctx, const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf,

            
                const EVP_HPKE_AEAD *aead, const uint8_t *enc, size_t enc_len,

            
                const uint8_t *info, size_t info_len);


            // EVP_HPKE_CTX_setup_recipient_with_shared_secret behaves like

            
            // `EVP_HPKE_CTX_setup_recipient`, but takes the shared secret explicitly.

            
            //

            
            // WARNING: `shared_secret` must be the result of decapsulating the sender's

            
            // `enc` value with the recipient's private key. Using the wrong shared secret

            
            // will result in an `EVP_HPKE_CTX` that cannot decrypt the sender's messages.

            
            // Additionally, an attacker with knowledge of `shared_secret` will be able to

            
            // decrypt and forge encrypted messages.

            
            //

            
            // It returns one on success and zero on error.

            
            //

            
            // On success, callers may call `EVP_HPKE_CTX_open` to decrypt messages from the

            
            // sender. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On failure,

            
            // calling `EVP_HPKE_CTX_cleanup` is safe, but not required.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient_with_shared_secret(

            
                EVP_HPKE_CTX *ctx, const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf,

            
                const EVP_HPKE_AEAD *aead, const uint8_t *shared_secret,

            
                size_t shared_secret_len, const uint8_t *info, size_t info_len);


            // EVP_HPKE_CTX_setup_auth_sender implements the SetupAuthS HPKE operation. It

            
            // behaves like `EVP_HPKE_CTX_setup_sender` but authenticates the resulting

            
            // context with `key`.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_sender(

            
                EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,

            
                const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,

            
                const uint8_t *peer_public_key, size_t peer_public_key_len,

            
                const uint8_t *info, size_t info_len);


            // EVP_HPKE_CTX_setup_auth_sender_with_seed_for_testing behaves like

            
            // `EVP_HPKE_CTX_setup_auth_sender`, but takes a seed to behave

            
            // deterministically. The seed's format depends on `kem`. For X25519, it is the

            
            // sender's ephemeral private key. For P256, it's an HKDF input.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_sender_with_seed_for_testing(

            
                EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,

            
                const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,

            
                const uint8_t *peer_public_key, size_t peer_public_key_len,

            
                const uint8_t *info, size_t info_len, const uint8_t *seed, size_t seed_len);


            // EVP_HPKE_CTX_setup_auth_recipient implements the SetupAuthR HPKE operation.

            
            // It behaves like `EVP_HPKE_CTX_setup_recipient` but checks the resulting

            
            // context was authenticated with `peer_public_key`.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_recipient(

            
                EVP_HPKE_CTX *ctx, const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf,

            
                const EVP_HPKE_AEAD *aead, const uint8_t *enc, size_t enc_len,

            
                const uint8_t *info, size_t info_len, const uint8_t *peer_public_key,

            
                size_t peer_public_key_len);


            // Using an HPKE context.

            
            //

            
            // Once set up, callers may encrypt or decrypt with an `EVP_HPKE_CTX` using the

            
            // following functions.


            // EVP_HPKE_CTX_open uses the HPKE context `ctx` to authenticate `in_len` bytes

            
            // from `in` and `ad_len` bytes from `ad` and to decrypt at most `in_len` bytes

            
            // into `out`. It returns one on success, and zero otherwise.

            
            //

            
            // This operation will fail if the `ctx` context is not set up as a receiver.

            
            //

            
            // Note that HPKE encryption is stateful and ordered. The sender's first call to

            
            // `EVP_HPKE_CTX_seal` must correspond to the recipient's first call to

            
            // `EVP_HPKE_CTX_open`, etc.

            
            //

            
            // At most `in_len` bytes are written to `out`. In order to ensure success,

            
            // `max_out_len` should be at least `in_len`. On successful return, `*out_len`

            
            // is set to the actual number of bytes written.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_open(EVP_HPKE_CTX *ctx, uint8_t *out,

            
                                                 size_t *out_len, size_t max_out_len,

            
                                                 const uint8_t *in, size_t in_len,

            
                                                 const uint8_t *ad, size_t ad_len);


            // EVP_HPKE_CTX_seal uses the HPKE context `ctx` to encrypt and authenticate

            
            // `in_len` bytes of ciphertext `in` and authenticate `ad_len` bytes from `ad`,

            
            // writing the result to `out`. It returns one on success and zero otherwise.

            
            //

            
            // This operation will fail if the `ctx` context is not set up as a sender.

            
            //

            
            // Note that HPKE encryption is stateful and ordered. The sender's first call to

            
            // `EVP_HPKE_CTX_seal` must correspond to the recipient's first call to

            
            // `EVP_HPKE_CTX_open`, etc.

            
            //

            
            // At most, `max_out_len` encrypted bytes are written to `out`. On successful

            
            // return, `*out_len` is set to the actual number of bytes written.

            
            //

            
            // To ensure success, `max_out_len` should be `in_len` plus the result of

            
            // `EVP_HPKE_CTX_max_overhead` or `EVP_HPKE_MAX_OVERHEAD`.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_seal(EVP_HPKE_CTX *ctx, uint8_t *out,

            
                                                 size_t *out_len, size_t max_out_len,

            
                                                 const uint8_t *in, size_t in_len,

            
                                                 const uint8_t *ad, size_t ad_len);


            // EVP_HPKE_CTX_export uses the HPKE context `ctx` to export a secret of

            
            // `secret_len` bytes into `out`. This function uses `context_len` bytes from

            
            // `context` as a context string for the secret. This is necessary to separate

            
            // different uses of exported secrets and bind relevant caller-specific context

            
            // into the output. It returns one on success and zero otherwise.

            
            OPENSSL_EXPORT int EVP_HPKE_CTX_export(const EVP_HPKE_CTX *ctx, uint8_t *out,

            
                                                   size_t secret_len,

            
                                                   const uint8_t *context,

            
                                                   size_t context_len);


            // EVP_HPKE_MAX_OVERHEAD contains the largest value that

            
            // `EVP_HPKE_CTX_max_overhead` would ever return for any context.

            
            #define EVP_HPKE_MAX_OVERHEAD EVP_AEAD_MAX_OVERHEAD


            // EVP_HPKE_CTX_max_overhead returns the maximum number of additional bytes

            
            // added by sealing data with `EVP_HPKE_CTX_seal`. The `ctx` context must be set

            
            // up as a sender.

            
            OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_kem returns `ctx`'s configured KEM, or NULL if the context has

            
            // not been set up.

            
            OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_HPKE_CTX_kem(const EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_aead returns `ctx`'s configured AEAD, or NULL if the context has

            
            // not been set up.

            
            OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_HPKE_CTX_aead(const EVP_HPKE_CTX *ctx);


            // EVP_HPKE_CTX_kdf returns `ctx`'s configured KDF, or NULL if the context has

            
            // not been set up.

            
            OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_HPKE_CTX_kdf(const EVP_HPKE_CTX *ctx);


            // Private structures.

            
            //

            
            // The following structures are exported so their types are stack-allocatable,

            
            // but accessing or modifying their fields is forbidden.


            struct evp_hpke_ctx_st {

            
              const EVP_HPKE_KEM *kem;

            
              const EVP_HPKE_AEAD *aead;

            
              const EVP_HPKE_KDF *kdf;

            
              EVP_AEAD_CTX aead_ctx;

            
              uint8_t base_nonce[EVP_AEAD_MAX_NONCE_LENGTH];

            
              uint8_t exporter_secret[EVP_MAX_MD_SIZE];

            
              uint64_t seq;

            
              int is_sender;

            
            };


            struct evp_hpke_key_st {

            
              const EVP_HPKE_KEM *kem;

            
              uint8_t private_key[EVP_HPKE_MAX_PRIVATE_KEY_LENGTH];

            
              uint8_t public_key[EVP_HPKE_MAX_PUBLIC_KEY_LENGTH];


              // `pkey`, if non-null, takes precedence over `private_key` and `public_key`,

            
              // which are left unused. Otherwise `private_key` and `public_key` are used

            
              // instead.

            
              // TODO(crbug.com/535883377): Unify EVP_HPKE_KEM and EVP_KEM for all supported

            
              // HPKE KEMs.

            
              EVP_PKEY *pkey;

            
            };


            #if defined(__cplusplus)

            
            }  // extern C

            
            #endif


            #if !defined(BORINGSSL_NO_CXX)

            
            extern "C++" {


            BSSL_NAMESPACE_BEGIN


            BORINGSSL_MAKE_STACK_TRAITS(EVP_HPKE_CTX, EVP_HPKE_CTX_zero,

            
                                        EVP_HPKE_CTX_cleanup)

            
            using ScopedEVP_HPKE_CTX = internal::StackAllocated<EVP_HPKE_CTX>;


            BORINGSSL_MAKE_STACK_TRAITS_MOVABLE(EVP_HPKE_KEY, EVP_HPKE_KEY_zero,

            
                                                EVP_HPKE_KEY_cleanup, EVP_HPKE_KEY_move)

            
            using ScopedEVP_HPKE_KEY = internal::StackAllocatedMovable<EVP_HPKE_KEY>;


            BORINGSSL_MAKE_DELETER(EVP_HPKE_CTX, EVP_HPKE_CTX_free)

            
            BORINGSSL_MAKE_DELETER(EVP_HPKE_KEY, EVP_HPKE_KEY_free)


            BSSL_NAMESPACE_END


            }  // extern C++

            
            #endif


            #endif  // OPENSSL_HEADER_HPKE_H
	// Copyright 2020 The BoringSSL Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	#ifndef OPENSSL_HEADER_HPKE_H
	#define OPENSSL_HEADER_HPKE_H

	#include <openssl/aead.h>
	#include <openssl/base.h> // IWYU pragma: export
	#include <openssl/curve25519.h>
	#include <openssl/digest.h>

	#if defined(__cplusplus)
	extern "C" {
	#endif


	// Hybrid Public Key Encryption.
	//
	// Hybrid Public Key Encryption (HPKE) enables a sender to encrypt messages to a
	// receiver with a public key.
	//
	// See RFC 9180.


	// Parameters.
	//
	// An HPKE context is parameterized by KEM, KDF, and AEAD algorithms,
	// represented by `EVP_HPKE_KEM`, `EVP_HPKE_KDF`, and `EVP_HPKE_AEAD` types,
	// respectively.

	// The following constants are KEM identifiers.
	#define EVP_HPKE_DHKEM_P256_HKDF_SHA256 0x0010
	#define EVP_HPKE_DHKEM_X25519_HKDF_SHA256 0x0020
	#define EVP_HPKE_XWING 0x647a
	#define EVP_HPKE_MLKEM768 0x0041
	#define EVP_HPKE_MLKEM1024 0x0042

	// The following functions are KEM algorithms which may be used with HPKE. Note
	// that, while some HPKE KEMs use KDFs internally, this is separate from the
	// `EVP_HPKE_KDF` selection.
	OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_x25519_hkdf_sha256(void);
	OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_p256_hkdf_sha256(void);
	OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_xwing(void);
	OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_mlkem768(void);
	OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_mlkem1024(void);

	// EVP_kem_dhkem_* implement DHKEM variants defined in RFC 9180.
	OPENSSL_EXPORT const EVP_KEM *EVP_kem_dhkem_p256_hkdf_sha256(void);
	OPENSSL_EXPORT const EVP_KEM *EVP_kem_dhkem_x25519_hkdf_sha256(void);

	// EVP_HPKE_KEM_id returns the HPKE KEM identifier for `kem`, which
	// will be one of the `EVP_HPKE_KEM_*` constants.
	OPENSSL_EXPORT uint16_t EVP_HPKE_KEM_id(const EVP_HPKE_KEM *kem);

	// EVP_HPKE_MAX_PUBLIC_KEY_LENGTH is the maximum length of an encoded public key
	// for all KEMs currently supported by this library.
	#define EVP_HPKE_MAX_PUBLIC_KEY_LENGTH 1568

	// EVP_HPKE_KEM_public_key_len returns the length of a public key for `kem`.
	// This value will be at most `EVP_HPKE_MAX_PUBLIC_KEY_LENGTH`.
	OPENSSL_EXPORT size_t EVP_HPKE_KEM_public_key_len(const EVP_HPKE_KEM *kem);

	// EVP_HPKE_MAX_PRIVATE_KEY_LENGTH is the maximum length of an encoded private
	// key for all KEMs currently supported by this library.
	#define EVP_HPKE_MAX_PRIVATE_KEY_LENGTH 64

	// EVP_HPKE_KEM_private_key_len returns the length of a private key for `kem`.
	// This value will be at most `EVP_HPKE_MAX_PRIVATE_KEY_LENGTH`.
	OPENSSL_EXPORT size_t EVP_HPKE_KEM_private_key_len(const EVP_HPKE_KEM *kem);

	// EVP_HPKE_MAX_ENC_LENGTH is the maximum length of "enc", the encapsulated
	// shared secret, for all KEMs currently supported by this library.
	#define EVP_HPKE_MAX_ENC_LENGTH 1568

	// EVP_HPKE_KEM_enc_len returns the length of the "enc", the encapsulated shared
	// secret, for `kem`. This value will be at most `EVP_HPKE_MAX_ENC_LENGTH`.
	OPENSSL_EXPORT size_t EVP_HPKE_KEM_enc_len(const EVP_HPKE_KEM *kem);

	// EVP_HPKE_KEM_shared_secret_len returns the length of the shared secret
	// produced by `kem`.
	OPENSSL_EXPORT size_t EVP_HPKE_KEM_shared_secret_len(const EVP_HPKE_KEM *kem);

	// The following constants are KDF identifiers.
	#define EVP_HPKE_HKDF_SHA256 0x0001
	#define EVP_HPKE_HKDF_SHA384 0x0002

	// The following functions are KDF algorithms which may be used with HPKE. If
	// unsure, use `EVP_hpke_hkdf_sha256`.
	OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(void);
	OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha384(void);

	// EVP_HPKE_KDF_id returns the HPKE KDF identifier for `kdf`.
	OPENSSL_EXPORT uint16_t EVP_HPKE_KDF_id(const EVP_HPKE_KDF *kdf);

	// EVP_HPKE_KDF_hkdf_md returns the HKDF hash function corresponding to `kdf`,
	// or NULL if `kdf` is not an HKDF-based KDF. All currently supported KDFs are
	// HKDF-based.
	OPENSSL_EXPORT const EVP_MD EVP_HPKE_KDF_hkdf_md(const EVP_HPKE_KDF kdf);

	// The following constants are AEAD identifiers.
	#define EVP_HPKE_AES_128_GCM 0x0001
	#define EVP_HPKE_AES_256_GCM 0x0002
	#define EVP_HPKE_CHACHA20_POLY1305 0x0003

	// The following functions are AEAD algorithms which may be used with HPKE.
	OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_128_gcm(void);
	OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_256_gcm(void);
	OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_chacha20_poly1305(void);

	// EVP_HPKE_AEAD_id returns the HPKE AEAD identifier for `aead`.
	OPENSSL_EXPORT uint16_t EVP_HPKE_AEAD_id(const EVP_HPKE_AEAD *aead);

	// EVP_HPKE_AEAD_aead returns the `EVP_AEAD` corresponding to `aead`.
	OPENSSL_EXPORT const EVP_AEAD EVP_HPKE_AEAD_aead(const EVP_HPKE_AEAD aead);


	// Recipient keys.
	//
	// An HPKE recipient maintains a long-term KEM key. This library represents keys
	// with the `EVP_HPKE_KEY` type.

	// EVP_HPKE_KEY_zero sets an uninitialized `EVP_HPKE_KEY` to the zero state. The
	// caller should then use `EVP_HPKE_KEY_init`, `EVP_HPKE_KEY_copy`, or
	// `EVP_HPKE_KEY_generate` to finish initializing `key`.
	//
	// It is safe, but not necessary to call `EVP_HPKE_KEY_cleanup` in this state.
	// This may be used for more uniform cleanup of `EVP_HPKE_KEY`.
	OPENSSL_EXPORT void EVP_HPKE_KEY_zero(EVP_HPKE_KEY *key);

	// EVP_HPKE_KEY_cleanup releases memory referenced by `key`.
	OPENSSL_EXPORT void EVP_HPKE_KEY_cleanup(EVP_HPKE_KEY *key);

	// EVP_HPKE_KEY_new returns a newly-allocated `EVP_HPKE_KEY`, or NULL on error.
	// The caller must call `EVP_HPKE_KEY_free` on the result to release it.
	//
	// This is a convenience function for callers that need a heap-allocated
	// `EVP_HPKE_KEY`.
	OPENSSL_EXPORT EVP_HPKE_KEY *EVP_HPKE_KEY_new(void);

	// EVP_HPKE_KEY_free releases memory associated with `key`, which must have been
	// created with `EVP_HPKE_KEY_new`.
	OPENSSL_EXPORT void EVP_HPKE_KEY_free(EVP_HPKE_KEY *key);

	// EVP_HPKE_KEY_copy sets `dst` to a copy of `src`. It returns one on success
	// and zero on error. On success, the caller must call `EVP_HPKE_KEY_cleanup` to
	// release `dst`. On failure, calling `EVP_HPKE_KEY_cleanup` is safe, but not
	// necessary.
	OPENSSL_EXPORT int EVP_HPKE_KEY_copy(EVP_HPKE_KEY *dst,
	const EVP_HPKE_KEY *src);

	// EVP_HPKE_KEY_move sets `out`, which must be initialized or in the zero state,
	// to the key in `in`. `in` is mutated and left in the zero state.
	OPENSSL_EXPORT void EVP_HPKE_KEY_move(EVP_HPKE_KEY out, EVP_HPKE_KEY in);

	// EVP_HPKE_KEY_init decodes `priv_key` as a private key for `kem` and
	// initializes `key` with the result. It returns one on success and zero if
	// `priv_key` was invalid. On success, the caller must call
	// `EVP_HPKE_KEY_cleanup` to release the key. On failure, calling
	// `EVP_HPKE_KEY_cleanup` is safe, but not necessary.
	OPENSSL_EXPORT int EVP_HPKE_KEY_init(EVP_HPKE_KEY key, const EVP_HPKE_KEM kem,
	const uint8_t *priv_key,
	size_t priv_key_len);

	// EVP_HPKE_KEY_generate sets `key` to a newly-generated key using `kem`.
	OPENSSL_EXPORT int EVP_HPKE_KEY_generate(EVP_HPKE_KEY *key,
	const EVP_HPKE_KEM *kem);

	// EVP_HPKE_KEY_derive deterministically derives a key from `ikm` for use with
	// `kem` and initializes `key` with the result. It returns one on success and
	// zero on error. This corresponds to the DeriveKeyPair operation in RFC 9180.
	OPENSSL_EXPORT int EVP_HPKE_KEY_derive(EVP_HPKE_KEY *key,
	const EVP_HPKE_KEM *kem,
	const uint8_t *ikm, size_t ikm_len);

	// EVP_HPKE_KEY_kem returns the HPKE KEM used by `key`.
	OPENSSL_EXPORT const EVP_HPKE_KEM EVP_HPKE_KEY_kem(const EVP_HPKE_KEY key);

	// EVP_HPKE_KEY_public_key writes `key`'s public key to `out` and sets
	// `*out_len` to the number of bytes written. On success, it returns one and
	// writes at most `max_out` bytes. If `max_out` is too small, it returns zero.
	// Setting `max_out` to `EVP_HPKE_MAX_PUBLIC_KEY_LENGTH` will ensure the public
	// key fits. An exact size can also be determined by
	// `EVP_HPKE_KEM_public_key_len`.
	OPENSSL_EXPORT int EVP_HPKE_KEY_public_key(const EVP_HPKE_KEY *key,
	uint8_t out, size_t out_len,
	size_t max_out);

	// EVP_HPKE_KEY_private_key writes `key`'s private key to `out` and sets
	// `*out_len` to the number of bytes written. On success, it returns one and
	// writes at most `max_out` bytes. If `max_out` is too small, it returns zero.
	// Setting `max_out` to `EVP_HPKE_MAX_PRIVATE_KEY_LENGTH` will ensure the
	// private key fits. An exact size can also be determined by
	// `EVP_HPKE_KEM_private_key_len`.
	OPENSSL_EXPORT int EVP_HPKE_KEY_private_key(const EVP_HPKE_KEY *key,
	uint8_t out, size_t out_len,
	size_t max_out);


	// Encryption contexts.
	//
	// An HPKE encryption context is represented by the `EVP_HPKE_CTX` type.

	// EVP_HPKE_CTX_zero sets an uninitialized `EVP_HPKE_CTX` to the zero state. The
	// caller should then use one of the `EVP_HPKE_CTX_setup_*` functions to finish
	// setting up `ctx`.
	//
	// It is safe, but not necessary to call `EVP_HPKE_CTX_cleanup` in this state.
	// This may be used for more uniform cleanup of `EVP_HPKE_CTX`.
	OPENSSL_EXPORT void EVP_HPKE_CTX_zero(EVP_HPKE_CTX *ctx);

	// EVP_HPKE_CTX_cleanup releases memory referenced by `ctx`. `ctx` must have
	// been initialized with `EVP_HPKE_CTX_zero` or one of the
	// `EVP_HPKE_CTX_setup_*` functions.
	OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx);

	// EVP_HPKE_CTX_new returns a newly-allocated `EVP_HPKE_CTX`, or NULL on error.
	// The caller must call `EVP_HPKE_CTX_free` on the result to release it.
	//
	// This is a convenience function for callers that need a heap-allocated
	// `EVP_HPKE_CTX`.
	OPENSSL_EXPORT EVP_HPKE_CTX *EVP_HPKE_CTX_new(void);

	// EVP_HPKE_CTX_free releases memory associated with `ctx`, which must have been
	// created with `EVP_HPKE_CTX_new`.
	OPENSSL_EXPORT void EVP_HPKE_CTX_free(EVP_HPKE_CTX *ctx);

	// EVP_HPKE_CTX_setup_sender implements the SetupBaseS HPKE operation. It
	// encapsulates a shared secret for `peer_public_key` and sets up `ctx` as a
	// sender context. It writes the encapsulated shared secret to `out_enc` and
	// sets `*out_enc_len` to the number of bytes written. It writes at most
	// `max_enc` bytes and fails if the buffer is too small. Setting `max_enc` to at
	// least `EVP_HPKE_MAX_ENC_LENGTH` will ensure the buffer is large enough. An
	// exact size may also be determined by `EVP_HPKE_KEM_enc_len`.
	//
	// This function returns one on success and zero on error. Note that
	// `peer_public_key` may be invalid, in which case this function will return an
	// error.
	//
	// On success, callers may call `EVP_HPKE_CTX_seal` to encrypt messages for the
	// recipient. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On
	// failure, calling `EVP_HPKE_CTX_cleanup` is safe, but not required.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender(
	EVP_HPKE_CTX ctx, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KEM kem, const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD *aead,
	const uint8_t *peer_public_key, size_t peer_public_key_len,
	const uint8_t *info, size_t info_len);

	// EVP_HPKE_CTX_setup_sender_with_seed_for_testing behaves like
	// `EVP_HPKE_CTX_setup_sender`, but takes a seed to behave deterministically.
	// The seed's format depends on `kem`. For X25519, it is the sender's
	// ephemeral private key. For P256, it's an HKDF input.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender_with_seed_for_testing(
	EVP_HPKE_CTX ctx, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KEM kem, const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD *aead,
	const uint8_t *peer_public_key, size_t peer_public_key_len,
	const uint8_t info, size_t info_len, const uint8_t seed, size_t seed_len);

	// EVP_HPKE_CTX_setup_recipient implements the SetupBaseR HPKE operation. It
	// decapsulates the shared secret in `enc` with `key` and sets up `ctx` as a
	// recipient context. It returns one on success and zero on failure. Note that
	// `enc` may be invalid, in which case this function will return an error.
	//
	// On success, callers may call `EVP_HPKE_CTX_open` to decrypt messages from the
	// sender. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On failure,
	// calling `EVP_HPKE_CTX_cleanup` is safe, but not required.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient(
	EVP_HPKE_CTX ctx, const EVP_HPKE_KEY key, const EVP_HPKE_KDF *kdf,
	const EVP_HPKE_AEAD aead, const uint8_t enc, size_t enc_len,
	const uint8_t *info, size_t info_len);

	// EVP_HPKE_CTX_setup_recipient_with_shared_secret behaves like
	// `EVP_HPKE_CTX_setup_recipient`, but takes the shared secret explicitly.
	//
	// WARNING: `shared_secret` must be the result of decapsulating the sender's
	// `enc` value with the recipient's private key. Using the wrong shared secret
	// will result in an `EVP_HPKE_CTX` that cannot decrypt the sender's messages.
	// Additionally, an attacker with knowledge of `shared_secret` will be able to
	// decrypt and forge encrypted messages.
	//
	// It returns one on success and zero on error.
	//
	// On success, callers may call `EVP_HPKE_CTX_open` to decrypt messages from the
	// sender. Callers must then call `EVP_HPKE_CTX_cleanup` when done. On failure,
	// calling `EVP_HPKE_CTX_cleanup` is safe, but not required.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient_with_shared_secret(
	EVP_HPKE_CTX ctx, const EVP_HPKE_KEM kem, const EVP_HPKE_KDF *kdf,
	const EVP_HPKE_AEAD aead, const uint8_t shared_secret,
	size_t shared_secret_len, const uint8_t *info, size_t info_len);

	// EVP_HPKE_CTX_setup_auth_sender implements the SetupAuthS HPKE operation. It
	// behaves like `EVP_HPKE_CTX_setup_sender` but authenticates the resulting
	// context with `key`.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_sender(
	EVP_HPKE_CTX ctx, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KEY key, const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD *aead,
	const uint8_t *peer_public_key, size_t peer_public_key_len,
	const uint8_t *info, size_t info_len);

	// EVP_HPKE_CTX_setup_auth_sender_with_seed_for_testing behaves like
	// `EVP_HPKE_CTX_setup_auth_sender`, but takes a seed to behave
	// deterministically. The seed's format depends on `kem`. For X25519, it is the
	// sender's ephemeral private key. For P256, it's an HKDF input.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_sender_with_seed_for_testing(
	EVP_HPKE_CTX ctx, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KEY key, const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD *aead,
	const uint8_t *peer_public_key, size_t peer_public_key_len,
	const uint8_t info, size_t info_len, const uint8_t seed, size_t seed_len);

	// EVP_HPKE_CTX_setup_auth_recipient implements the SetupAuthR HPKE operation.
	// It behaves like `EVP_HPKE_CTX_setup_recipient` but checks the resulting
	// context was authenticated with `peer_public_key`.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_auth_recipient(
	EVP_HPKE_CTX ctx, const EVP_HPKE_KEY key, const EVP_HPKE_KDF *kdf,
	const EVP_HPKE_AEAD aead, const uint8_t enc, size_t enc_len,
	const uint8_t info, size_t info_len, const uint8_t peer_public_key,
	size_t peer_public_key_len);


	// Using an HPKE context.
	//
	// Once set up, callers may encrypt or decrypt with an `EVP_HPKE_CTX` using the
	// following functions.

	// EVP_HPKE_CTX_open uses the HPKE context `ctx` to authenticate `in_len` bytes
	// from `in` and `ad_len` bytes from `ad` and to decrypt at most `in_len` bytes
	// into `out`. It returns one on success, and zero otherwise.
	//
	// This operation will fail if the `ctx` context is not set up as a receiver.
	//
	// Note that HPKE encryption is stateful and ordered. The sender's first call to
	// `EVP_HPKE_CTX_seal` must correspond to the recipient's first call to
	// `EVP_HPKE_CTX_open`, etc.
	//
	// At most `in_len` bytes are written to `out`. In order to ensure success,
	// `max_out_len` should be at least `in_len`. On successful return, `*out_len`
	// is set to the actual number of bytes written.
	OPENSSL_EXPORT int EVP_HPKE_CTX_open(EVP_HPKE_CTX ctx, uint8_t out,
	size_t *out_len, size_t max_out_len,
	const uint8_t *in, size_t in_len,
	const uint8_t *ad, size_t ad_len);

	// EVP_HPKE_CTX_seal uses the HPKE context `ctx` to encrypt and authenticate
	// `in_len` bytes of ciphertext `in` and authenticate `ad_len` bytes from `ad`,
	// writing the result to `out`. It returns one on success and zero otherwise.
	//
	// This operation will fail if the `ctx` context is not set up as a sender.
	//
	// Note that HPKE encryption is stateful and ordered. The sender's first call to
	// `EVP_HPKE_CTX_seal` must correspond to the recipient's first call to
	// `EVP_HPKE_CTX_open`, etc.
	//
	// At most, `max_out_len` encrypted bytes are written to `out`. On successful
	// return, `*out_len` is set to the actual number of bytes written.
	//
	// To ensure success, `max_out_len` should be `in_len` plus the result of
	// `EVP_HPKE_CTX_max_overhead` or `EVP_HPKE_MAX_OVERHEAD`.
	OPENSSL_EXPORT int EVP_HPKE_CTX_seal(EVP_HPKE_CTX ctx, uint8_t out,
	size_t *out_len, size_t max_out_len,
	const uint8_t *in, size_t in_len,
	const uint8_t *ad, size_t ad_len);

	// EVP_HPKE_CTX_export uses the HPKE context `ctx` to export a secret of
	// `secret_len` bytes into `out`. This function uses `context_len` bytes from
	// `context` as a context string for the secret. This is necessary to separate
	// different uses of exported secrets and bind relevant caller-specific context
	// into the output. It returns one on success and zero otherwise.
	OPENSSL_EXPORT int EVP_HPKE_CTX_export(const EVP_HPKE_CTX ctx, uint8_t out,
	size_t secret_len,
	const uint8_t *context,
	size_t context_len);

	// EVP_HPKE_MAX_OVERHEAD contains the largest value that
	// `EVP_HPKE_CTX_max_overhead` would ever return for any context.
	#define EVP_HPKE_MAX_OVERHEAD EVP_AEAD_MAX_OVERHEAD

	// EVP_HPKE_CTX_max_overhead returns the maximum number of additional bytes
	// added by sealing data with `EVP_HPKE_CTX_seal`. The `ctx` context must be set
	// up as a sender.
	OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *ctx);

	// EVP_HPKE_CTX_kem returns `ctx`'s configured KEM, or NULL if the context has
	// not been set up.
	OPENSSL_EXPORT const EVP_HPKE_KEM EVP_HPKE_CTX_kem(const EVP_HPKE_CTX ctx);

	// EVP_HPKE_CTX_aead returns `ctx`'s configured AEAD, or NULL if the context has
	// not been set up.
	OPENSSL_EXPORT const EVP_HPKE_AEAD EVP_HPKE_CTX_aead(const EVP_HPKE_CTX ctx);

	// EVP_HPKE_CTX_kdf returns `ctx`'s configured KDF, or NULL if the context has
	// not been set up.
	OPENSSL_EXPORT const EVP_HPKE_KDF EVP_HPKE_CTX_kdf(const EVP_HPKE_CTX ctx);


	// Private structures.
	//
	// The following structures are exported so their types are stack-allocatable,
	// but accessing or modifying their fields is forbidden.

	struct evp_hpke_ctx_st {
	const EVP_HPKE_KEM *kem;
	const EVP_HPKE_AEAD *aead;
	const EVP_HPKE_KDF *kdf;
	EVP_AEAD_CTX aead_ctx;
	uint8_t base_nonce[EVP_AEAD_MAX_NONCE_LENGTH];
	uint8_t exporter_secret[EVP_MAX_MD_SIZE];
	uint64_t seq;
	int is_sender;
	};

	struct evp_hpke_key_st {
	const EVP_HPKE_KEM *kem;
	uint8_t private_key[EVP_HPKE_MAX_PRIVATE_KEY_LENGTH];
	uint8_t public_key[EVP_HPKE_MAX_PUBLIC_KEY_LENGTH];

	// `pkey`, if non-null, takes precedence over `private_key` and `public_key`,
	// which are left unused. Otherwise `private_key` and `public_key` are used
	// instead.
	// TODO(crbug.com/535883377): Unify EVP_HPKE_KEM and EVP_KEM for all supported
	// HPKE KEMs.
	EVP_PKEY *pkey;
	};


	#if defined(__cplusplus)
	} // extern C
	#endif

	#if !defined(BORINGSSL_NO_CXX)
	extern "C++" {

	BSSL_NAMESPACE_BEGIN

	BORINGSSL_MAKE_STACK_TRAITS(EVP_HPKE_CTX, EVP_HPKE_CTX_zero,
	EVP_HPKE_CTX_cleanup)
	using ScopedEVP_HPKE_CTX = internal::StackAllocated<EVP_HPKE_CTX>;

	BORINGSSL_MAKE_STACK_TRAITS_MOVABLE(EVP_HPKE_KEY, EVP_HPKE_KEY_zero,
	EVP_HPKE_KEY_cleanup, EVP_HPKE_KEY_move)
	using ScopedEVP_HPKE_KEY = internal::StackAllocatedMovable<EVP_HPKE_KEY>;

	BORINGSSL_MAKE_DELETER(EVP_HPKE_CTX, EVP_HPKE_CTX_free)
	BORINGSSL_MAKE_DELETER(EVP_HPKE_KEY, EVP_HPKE_KEY_free)

	BSSL_NAMESPACE_END

	} // extern C++
	#endif

	#endif // OPENSSL_HEADER_HPKE_H