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 // EVP_HPKE_MAX_PUBLIC_KEY_LENGTH is the maximum length of an encoded public key 55 // for all KEMs currently supported by this library. 56 #define EVP_HPKE_MAX_PUBLIC_KEY_LENGTH 32 57 58 // EVP_HPKE_KEM_public_key_len returns the length of a public key for |kem|. 59 // This value will be at most |EVP_HPKE_MAX_PUBLIC_KEY_LENGTH|. 60 OPENSSL_EXPORT size_t EVP_HPKE_KEM_public_key_len(const EVP_HPKE_KEM *kem); 61 62 // EVP_HPKE_MAX_PRIVATE_KEY_LENGTH is the maximum length of an encoded private 63 // key for all KEMs currently supported by this library. 64 #define EVP_HPKE_MAX_PRIVATE_KEY_LENGTH 32 65 66 // EVP_HPKE_KEM_private_key_len returns the length of a private key for |kem|. 67 // This value will be at most |EVP_HPKE_MAX_PRIVATE_KEY_LENGTH|. 68 OPENSSL_EXPORT size_t EVP_HPKE_KEM_private_key_len(const EVP_HPKE_KEM *kem); 69 70 // EVP_HPKE_MAX_ENC_LENGTH is the maximum length of "enc", the encapsulated 71 // shared secret, for all KEMs currently supported by this library. 72 #define EVP_HPKE_MAX_ENC_LENGTH 32 73 74 // EVP_HPKE_KEM_enc_len returns the length of the "enc", the encapsulated shared 75 // secret, for |kem|. This value will be at most |EVP_HPKE_MAX_ENC_LENGTH|. 76 OPENSSL_EXPORT size_t EVP_HPKE_KEM_enc_len(const EVP_HPKE_KEM *kem); 77 78 // The following constants are KDF identifiers. 79 #define EVP_HPKE_HKDF_SHA256 0x0001 80 81 // The following functions are KDF algorithms which may be used with HPKE. 82 OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_hpke_hkdf_sha256(void); 83 84 // EVP_HPKE_KDF_id returns the HPKE KDF identifier for |kdf|. 85 OPENSSL_EXPORT uint16_t EVP_HPKE_KDF_id(const EVP_HPKE_KDF *kdf); 86 87 // EVP_HPKE_KDF_hkdf_md returns the HKDF hash function corresponding to |kdf|, 88 // or NULL if |kdf| is not an HKDF-based KDF. All currently supported KDFs are 89 // HKDF-based. 90 OPENSSL_EXPORT const EVP_MD *EVP_HPKE_KDF_hkdf_md(const EVP_HPKE_KDF *kdf); 91 92 // The following constants are AEAD identifiers. 93 #define EVP_HPKE_AES_128_GCM 0x0001 94 #define EVP_HPKE_AES_256_GCM 0x0002 95 #define EVP_HPKE_CHACHA20_POLY1305 0x0003 96 97 // The following functions are AEAD algorithms which may be used with HPKE. 98 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_128_gcm(void); 99 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_aes_256_gcm(void); 100 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_hpke_chacha20_poly1305(void); 101 102 // EVP_HPKE_AEAD_id returns the HPKE AEAD identifier for |aead|. 103 OPENSSL_EXPORT uint16_t EVP_HPKE_AEAD_id(const EVP_HPKE_AEAD *aead); 104 105 // EVP_HPKE_AEAD_aead returns the |EVP_AEAD| corresponding to |aead|. 106 OPENSSL_EXPORT const EVP_AEAD *EVP_HPKE_AEAD_aead(const EVP_HPKE_AEAD *aead); 107 108 109 // Recipient keys. 110 // 111 // An HPKE recipient maintains a long-term KEM key. This library represents keys 112 // with the |EVP_HPKE_KEY| type. 113 114 // EVP_HPKE_KEY_zero sets an uninitialized |EVP_HPKE_KEY| to the zero state. The 115 // caller should then use |EVP_HPKE_KEY_init|, |EVP_HPKE_KEY_copy|, or 116 // |EVP_HPKE_KEY_generate| to finish initializing |key|. 117 // 118 // It is safe, but not necessary to call |EVP_HPKE_KEY_cleanup| in this state. 119 // This may be used for more uniform cleanup of |EVP_HPKE_KEY|. 120 OPENSSL_EXPORT void EVP_HPKE_KEY_zero(EVP_HPKE_KEY *key); 121 122 // EVP_HPKE_KEY_cleanup releases memory referenced by |key|. 123 OPENSSL_EXPORT void EVP_HPKE_KEY_cleanup(EVP_HPKE_KEY *key); 124 125 // EVP_HPKE_KEY_new returns a newly-allocated |EVP_HPKE_KEY|, or NULL on error. 126 // The caller must call |EVP_HPKE_KEY_free| on the result to release it. 127 // 128 // This is a convenience function for callers that need a heap-allocated 129 // |EVP_HPKE_KEY|. 130 OPENSSL_EXPORT EVP_HPKE_KEY *EVP_HPKE_KEY_new(void); 131 132 // EVP_HPKE_KEY_free releases memory associated with |key|, which must have been 133 // created with |EVP_HPKE_KEY_new|. 134 OPENSSL_EXPORT void EVP_HPKE_KEY_free(EVP_HPKE_KEY *key); 135 136 // EVP_HPKE_KEY_copy sets |dst| to a copy of |src|. It returns one on success 137 // and zero on error. On success, the caller must call |EVP_HPKE_KEY_cleanup| to 138 // release |dst|. On failure, calling |EVP_HPKE_KEY_cleanup| is safe, but not 139 // necessary. 140 OPENSSL_EXPORT int EVP_HPKE_KEY_copy(EVP_HPKE_KEY *dst, 141 const EVP_HPKE_KEY *src); 142 143 // EVP_HPKE_KEY_init decodes |priv_key| as a private key for |kem| and 144 // initializes |key| with the result. It returns one on success and zero if 145 // |priv_key| was invalid. On success, the caller must call 146 // |EVP_HPKE_KEY_cleanup| to release the key. On failure, calling 147 // |EVP_HPKE_KEY_cleanup| is safe, but not necessary. 148 OPENSSL_EXPORT int EVP_HPKE_KEY_init(EVP_HPKE_KEY *key, const EVP_HPKE_KEM *kem, 149 const uint8_t *priv_key, 150 size_t priv_key_len); 151 152 // EVP_HPKE_KEY_generate sets |key| to a newly-generated key using |kem|. 153 OPENSSL_EXPORT int EVP_HPKE_KEY_generate(EVP_HPKE_KEY *key, 154 const EVP_HPKE_KEM *kem); 155 156 // EVP_HPKE_KEY_kem returns the HPKE KEM used by |key|. 157 OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_HPKE_KEY_kem(const EVP_HPKE_KEY *key); 158 159 // EVP_HPKE_KEY_public_key writes |key|'s public key to |out| and sets 160 // |*out_len| to the number of bytes written. On success, it returns one and 161 // writes at most |max_out| bytes. If |max_out| is too small, it returns zero. 162 // Setting |max_out| to |EVP_HPKE_MAX_PUBLIC_KEY_LENGTH| will ensure the public 163 // key fits. An exact size can also be determined by 164 // |EVP_HPKE_KEM_public_key_len|. 165 OPENSSL_EXPORT int EVP_HPKE_KEY_public_key(const EVP_HPKE_KEY *key, 166 uint8_t *out, size_t *out_len, 167 size_t max_out); 168 169 // EVP_HPKE_KEY_private_key writes |key|'s private key to |out| and sets 170 // |*out_len| to the number of bytes written. On success, it returns one and 171 // writes at most |max_out| bytes. If |max_out| is too small, it returns zero. 172 // Setting |max_out| to |EVP_HPKE_MAX_PRIVATE_KEY_LENGTH| will ensure the 173 // private key fits. An exact size can also be determined by 174 // |EVP_HPKE_KEM_private_key_len|. 175 OPENSSL_EXPORT int EVP_HPKE_KEY_private_key(const EVP_HPKE_KEY *key, 176 uint8_t *out, size_t *out_len, 177 size_t max_out); 178 179 180 // Encryption contexts. 181 // 182 // An HPKE encryption context is represented by the |EVP_HPKE_CTX| type. 183 184 // EVP_HPKE_CTX_zero sets an uninitialized |EVP_HPKE_CTX| to the zero state. The 185 // caller should then use one of the |EVP_HPKE_CTX_setup_*| functions to finish 186 // setting up |ctx|. 187 // 188 // It is safe, but not necessary to call |EVP_HPKE_CTX_cleanup| in this state. 189 // This may be used for more uniform cleanup of |EVP_HPKE_CTX|. 190 OPENSSL_EXPORT void EVP_HPKE_CTX_zero(EVP_HPKE_CTX *ctx); 191 192 // EVP_HPKE_CTX_cleanup releases memory referenced by |ctx|. |ctx| must have 193 // been initialized with |EVP_HPKE_CTX_zero| or one of the 194 // |EVP_HPKE_CTX_setup_*| functions. 195 OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx); 196 197 // EVP_HPKE_CTX_new returns a newly-allocated |EVP_HPKE_CTX|, or NULL on error. 198 // The caller must call |EVP_HPKE_CTX_free| on the result to release it. 199 // 200 // This is a convenience function for callers that need a heap-allocated 201 // |EVP_HPKE_CTX|. 202 OPENSSL_EXPORT EVP_HPKE_CTX *EVP_HPKE_CTX_new(void); 203 204 // EVP_HPKE_CTX_free releases memory associated with |ctx|, which must have been 205 // created with |EVP_HPKE_CTX_new|. 206 OPENSSL_EXPORT void EVP_HPKE_CTX_free(EVP_HPKE_CTX *ctx); 207 208 // EVP_HPKE_CTX_setup_sender implements the SetupBaseS HPKE operation. It 209 // encapsulates a shared secret for |peer_public_key| and sets up |ctx| as a 210 // sender context. It writes the encapsulated shared secret to |out_enc| and 211 // sets |*out_enc_len| to the number of bytes written. It writes at most 212 // |max_enc| bytes and fails if the buffer is too small. Setting |max_enc| to at 213 // least |EVP_HPKE_MAX_ENC_LENGTH| will ensure the buffer is large enough. An 214 // exact size may also be determined by |EVP_PKEY_KEM_enc_len|. 215 // 216 // This function returns one on success and zero on error. Note that 217 // |peer_public_key| may be invalid, in which case this function will return an 218 // error. 219 // 220 // On success, callers may call |EVP_HPKE_CTX_seal| to encrypt messages for the 221 // recipient. Callers must then call |EVP_HPKE_CTX_cleanup| when done. On 222 // failure, calling |EVP_HPKE_CTX_cleanup| is safe, but not required. 223 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender( 224 EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc, 225 const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead, 226 const uint8_t *peer_public_key, size_t peer_public_key_len, 227 const uint8_t *info, size_t info_len); 228 229 // EVP_HPKE_CTX_setup_sender_with_seed_for_testing behaves like 230 // |EVP_HPKE_CTX_setup_sender|, but takes a seed to behave deterministically. 231 // The seed's format depends on |kem|. For X25519, it is the sender's 232 // ephemeral private key. 233 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_sender_with_seed_for_testing( 234 EVP_HPKE_CTX *ctx, uint8_t *out_enc, size_t *out_enc_len, size_t max_enc, 235 const EVP_HPKE_KEM *kem, const EVP_HPKE_KDF *kdf, const EVP_HPKE_AEAD *aead, 236 const uint8_t *peer_public_key, size_t peer_public_key_len, 237 const uint8_t *info, size_t info_len, const uint8_t *seed, size_t seed_len); 238 239 // EVP_HPKE_CTX_setup_recipient implements the SetupBaseR HPKE operation. It 240 // decapsulates the shared secret in |enc| with |key| and sets up |ctx| as a 241 // recipient context. It returns one on success and zero on failure. Note that 242 // |enc| may be invalid, in which case this function will return an error. 243 // 244 // On success, callers may call |EVP_HPKE_CTX_open| to decrypt messages from the 245 // sender. Callers must then call |EVP_HPKE_CTX_cleanup| when done. On failure, 246 // calling |EVP_HPKE_CTX_cleanup| is safe, but not required. 247 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_recipient( 248 EVP_HPKE_CTX *ctx, const EVP_HPKE_KEY *key, const EVP_HPKE_KDF *kdf, 249 const EVP_HPKE_AEAD *aead, const uint8_t *enc, size_t enc_len, 250 const uint8_t *info, size_t info_len); 251 252 253 // Using an HPKE context. 254 // 255 // Once set up, callers may encrypt or decrypt with an |EVP_HPKE_CTX| using the 256 // following functions. 257 258 // EVP_HPKE_CTX_open uses the HPKE context |ctx| to authenticate |in_len| bytes 259 // from |in| and |ad_len| bytes from |ad| and to decrypt at most |in_len| bytes 260 // into |out|. It returns one on success, and zero otherwise. 261 // 262 // This operation will fail if the |ctx| context is not set up as a receiver. 263 // 264 // Note that HPKE encryption is stateful and ordered. The sender's first call to 265 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 266 // |EVP_HPKE_CTX_open|, etc. 267 // 268 // At most |in_len| bytes are written to |out|. In order to ensure success, 269 // |max_out_len| should be at least |in_len|. On successful return, |*out_len| 270 // is set to the actual number of bytes written. 271 OPENSSL_EXPORT int EVP_HPKE_CTX_open(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_seal uses the HPKE context |ctx| to encrypt and authenticate 277 // |in_len| bytes of ciphertext |in| and authenticate |ad_len| bytes from |ad|, 278 // writing the result to |out|. It returns one on success and zero otherwise. 279 // 280 // This operation will fail if the |ctx| context is not set up as a sender. 281 // 282 // Note that HPKE encryption is stateful and ordered. The sender's first call to 283 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 284 // |EVP_HPKE_CTX_open|, etc. 285 // 286 // At most, |max_out_len| encrypted bytes are written to |out|. On successful 287 // return, |*out_len| is set to the actual number of bytes written. 288 // 289 // To ensure success, |max_out_len| should be |in_len| plus the result of 290 // |EVP_HPKE_CTX_max_overhead| or |EVP_HPKE_MAX_OVERHEAD|. 291 OPENSSL_EXPORT int EVP_HPKE_CTX_seal(EVP_HPKE_CTX *ctx, uint8_t *out, 292 size_t *out_len, size_t max_out_len, 293 const uint8_t *in, size_t in_len, 294 const uint8_t *ad, size_t ad_len); 295 296 // EVP_HPKE_CTX_export uses the HPKE context |ctx| to export a secret of 297 // |secret_len| bytes into |out|. This function uses |context_len| bytes from 298 // |context| as a context string for the secret. This is necessary to separate 299 // different uses of exported secrets and bind relevant caller-specific context 300 // into the output. It returns one on success and zero otherwise. 301 OPENSSL_EXPORT int EVP_HPKE_CTX_export(const EVP_HPKE_CTX *ctx, uint8_t *out, 302 size_t secret_len, 303 const uint8_t *context, 304 size_t context_len); 305 306 // EVP_HPKE_MAX_OVERHEAD contains the largest value that 307 // |EVP_HPKE_CTX_max_overhead| would ever return for any context. 308 #define EVP_HPKE_MAX_OVERHEAD EVP_AEAD_MAX_OVERHEAD 309 310 // EVP_HPKE_CTX_max_overhead returns the maximum number of additional bytes 311 // added by sealing data with |EVP_HPKE_CTX_seal|. The |ctx| context must be set 312 // up as a sender. 313 OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *ctx); 314 315 // EVP_HPKE_CTX_kem returns |ctx|'s configured KEM, or NULL if the context has 316 // not been set up. 317 OPENSSL_EXPORT const EVP_HPKE_KEM *EVP_HPKE_CTX_kem(const EVP_HPKE_CTX *ctx); 318 319 // EVP_HPKE_CTX_aead returns |ctx|'s configured AEAD, or NULL if the context has 320 // not been set up. 321 OPENSSL_EXPORT const EVP_HPKE_AEAD *EVP_HPKE_CTX_aead(const EVP_HPKE_CTX *ctx); 322 323 // EVP_HPKE_CTX_kdf returns |ctx|'s configured KDF, or NULL if the context has 324 // not been set up. 325 OPENSSL_EXPORT const EVP_HPKE_KDF *EVP_HPKE_CTX_kdf(const EVP_HPKE_CTX *ctx); 326 327 328 // Private structures. 329 // 330 // The following structures are exported so their types are stack-allocatable, 331 // but accessing or modifying their fields is forbidden. 332 333 struct evp_hpke_ctx_st { 334 const EVP_HPKE_KEM *kem; 335 const EVP_HPKE_AEAD *aead; 336 const EVP_HPKE_KDF *kdf; 337 EVP_AEAD_CTX aead_ctx; 338 uint8_t base_nonce[EVP_AEAD_MAX_NONCE_LENGTH]; 339 uint8_t exporter_secret[EVP_MAX_MD_SIZE]; 340 uint64_t seq; 341 int is_sender; 342 }; 343 344 struct evp_hpke_key_st { 345 const EVP_HPKE_KEM *kem; 346 uint8_t private_key[X25519_PRIVATE_KEY_LEN]; 347 uint8_t public_key[X25519_PUBLIC_VALUE_LEN]; 348 }; 349 350 351 #if defined(__cplusplus) 352 } // extern C 353 #endif 354 355 #if !defined(BORINGSSL_NO_CXX) 356 extern "C++" { 357 358 BSSL_NAMESPACE_BEGIN 359 360 using ScopedEVP_HPKE_CTX = 361 internal::StackAllocated<EVP_HPKE_CTX, void, EVP_HPKE_CTX_zero, 362 EVP_HPKE_CTX_cleanup>; 363 using ScopedEVP_HPKE_KEY = 364 internal::StackAllocated<EVP_HPKE_KEY, void, EVP_HPKE_KEY_zero, 365 EVP_HPKE_KEY_cleanup>; 366 367 BORINGSSL_MAKE_DELETER(EVP_HPKE_CTX, EVP_HPKE_CTX_free) 368 BORINGSSL_MAKE_DELETER(EVP_HPKE_KEY, EVP_HPKE_KEY_free) 369 370 BSSL_NAMESPACE_END 371 372 } // extern C++ 373 #endif 374 375 #endif // OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H 376