1 /* Copyright (c) 2020, Google Inc. 2 * 3 * Permission to use, copy, modify, and/or distribute this software for any 4 * purpose with or without fee is hereby granted, provided that the above 5 * copyright notice and this permission notice appear in all copies. 6 * 7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ 14 15 #ifndef OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H 16 #define OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H 17 18 #include <openssl/aead.h> 19 #include <openssl/base.h> 20 #include <openssl/curve25519.h> 21 #include <openssl/digest.h> 22 23 #if defined(__cplusplus) 24 extern "C" { 25 #endif 26 27 28 // Hybrid Public Key Encryption. 29 // 30 // Hybrid Public Key Encryption (HPKE) enables a sender to encrypt messages to a 31 // receiver with a public key. 32 // 33 // See RFC 9180. 34 35 36 // Parameters. 37 // 38 // An HPKE context is parameterized by KEM, KDF, and AEAD algorithms, 39 // represented by |EVP_HPKE_KEM|, |EVP_HPKE_KDF|, and |EVP_HPKE_AEAD| types, 40 // respectively. 41 42 // The following constants are KEM identifiers. 43 #define EVP_HPKE_DHKEM_X25519_HKDF_SHA256 0x0020 44 45 // The following functions are KEM algorithms which may be used with HPKE. Note 46 // that, while some HPKE KEMs use KDFs internally, this is separate from the 47 // |EVP_HPKE_KDF| selection. 48 OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_hpke_x25519_hkdf_sha256(void); 49 50 // EVP_HPKE_KEM_id returns the HPKE KEM identifier for |kem|, which 51 // will be one of the |EVP_HPKE_KEM_*| constants. 52 OPENSSL_EXPORT uint16_t EVP_HPKE_KEM_id(const EVP_HPKE_KEM *kem); 53 54 // The following constants are KDF identifiers. 55 #define EVP_HPKE_HKDF_SHA256 0x0001 56 57 // The following functions are KDF algorithms which may be used with HPKE. 58 OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(void); 59 60 // EVP_HPKE_KDF_id returns the HPKE KDF identifier for |kdf|. 61 OPENSSL_EXPORT uint16_t EVP_HPKE_KDF_id(const EVP_HPKE_KDF *kdf); 62 63 // The following constants are AEAD identifiers. 64 #define EVP_HPKE_AES_128_GCM 0x0001 65 #define EVP_HPKE_AES_256_GCM 0x0002 66 #define EVP_HPKE_CHACHA20_POLY1305 0x0003 67 68 // The following functions are AEAD algorithms which may be used with HPKE. 69 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_128_gcm(void); 70 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_256_gcm(void); 71 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_chacha20_poly1305(void); 72 73 // EVP_HPKE_AEAD_id returns the HPKE AEAD identifier for |aead|. 74 OPENSSL_EXPORT uint16_t EVP_HPKE_AEAD_id(const EVP_HPKE_AEAD *aead); 75 76 // EVP_HPKE_AEAD_aead returns the |EVP_AEAD| corresponding to |aead|. 77 OPENSSL_EXPORT const EVP_AEAD *EVP_HPKE_AEAD_aead(const EVP_HPKE_AEAD *aead); 78 79 80 // Recipient keys. 81 // 82 // An HPKE recipient maintains a long-term KEM key. This library represents keys 83 // with the |EVP_HPKE_KEY| type. 84 85 // EVP_HPKE_KEY_zero sets an uninitialized |EVP_HPKE_KEY| to the zero state. The 86 // caller should then use |EVP_HPKE_KEY_init|, |EVP_HPKE_KEY_copy|, or 87 // |EVP_HPKE_KEY_generate| to finish initializing |key|. 88 // 89 // It is safe, but not necessary to call |EVP_HPKE_KEY_cleanup| in this state. 90 // This may be used for more uniform cleanup of |EVP_HPKE_KEY|. 91 OPENSSL_EXPORT void EVP_HPKE_KEY_zero(EVP_HPKE_KEY *key); 92 93 // EVP_HPKE_KEY_cleanup releases memory referenced by |key|. 94 OPENSSL_EXPORT void EVP_HPKE_KEY_cleanup(EVP_HPKE_KEY *key); 95 96 // EVP_HPKE_KEY_new returns a newly-allocated |EVP_HPKE_KEY|, or NULL on error. 97 // The caller must call |EVP_HPKE_KEY_free| on the result to release it. 98 // 99 // This is a convenience function for callers that need a heap-allocated 100 // |EVP_HPKE_KEY|. 101 OPENSSL_EXPORT EVP_HPKE_KEY *EVP_HPKE_KEY_new(void); 102 103 // EVP_HPKE_KEY_free releases memory associated with |key|, which must have been 104 // created with |EVP_HPKE_KEY_new|. 105 OPENSSL_EXPORT void EVP_HPKE_KEY_free(EVP_HPKE_KEY *key); 106 107 // EVP_HPKE_KEY_copy sets |dst| to a copy of |src|. It returns one on success 108 // and zero on error. On success, the caller must call |EVP_HPKE_KEY_cleanup| to 109 // release |dst|. On failure, calling |EVP_HPKE_KEY_cleanup| is safe, but not 110 // necessary. 111 OPENSSL_EXPORT int EVP_HPKE_KEY_copy(EVP_HPKE_KEY *dst, 112 const EVP_HPKE_KEY *src); 113 114 // EVP_HPKE_KEY_init decodes |priv_key| as a private key for |kem| and 115 // initializes |key| with the result. It returns one on success and zero if 116 // |priv_key| was invalid. On success, the caller must call 117 // |EVP_HPKE_KEY_cleanup| to release the key. On failure, calling 118 // |EVP_HPKE_KEY_cleanup| is safe, but not necessary. 119 OPENSSL_EXPORT int EVP_HPKE_KEY_init(EVP_HPKE_KEY *key, const EVP_HPKE_KEM *kem, 120 const uint8_t *priv_key, 121 size_t priv_key_len); 122 123 // EVP_HPKE_KEY_generate sets |key| to a newly-generated key using |kem|. 124 OPENSSL_EXPORT int EVP_HPKE_KEY_generate(EVP_HPKE_KEY *key, 125 const EVP_HPKE_KEM *kem); 126 127 // EVP_HPKE_KEY_kem returns the HPKE KEM used by |key|. 128 OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_HPKE_KEY_kem(const EVP_HPKE_KEY *key); 129 130 // EVP_HPKE_MAX_PUBLIC_KEY_LENGTH is the maximum length of a public key for all 131 // KEMs supported by this library. 132 #define EVP_HPKE_MAX_PUBLIC_KEY_LENGTH 32 133 134 // EVP_HPKE_KEY_public_key writes |key|'s public key to |out| and sets 135 // |*out_len| to the number of bytes written. On success, it returns one and 136 // writes at most |max_out| bytes. If |max_out| is too small, it returns zero. 137 // Setting |max_out| to |EVP_HPKE_MAX_PUBLIC_KEY_LENGTH| will ensure the public 138 // key fits. 139 OPENSSL_EXPORT int EVP_HPKE_KEY_public_key(const EVP_HPKE_KEY *key, 140 uint8_t *out, size_t *out_len, 141 size_t max_out); 142 143 // EVP_HPKE_MAX_PRIVATE_KEY_LENGTH is the maximum length of a private key for 144 // all KEMs supported by this library. 145 #define EVP_HPKE_MAX_PRIVATE_KEY_LENGTH 32 146 147 // EVP_HPKE_KEY_private_key writes |key|'s private key to |out| and sets 148 // |*out_len| to the number of bytes written. On success, it returns one and 149 // writes at most |max_out| bytes. If |max_out| is too small, it returns zero. 150 // Setting |max_out| to |EVP_HPKE_MAX_PRIVATE_KEY_LENGTH| will ensure the 151 // private key fits. 152 OPENSSL_EXPORT int EVP_HPKE_KEY_private_key(const EVP_HPKE_KEY *key, 153 uint8_t *out, size_t *out_len, 154 size_t max_out); 155 156 157 // Encryption contexts. 158 // 159 // An HPKE encryption context is represented by the |EVP_HPKE_CTX| type. 160 161 // EVP_HPKE_CTX_zero sets an uninitialized |EVP_HPKE_CTX| to the zero state. The 162 // caller should then use one of the |EVP_HPKE_CTX_setup_*| functions to finish 163 // setting up |ctx|. 164 // 165 // It is safe, but not necessary to call |EVP_HPKE_CTX_cleanup| in this state. 166 // This may be used for more uniform cleanup of |EVP_HPKE_CTX|. 167 OPENSSL_EXPORT void EVP_HPKE_CTX_zero(EVP_HPKE_CTX *ctx); 168 169 // EVP_HPKE_CTX_cleanup releases memory referenced by |ctx|. |ctx| must have 170 // been initialized with |EVP_HPKE_CTX_zero| or one of the 171 // |EVP_HPKE_CTX_setup_*| functions. 172 OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx); 173 174 // EVP_HPKE_CTX_new returns a newly-allocated |EVP_HPKE_CTX|, or NULL on error. 175 // The caller must call |EVP_HPKE_CTX_free| on the result to release it. 176 // 177 // This is a convenience function for callers that need a heap-allocated 178 // |EVP_HPKE_CTX|. 179 OPENSSL_EXPORT EVP_HPKE_CTX *EVP_HPKE_CTX_new(void); 180 181 // EVP_HPKE_CTX_free releases memory associated with |ctx|, which must have been 182 // created with |EVP_HPKE_CTX_new|. 183 OPENSSL_EXPORT void EVP_HPKE_CTX_free(EVP_HPKE_CTX *ctx); 184 185 // EVP_HPKE_MAX_ENC_LENGTH is the maximum length of "enc", the encapsulated 186 // shared secret, for all supported KEMs in this library. 187 #define EVP_HPKE_MAX_ENC_LENGTH 32 188 189 // EVP_HPKE_CTX_setup_sender implements the SetupBaseS HPKE operation. It 190 // encapsulates a shared secret for |peer_public_key| and sets up |ctx| as a 191 // sender context. It writes the encapsulated shared secret to |out_enc| and 192 // sets |*out_enc_len| to the number of bytes written. It writes at most 193 // |max_enc| bytes and fails if the buffer is too small. Setting |max_enc| to at 194 // least |EVP_HPKE_MAX_ENC_LENGTH| will ensure the buffer is large enough. 195 // 196 // This function returns one on success and zero on error. Note that 197 // |peer_public_key| may be invalid, in which case this function will return an 198 // error. 199 // 200 // On success, callers may call |EVP_HPKE_CTX_seal| to encrypt messages for the 201 // recipient. Callers must then call |EVP_HPKE_CTX_cleanup| when done. On 202 // failure, calling |EVP_HPKE_CTX_cleanup| is safe, but not required. 203 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender( 204 EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc, 205 const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead, 206 const uint8_t *peer_public_key, size_t peer_public_key_len, 207 const uint8_t *info, size_t info_len); 208 209 // EVP_HPKE_CTX_setup_sender_with_seed_for_testing behaves like 210 // |EVP_HPKE_CTX_setup_sender|, but takes a seed to behave deterministically. 211 // The seed's format depends on |kem|. For X25519, it is the sender's 212 // ephemeral private key. 213 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender_with_seed_for_testing( 214 EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc, 215 const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead, 216 const uint8_t *peer_public_key, size_t peer_public_key_len, 217 const uint8_t *info, size_t info_len, const uint8_t *seed, size_t seed_len); 218 219 // EVP_HPKE_CTX_setup_recipient implements the SetupBaseR HPKE operation. It 220 // decapsulates the shared secret in |enc| with |key| and sets up |ctx| as a 221 // recipient context. It returns one on success and zero on failure. Note that 222 // |enc| may be invalid, in which case this function will return an error. 223 // 224 // On success, callers may call |EVP_HPKE_CTX_open| to decrypt messages from the 225 // sender. Callers must then call |EVP_HPKE_CTX_cleanup| when done. On failure, 226 // calling |EVP_HPKE_CTX_cleanup| is safe, but not required. 227 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient( 228 EVP_HPKE_CTX *ctx, const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf, 229 const EVP_HPKE_AEAD *aead, const uint8_t *enc, size_t enc_len, 230 const uint8_t *info, size_t info_len); 231 232 233 // Using an HPKE context. 234 // 235 // Once set up, callers may encrypt or decrypt with an |EVP_HPKE_CTX| using the 236 // following functions. 237 238 // EVP_HPKE_CTX_open uses the HPKE context |ctx| to authenticate |in_len| bytes 239 // from |in| and |ad_len| bytes from |ad| and to decrypt at most |in_len| bytes 240 // into |out|. It returns one on success, and zero otherwise. 241 // 242 // This operation will fail if the |ctx| context is not set up as a receiver. 243 // 244 // Note that HPKE encryption is stateful and ordered. The sender's first call to 245 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 246 // |EVP_HPKE_CTX_open|, etc. 247 // 248 // At most |in_len| bytes are written to |out|. In order to ensure success, 249 // |max_out_len| should be at least |in_len|. On successful return, |*out_len| 250 // is set to the actual number of bytes written. 251 OPENSSL_EXPORT int EVP_HPKE_CTX_open(EVP_HPKE_CTX *ctx, uint8_t *out, 252 size_t *out_len, size_t max_out_len, 253 const uint8_t *in, size_t in_len, 254 const uint8_t *ad, size_t ad_len); 255 256 // EVP_HPKE_CTX_seal uses the HPKE context |ctx| to encrypt and authenticate 257 // |in_len| bytes of ciphertext |in| and authenticate |ad_len| bytes from |ad|, 258 // writing the result to |out|. It returns one on success and zero otherwise. 259 // 260 // This operation will fail if the |ctx| context is not set up as a sender. 261 // 262 // Note that HPKE encryption is stateful and ordered. The sender's first call to 263 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 264 // |EVP_HPKE_CTX_open|, etc. 265 // 266 // At most, |max_out_len| encrypted bytes are written to |out|. On successful 267 // return, |*out_len| is set to the actual number of bytes written. 268 // 269 // To ensure success, |max_out_len| should be |in_len| plus the result of 270 // |EVP_HPKE_CTX_max_overhead| or |EVP_HPKE_MAX_OVERHEAD|. 271 OPENSSL_EXPORT int EVP_HPKE_CTX_seal(EVP_HPKE_CTX *ctx, uint8_t *out, 272 size_t *out_len, size_t max_out_len, 273 const uint8_t *in, size_t in_len, 274 const uint8_t *ad, size_t ad_len); 275 276 // EVP_HPKE_CTX_export uses the HPKE context |ctx| to export a secret of 277 // |secret_len| bytes into |out|. This function uses |context_len| bytes from 278 // |context| as a context string for the secret. This is necessary to separate 279 // different uses of exported secrets and bind relevant caller-specific context 280 // into the output. It returns one on success and zero otherwise. 281 OPENSSL_EXPORT int EVP_HPKE_CTX_export(const EVP_HPKE_CTX *ctx, uint8_t *out, 282 size_t secret_len, 283 const uint8_t *context, 284 size_t context_len); 285 286 // EVP_HPKE_MAX_OVERHEAD contains the largest value that 287 // |EVP_HPKE_CTX_max_overhead| would ever return for any context. 288 #define EVP_HPKE_MAX_OVERHEAD EVP_AEAD_MAX_OVERHEAD 289 290 // EVP_HPKE_CTX_max_overhead returns the maximum number of additional bytes 291 // added by sealing data with |EVP_HPKE_CTX_seal|. The |ctx| context must be set 292 // up as a sender. 293 OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *ctx); 294 295 // EVP_HPKE_CTX_aead returns |ctx|'s configured AEAD, or NULL if the context has 296 // not been set up. 297 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_HPKE_CTX_aead(const EVP_HPKE_CTX *ctx); 298 299 // EVP_HPKE_CTX_kdf returns |ctx|'s configured KDF, or NULL if the context has 300 // not been set up. 301 OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_HPKE_CTX_kdf(const EVP_HPKE_CTX *ctx); 302 303 304 // Private structures. 305 // 306 // The following structures are exported so their types are stack-allocatable, 307 // but accessing or modifying their fields is forbidden. 308 309 struct evp_hpke_ctx_st { 310 const EVP_HPKE_AEAD *aead; 311 const EVP_HPKE_KDF *kdf; 312 EVP_AEAD_CTX aead_ctx; 313 uint8_t base_nonce[EVP_AEAD_MAX_NONCE_LENGTH]; 314 uint8_t exporter_secret[EVP_MAX_MD_SIZE]; 315 uint64_t seq; 316 int is_sender; 317 }; 318 319 struct evp_hpke_key_st { 320 const EVP_HPKE_KEM *kem; 321 uint8_t private_key[X25519_PRIVATE_KEY_LEN]; 322 uint8_t public_key[X25519_PUBLIC_VALUE_LEN]; 323 }; 324 325 326 #if defined(__cplusplus) 327 } // extern C 328 #endif 329 330 #if !defined(BORINGSSL_NO_CXX) 331 extern "C++" { 332 333 BSSL_NAMESPACE_BEGIN 334 335 using ScopedEVP_HPKE_CTX = 336 internal::StackAllocated<EVP_HPKE_CTX, void, EVP_HPKE_CTX_zero, 337 EVP_HPKE_CTX_cleanup>; 338 using ScopedEVP_HPKE_KEY = 339 internal::StackAllocated<EVP_HPKE_KEY, void, EVP_HPKE_KEY_zero, 340 EVP_HPKE_KEY_cleanup>; 341 342 BORINGSSL_MAKE_DELETER(EVP_HPKE_CTX, EVP_HPKE_CTX_free) 343 BORINGSSL_MAKE_DELETER(EVP_HPKE_KEY, EVP_HPKE_KEY_free) 344 345 BSSL_NAMESPACE_END 346 347 } // extern C++ 348 #endif 349 350 #endif // OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H 351