crypto/hpke/internal.h - boringssl - Git at Google

 /* Copyright (c) 2020, Google Inc.
  *
  * Permission to use, copy, modify, and/or distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
  * copyright notice and this permission notice appear in all copies.
  *
  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */

 #ifndef OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H
 #define OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H

 #include <openssl/aead.h>
 #include <openssl/base.h>
 #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 https://tools.ietf.org/html/draft-irtf-cfrg-hpke-08.


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

 typedef struct evp_hpke_kdf_st EVP_HPKE_KDF;
 typedef struct evp_hpke_aead_st EVP_HPKE_AEAD;

 // The following constants are KEM identifiers.
 #define EVP_HPKE_DHKEM_X25519_HKDF_SHA256 0x0020

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

 // The following functions are KDF algorithms which may be used with HPKE.
 OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(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);

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


 // Encryption contexts.

 // An |EVP_HPKE_CTX| is an HPKE encryption context.
 typedef struct evp_hpke_ctx_st EVP_HPKE_CTX;

 // EVP_HPKE_CTX_init initializes an already-allocated |EVP_HPKE_CTX|. The caller
 // should then use one of the |EVP_HPKE_CTX_setup_*| functions.
 //
 // It is safe, but not necessary to call |EVP_HPKE_CTX_cleanup| in this state.
 OPENSSL_EXPORT void EVP_HPKE_CTX_init(EVP_HPKE_CTX *ctx);

 // EVP_HPKE_CTX_cleanup releases memory referenced by |ctx|. |ctx| must have
 // been initialized with |EVP_HPKE_CTX_init|.
 OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx);


 // Setting up HPKE contexts.

 // EVP_HPKE_CTX_setup_base_s_x25519 sets up |hpke| as a sender context that can
 // encrypt for the private key corresponding to |peer_public_value| (the
 // recipient's public key). It returns one on success, and zero otherwise. Note
 // that this function will fail if |peer_public_value| is invalid.
 //
 // This function 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. |max_enc| must be at least
 // |X25519_PUBLIC_VALUE_LEN| to ensure the buffer is large enough.
 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519(
     EVP_HPKE_CTX *hpke, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,
     const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,
     const uint8_t *peer_public_value, size_t peer_public_value_len,
     const uint8_t *info, size_t info_len);

 // EVP_HPKE_CTX_setup_base_s_x25519_with_seed_for_testing behaves like
 // |EVP_HPKE_CTX_setup_base_s_x25519|, but takes a seed value to behave
 // deterministically. This seed is the sender's ephemeral X25519 key.
 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519_with_seed_for_testing(
     EVP_HPKE_CTX *hpke, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc,
     const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,
     const uint8_t *peer_public_value, size_t peer_public_value_len,
     const uint8_t *info, size_t info_len, const uint8_t *seed, size_t seed_len);

 // EVP_HPKE_CTX_setup_base_r_x25519 sets up |hpke| as a recipient context that
 // can decrypt messages. It returns one on success, and zero otherwise.
 //
 // The recipient's keypair is composed of |public_key| and |private_key|, and
 // |enc| is the encapsulated shared secret from the sender. If |enc| is invalid,
 // this function will fail.
 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_r_x25519(
     EVP_HPKE_CTX *hpke, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead,
     const uint8_t *enc, size_t enc_len, const uint8_t *public_key,
     size_t public_key_len, const uint8_t *private_key, size_t private_key_len,
     const uint8_t *info, size_t info_len);


 // Using an HPKE context.

 // EVP_HPKE_CTX_open uses the HPKE context |hpke| 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 |hpke| 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 *hpke, 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 |hpke| 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 |hpke| 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 *hpke, 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 |hpke| 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 *hpke, 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 |hpke| context must be
 // set up as a sender.
 OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *hpke);

 // EVP_HPKE_CTX_aead returns |hpke|'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 *hpke);

 // EVP_HPKE_CTX_kdf returns |hpke|'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 *hpke);


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


 #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_init,
                              EVP_HPKE_CTX_cleanup>;

 BSSL_NAMESPACE_END

 }  // extern C++
 #endif

 #endif  // OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H
	/* Copyright (c) 2020, Google Inc.
	*
	* Permission to use, copy, modify, and/or distribute this software for any
	* purpose with or without fee is hereby granted, provided that the above
	* copyright notice and this permission notice appear in all copies.
	*
	* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
	* SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
	* OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
	* CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */

	#ifndef OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H
	#define OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H

	#include <openssl/aead.h>
	#include <openssl/base.h>
	#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 https://tools.ietf.org/html/draft-irtf-cfrg-hpke-08.


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

	typedef struct evp_hpke_kdf_st EVP_HPKE_KDF;
	typedef struct evp_hpke_aead_st EVP_HPKE_AEAD;

	// The following constants are KEM identifiers.
	#define EVP_HPKE_DHKEM_X25519_HKDF_SHA256 0x0020

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

	// The following functions are KDF algorithms which may be used with HPKE.
	OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(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);

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


	// Encryption contexts.

	// An \|EVP_HPKE_CTX\| is an HPKE encryption context.
	typedef struct evp_hpke_ctx_st EVP_HPKE_CTX;

	// EVP_HPKE_CTX_init initializes an already-allocated \|EVP_HPKE_CTX\|. The caller
	// should then use one of the \|EVP_HPKE_CTX_setup_*\| functions.
	//
	// It is safe, but not necessary to call \|EVP_HPKE_CTX_cleanup\| in this state.
	OPENSSL_EXPORT void EVP_HPKE_CTX_init(EVP_HPKE_CTX *ctx);

	// EVP_HPKE_CTX_cleanup releases memory referenced by \|ctx\|. \|ctx\| must have
	// been initialized with \|EVP_HPKE_CTX_init\|.
	OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx);


	// Setting up HPKE contexts.

	// EVP_HPKE_CTX_setup_base_s_x25519 sets up \|hpke\| as a sender context that can
	// encrypt for the private key corresponding to \|peer_public_value\| (the
	// recipient's public key). It returns one on success, and zero otherwise. Note
	// that this function will fail if \|peer_public_value\| is invalid.
	//
	// This function 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. \|max_enc\| must be at least
	// \|X25519_PUBLIC_VALUE_LEN\| to ensure the buffer is large enough.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519(
	EVP_HPKE_CTX hpke, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD aead,
	const uint8_t *peer_public_value, size_t peer_public_value_len,
	const uint8_t *info, size_t info_len);

	// EVP_HPKE_CTX_setup_base_s_x25519_with_seed_for_testing behaves like
	// \|EVP_HPKE_CTX_setup_base_s_x25519\|, but takes a seed value to behave
	// deterministically. This seed is the sender's ephemeral X25519 key.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519_with_seed_for_testing(
	EVP_HPKE_CTX hpke, uint8_t out_enc, size_t *out_enc_len, size_t max_enc,
	const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD aead,
	const uint8_t *peer_public_value, size_t peer_public_value_len,
	const uint8_t info, size_t info_len, const uint8_t seed, size_t seed_len);

	// EVP_HPKE_CTX_setup_base_r_x25519 sets up \|hpke\| as a recipient context that
	// can decrypt messages. It returns one on success, and zero otherwise.
	//
	// The recipient's keypair is composed of \|public_key\| and \|private_key\|, and
	// \|enc\| is the encapsulated shared secret from the sender. If \|enc\| is invalid,
	// this function will fail.
	OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_r_x25519(
	EVP_HPKE_CTX hpke, const EVP_HPKE_KDF kdf, const EVP_HPKE_AEAD *aead,
	const uint8_t enc, size_t enc_len, const uint8_t public_key,
	size_t public_key_len, const uint8_t *private_key, size_t private_key_len,
	const uint8_t *info, size_t info_len);


	// Using an HPKE context.

	// EVP_HPKE_CTX_open uses the HPKE context \|hpke\| 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 \|hpke\| 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 hpke, 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 \|hpke\| 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 \|hpke\| 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 hpke, 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 \|hpke\| 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 hpke, 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 \|hpke\| context must be
	// set up as a sender.
	OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *hpke);

	// EVP_HPKE_CTX_aead returns \|hpke\|'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 hpke);

	// EVP_HPKE_CTX_kdf returns \|hpke\|'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 hpke);


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


	#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_init,
	EVP_HPKE_CTX_cleanup>;

	BSSL_NAMESPACE_END

	} // extern C++
	#endif

	#endif // OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H