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. Optionally, the sender may authenticate its 32 // possession of a pre-shared key to the recipient. 33 // 34 // See https://tools.ietf.org/html/draft-irtf-cfrg-hpke-07. 35 36 // EVP_HPKE_AEAD_* are AEAD identifiers. 37 #define EVP_HPKE_AEAD_AES_GCM_128 0x0001 38 #define EVP_HPKE_AEAD_AES_GCM_256 0x0002 39 #define EVP_HPKE_AEAD_CHACHA20POLY1305 0x0003 40 41 // EVP_HPKE_HKDF_* are HKDF identifiers. 42 #define EVP_HPKE_HKDF_SHA256 0x0001 43 #define EVP_HPKE_HKDF_SHA384 0x0002 44 #define EVP_HPKE_HKDF_SHA512 0x0003 45 46 // EVP_HPKE_MAX_OVERHEAD contains the largest value that 47 // |EVP_HPKE_CTX_max_overhead| would ever return for any context. 48 #define EVP_HPKE_MAX_OVERHEAD EVP_AEAD_MAX_OVERHEAD 49 50 51 // Encryption contexts. 52 53 // An |EVP_HPKE_CTX| is an HPKE encryption context. 54 typedef struct evp_hpke_ctx_st { 55 const EVP_MD *hkdf_md; 56 EVP_AEAD_CTX aead_ctx; 57 uint16_t kdf_id; 58 uint16_t aead_id; 59 uint8_t base_nonce[EVP_AEAD_MAX_NONCE_LENGTH]; 60 uint8_t exporter_secret[EVP_MAX_MD_SIZE]; 61 uint64_t seq; 62 int is_sender; 63 } EVP_HPKE_CTX; 64 65 // EVP_HPKE_CTX_init initializes an already-allocated |EVP_HPKE_CTX|. The caller 66 // should then use one of the |EVP_HPKE_CTX_setup_*| functions. 67 // 68 // It is safe, but not necessary to call |EVP_HPKE_CTX_cleanup| in this state. 69 OPENSSL_EXPORT void EVP_HPKE_CTX_init(EVP_HPKE_CTX *ctx); 70 71 // EVP_HPKE_CTX_cleanup releases memory referenced by |ctx|. |ctx| must have 72 // been initialized with |EVP_HPKE_CTX_init|. 73 OPENSSL_EXPORT void EVP_HPKE_CTX_cleanup(EVP_HPKE_CTX *ctx); 74 75 76 // Setting up HPKE contexts. 77 // 78 // In each of the following functions, |hpke| must have been initialized with 79 // |EVP_HPKE_CTX_init|. |kdf_id| selects the KDF for non-KEM HPKE operations and 80 // must be one of the |EVP_HPKE_HKDF_*| constants. |aead_id| selects the AEAD 81 // for the "open" and "seal" operations and must be one of the |EVP_HPKE_AEAD_*| 82 // constants. 83 84 // EVP_HPKE_CTX_setup_base_s_x25519 sets up |hpke| as a sender context that can 85 // encrypt for the private key corresponding to |peer_public_value| (the 86 // recipient's public key). It returns one on success, and zero otherwise. Note 87 // that this function will fail if |peer_public_value| is invalid. 88 // 89 // This function writes the encapsulated shared secret to |out_enc|. 90 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519( 91 EVP_HPKE_CTX *hpke, uint8_t out_enc[X25519_PUBLIC_VALUE_LEN], 92 uint16_t kdf_id, uint16_t aead_id, 93 const uint8_t peer_public_value[X25519_PUBLIC_VALUE_LEN], 94 const uint8_t *info, size_t info_len); 95 96 // EVP_HPKE_CTX_setup_base_s_x25519_for_test behaves like 97 // |EVP_HPKE_CTX_setup_base_s_x25519|, but takes a pre-generated ephemeral 98 // sender key. 99 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_s_x25519_for_test( 100 EVP_HPKE_CTX *hpke, uint16_t kdf_id, uint16_t aead_id, 101 const uint8_t peer_public_value[X25519_PUBLIC_VALUE_LEN], 102 const uint8_t *info, size_t info_len, 103 const uint8_t ephemeral_private[X25519_PRIVATE_KEY_LEN], 104 const uint8_t ephemeral_public[X25519_PUBLIC_VALUE_LEN]); 105 106 // EVP_HPKE_CTX_setup_base_r_x25519 sets up |hpke| as a recipient context that 107 // can decrypt messages. |private_key| is the recipient's private key, and |enc| 108 // is the encapsulated shared secret from the sender. Note that this function 109 // will fail if |enc| is invalid. 110 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_base_r_x25519( 111 EVP_HPKE_CTX *hpke, uint16_t kdf_id, uint16_t aead_id, 112 const uint8_t enc[X25519_PUBLIC_VALUE_LEN], 113 const uint8_t public_key[X25519_PUBLIC_VALUE_LEN], 114 const uint8_t private_key[X25519_PRIVATE_KEY_LEN], const uint8_t *info, 115 size_t info_len); 116 117 // EVP_HPKE_CTX_setup_psk_s_x25519 sets up |hpke| as a sender context that can 118 // encrypt for the private key corresponding to |peer_public_value| (the 119 // recipient's public key) and authenticate its possession of a PSK. It returns 120 // one on success, and zero otherwise. Note that this function will fail if 121 // |peer_public_value| is invalid. 122 // 123 // The PSK and its ID must be provided in |psk| and |psk_id|, respectively. Both 124 // must be nonempty (|psk_len| and |psk_id_len| must be non-zero), or this 125 // function will fail. 126 // 127 // This function writes the encapsulated shared secret to |out_enc|. 128 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_psk_s_x25519( 129 EVP_HPKE_CTX *hpke, uint8_t out_enc[X25519_PUBLIC_VALUE_LEN], 130 uint16_t kdf_id, uint16_t aead_id, 131 const uint8_t peer_public_value[X25519_PUBLIC_VALUE_LEN], 132 const uint8_t *info, size_t info_len, const uint8_t *psk, size_t psk_len, 133 const uint8_t *psk_id, size_t psk_id_len); 134 135 // EVP_HPKE_CTX_setup_psk_s_x25519_for_test behaves like 136 // |EVP_HPKE_CTX_setup_psk_s_x25519|, but takes a pre-generated ephemeral sender 137 // key. 138 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_psk_s_x25519_for_test( 139 EVP_HPKE_CTX *hpke, uint16_t kdf_id, uint16_t aead_id, 140 const uint8_t peer_public_value[X25519_PUBLIC_VALUE_LEN], 141 const uint8_t *info, size_t info_len, const uint8_t *psk, size_t psk_len, 142 const uint8_t *psk_id, size_t psk_id_len, 143 const uint8_t ephemeral_private[X25519_PRIVATE_KEY_LEN], 144 const uint8_t ephemeral_public[X25519_PUBLIC_VALUE_LEN]); 145 146 // EVP_HPKE_CTX_setup_psk_r_x25519 sets up |hpke| as a recipient context that 147 // can decrypt messages. Future open (decrypt) operations will fail if the 148 // sender does not possess the PSK indicated by |psk| and |psk_id|. 149 // |private_key| is the recipient's private key, and |enc| is the encapsulated 150 // shared secret from the sender. If |enc| is invalid, this function will fail. 151 // 152 // The PSK and its ID must be provided in |psk| and |psk_id|, respectively. Both 153 // must be nonempty (|psk_len| and |psk_id_len| must be non-zero), or this 154 // function will fail. 155 OPENSSL_EXPORT int EVP_HPKE_CTX_setup_psk_r_x25519( 156 EVP_HPKE_CTX *hpke, uint16_t kdf_id, uint16_t aead_id, 157 const uint8_t enc[X25519_PUBLIC_VALUE_LEN], 158 const uint8_t public_key[X25519_PUBLIC_VALUE_LEN], 159 const uint8_t private_key[X25519_PRIVATE_KEY_LEN], const uint8_t *info, 160 size_t info_len, const uint8_t *psk, size_t psk_len, const uint8_t *psk_id, 161 size_t psk_id_len); 162 163 164 // Using an HPKE context. 165 166 // EVP_HPKE_CTX_open uses the HPKE context |hpke| to authenticate |in_len| bytes 167 // from |in| and |ad_len| bytes from |ad| and to decrypt at most |in_len| bytes 168 // into |out|. It returns one on success, and zero otherwise. 169 // 170 // This operation will fail if the |hpke| context is not set up as a receiver. 171 // 172 // Note that HPKE encryption is stateful and ordered. The sender's first call to 173 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 174 // |EVP_HPKE_CTX_open|, etc. 175 // 176 // At most |in_len| bytes are written to |out|. In order to ensure success, 177 // |max_out_len| should be at least |in_len|. On successful return, |*out_len| 178 // is set to the actual number of bytes written. 179 OPENSSL_EXPORT int EVP_HPKE_CTX_open(EVP_HPKE_CTX *hpke, uint8_t *out, 180 size_t *out_len, size_t max_out_len, 181 const uint8_t *in, size_t in_len, 182 const uint8_t *ad, size_t ad_len); 183 184 // EVP_HPKE_CTX_seal uses the HPKE context |hpke| to encrypt and authenticate 185 // |in_len| bytes of ciphertext |in| and authenticate |ad_len| bytes from |ad|, 186 // writing the result to |out|. It returns one on success and zero otherwise. 187 // 188 // This operation will fail if the |hpke| context is not set up as a sender. 189 // 190 // Note that HPKE encryption is stateful and ordered. The sender's first call to 191 // |EVP_HPKE_CTX_seal| must correspond to the recipient's first call to 192 // |EVP_HPKE_CTX_open|, etc. 193 // 194 // At most, |max_out_len| encrypted bytes are written to |out|. On successful 195 // return, |*out_len| is set to the actual number of bytes written. 196 // 197 // To ensure success, |max_out_len| should be |in_len| plus the result of 198 // |EVP_HPKE_CTX_max_overhead| or |EVP_HPKE_MAX_OVERHEAD|. 199 OPENSSL_EXPORT int EVP_HPKE_CTX_seal(EVP_HPKE_CTX *hpke, uint8_t *out, 200 size_t *out_len, size_t max_out_len, 201 const uint8_t *in, size_t in_len, 202 const uint8_t *ad, size_t ad_len); 203 204 // EVP_HPKE_CTX_export uses the HPKE context |hpke| to export a secret of 205 // |secret_len| bytes into |out|. This function uses |context_len| bytes from 206 // |context| as a context string for the secret. This is necessary to separate 207 // different uses of exported secrets and bind relevant caller-specific context 208 // into the output. It returns one on success and zero otherwise. 209 OPENSSL_EXPORT int EVP_HPKE_CTX_export(const EVP_HPKE_CTX *hpke, uint8_t *out, 210 size_t secret_len, 211 const uint8_t *context, 212 size_t context_len); 213 214 // EVP_HPKE_CTX_max_overhead returns the maximum number of additional bytes 215 // added by sealing data with |EVP_HPKE_CTX_seal|. The |hpke| context must be 216 // set up as a sender. 217 OPENSSL_EXPORT size_t EVP_HPKE_CTX_max_overhead(const EVP_HPKE_CTX *hpke); 218 219 // EVP_HPKE_get_aead returns the AEAD corresponding to |aead_id|, or NULL if 220 // |aead_id| is not a known AEAD identifier. 221 OPENSSL_EXPORT const EVP_AEAD *EVP_HPKE_get_aead(uint16_t aead_id); 222 223 // EVP_HPKE_get_hkdf_md returns the hash function associated with |kdf_id|, or 224 // NULL if |kdf_id| is not a known KDF identifier that uses HKDF. 225 OPENSSL_EXPORT const EVP_MD *EVP_HPKE_get_hkdf_md(uint16_t kdf_id); 226 227 228 #if defined(__cplusplus) 229 } // extern C 230 #endif 231 232 #if !defined(BORINGSSL_NO_CXX) 233 extern "C++" { 234 235 BSSL_NAMESPACE_BEGIN 236 237 using ScopedEVP_HPKE_CTX = 238 internal::StackAllocated<EVP_HPKE_CTX, void, EVP_HPKE_CTX_init, 239 EVP_HPKE_CTX_cleanup>; 240 241 BSSL_NAMESPACE_END 242 243 } // extern C++ 244 #endif 245 246 #endif // OPENSSL_HEADER_CRYPTO_HPKE_INTERNAL_H 247