// 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_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);

// 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_PKEY_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_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];
};


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

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

BSSL_NAMESPACE_BEGIN

using ScopedEVP_HPKE_CTX =
    internal::StackAllocated<EVP_HPKE_CTX, void, EVP_HPKE_CTX_zero,
                             EVP_HPKE_CTX_cleanup>;
using ScopedEVP_HPKE_KEY =
    internal::StackAllocatedMovable<EVP_HPKE_KEY, void, EVP_HPKE_KEY_zero,
                                    EVP_HPKE_KEY_cleanup, EVP_HPKE_KEY_move>;

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