1 /* Copyright (c) 2014, 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_AEAD_H 16 #define OPENSSL_HEADER_AEAD_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // Authenticated Encryption with Additional Data. 26 // 27 // AEAD couples confidentiality and integrity in a single primitive. AEAD 28 // algorithms take a key and then can seal and open individual messages. Each 29 // message has a unique, per-message nonce and, optionally, additional data 30 // which is authenticated but not included in the ciphertext. 31 // 32 // The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and 33 // performs any precomputation needed to use |aead| with |key|. The length of 34 // the key, |key_len|, is given in bytes. 35 // 36 // The |tag_len| argument contains the length of the tags, in bytes, and allows 37 // for the processing of truncated authenticators. A zero value indicates that 38 // the default tag length should be used and this is defined as 39 // |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using 40 // truncated tags increases an attacker's chance of creating a valid forgery. 41 // Be aware that the attacker's chance may increase more than exponentially as 42 // would naively be expected. 43 // 44 // When no longer needed, the initialised |EVP_AEAD_CTX| structure must be 45 // passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used. 46 // 47 // With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These 48 // operations are intended to meet the standard notions of privacy and 49 // authenticity for authenticated encryption. For formal definitions see 50 // Bellare and Namprempre, "Authenticated encryption: relations among notions 51 // and analysis of the generic composition paradigm," Lecture Notes in Computer 52 // Science B<1976> (2000), 531–545, 53 // http://www-cse.ucsd.edu/~mihir/papers/oem.html. 54 // 55 // When sealing messages, a nonce must be given. The length of the nonce is 56 // fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The 57 // nonce must be unique for all messages with the same key*. This is critically 58 // important - nonce reuse may completely undermine the security of the AEAD. 59 // Nonces may be predictable and public, so long as they are unique. Uniqueness 60 // may be achieved with a simple counter or, if large enough, may be generated 61 // randomly. The nonce must be passed into the "open" operation by the receiver 62 // so must either be implicit (e.g. a counter), or must be transmitted along 63 // with the sealed message. 64 // 65 // The "seal" and "open" operations are atomic - an entire message must be 66 // encrypted or decrypted in a single call. Large messages may have to be split 67 // up in order to accommodate this. When doing so, be mindful of the need not to 68 // repeat nonces and the possibility that an attacker could duplicate, reorder 69 // or drop message chunks. For example, using a single key for a given (large) 70 // message and sealing chunks with nonces counting from zero would be secure as 71 // long as the number of chunks was securely transmitted. (Otherwise an 72 // attacker could truncate the message by dropping chunks from the end.) 73 // 74 // The number of chunks could be transmitted by prefixing it to the plaintext, 75 // for example. This also assumes that no other message would ever use the same 76 // key otherwise the rule that nonces must be unique for a given key would be 77 // violated. 78 // 79 // The "seal" and "open" operations also permit additional data to be 80 // authenticated via the |ad| parameter. This data is not included in the 81 // ciphertext and must be identical for both the "seal" and "open" call. This 82 // permits implicit context to be authenticated but may be empty if not needed. 83 // 84 // The "seal" and "open" operations may work in-place if the |out| and |in| 85 // arguments are equal. Otherwise, if |out| and |in| alias, input data may be 86 // overwritten before it is read. This situation will cause an error. 87 // 88 // The "seal" and "open" operations return one on success and zero on error. 89 90 91 // AEAD algorithms. 92 93 // EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode. 94 // 95 // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it 96 // is specified to take a variable-length nonce, nonces with other lengths are 97 // effectively randomized, which means one must consider collisions. Unless 98 // implementing an existing protocol which has already specified incorrect 99 // parameters, only use 12-byte nonces. 100 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void); 101 102 // EVP_aead_aes_192_gcm is AES-192 in Galois Counter Mode. 103 // 104 // WARNING: AES-192 is superfluous and shouldn't exist. NIST should never have 105 // defined it. Use only when interop with another system requires it, never 106 // de novo. 107 // 108 // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it 109 // is specified to take a variable-length nonce, nonces with other lengths are 110 // effectively randomized, which means one must consider collisions. Unless 111 // implementing an existing protocol which has already specified incorrect 112 // parameters, only use 12-byte nonces. 113 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_192_gcm(void); 114 115 // EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. 116 // 117 // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it 118 // is specified to take a variable-length nonce, nonces with other lengths are 119 // effectively randomized, which means one must consider collisions. Unless 120 // implementing an existing protocol which has already specified incorrect 121 // parameters, only use 12-byte nonces. 122 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void); 123 124 // EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and 125 // Poly1305 as described in RFC 7539. 126 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); 127 128 // EVP_aead_xchacha20_poly1305 is ChaCha20-Poly1305 with an extended nonce that 129 // makes random generation of nonces safe. 130 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xchacha20_poly1305(void); 131 132 // EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for 133 // authentication. The nonce is 12 bytes; the bottom 32-bits are used as the 134 // block counter, thus the maximum plaintext size is 64GB. 135 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); 136 137 // EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for 138 // authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. 139 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void); 140 141 // EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See 142 // https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 143 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_siv(void); 144 145 // EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See 146 // https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 147 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_siv(void); 148 149 // EVP_aead_aes_128_gcm_randnonce is AES-128 in Galois Counter Mode with 150 // internal nonce generation. The 12-byte nonce is appended to the tag 151 // and is generated internally. The "tag", for the purpurses of the API, is thus 152 // 12 bytes larger. The nonce parameter when using this AEAD must be 153 // zero-length. Since the nonce is random, a single key should not be used for 154 // more than 2^32 seal operations. 155 // 156 // Warning: this is for use for FIPS compliance only. It is probably not 157 // suitable for other uses. Using standard AES-GCM AEADs allows one to achieve 158 // the same effect, but gives more control over nonce storage. 159 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_randnonce(void); 160 161 // EVP_aead_aes_256_gcm_randnonce is AES-256 in Galois Counter Mode with 162 // internal nonce generation. The 12-byte nonce is appended to the tag 163 // and is generated internally. The "tag", for the purpurses of the API, is thus 164 // 12 bytes larger. The nonce parameter when using this AEAD must be 165 // zero-length. Since the nonce is random, a single key should not be used for 166 // more than 2^32 seal operations. 167 // 168 // Warning: this is for use for FIPS compliance only. It is probably not 169 // suitable for other uses. Using standard AES-GCM AEADs allows one to achieve 170 // the same effect, but gives more control over nonce storage. 171 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_randnonce(void); 172 173 // EVP_aead_aes_128_ccm_bluetooth is AES-128-CCM with M=4 and L=2 (4-byte tags 174 // and 13-byte nonces), as decribed in the Bluetooth Core Specification v5.0, 175 // Volume 6, Part E, Section 1. 176 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth(void); 177 178 // EVP_aead_aes_128_ccm_bluetooth_8 is AES-128-CCM with M=8 and L=2 (8-byte tags 179 // and 13-byte nonces), as used in the Bluetooth Mesh Networking Specification 180 // v1.0. 181 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth_8(void); 182 183 // EVP_has_aes_hardware returns one if we enable hardware support for fast and 184 // constant-time AES-GCM. 185 OPENSSL_EXPORT int EVP_has_aes_hardware(void); 186 187 188 // Utility functions. 189 190 // EVP_AEAD_key_length returns the length, in bytes, of the keys used by 191 // |aead|. 192 OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); 193 194 // EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce 195 // for |aead|. 196 OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); 197 198 // EVP_AEAD_max_overhead returns the maximum number of additional bytes added 199 // by the act of sealing data with |aead|. 200 OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); 201 202 // EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This 203 // is the largest value that can be passed as |tag_len| to 204 // |EVP_AEAD_CTX_init|. 205 OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); 206 207 208 // AEAD operations. 209 210 union evp_aead_ctx_st_state { 211 uint8_t opaque[580]; 212 uint64_t alignment; 213 }; 214 215 // An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key 216 // and message-independent IV. 217 typedef struct evp_aead_ctx_st { 218 const EVP_AEAD *aead; 219 union evp_aead_ctx_st_state state; 220 // tag_len may contain the actual length of the authentication tag if it is 221 // known at initialization time. 222 uint8_t tag_len; 223 } EVP_AEAD_CTX; 224 225 // EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by 226 // any AEAD defined in this header. 227 #define EVP_AEAD_MAX_KEY_LENGTH 80 228 229 // EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by 230 // any AEAD defined in this header. 231 #define EVP_AEAD_MAX_NONCE_LENGTH 24 232 233 // EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD 234 // defined in this header. 235 #define EVP_AEAD_MAX_OVERHEAD 64 236 237 // EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to 238 // EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should 239 // be used. 240 #define EVP_AEAD_DEFAULT_TAG_LENGTH 0 241 242 // EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be 243 // initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not 244 // necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for 245 // more uniform cleanup of |EVP_AEAD_CTX|. 246 OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx); 247 248 // EVP_AEAD_CTX_new allocates an |EVP_AEAD_CTX|, calls |EVP_AEAD_CTX_init| and 249 // returns the |EVP_AEAD_CTX|, or NULL on error. 250 OPENSSL_EXPORT EVP_AEAD_CTX *EVP_AEAD_CTX_new(const EVP_AEAD *aead, 251 const uint8_t *key, 252 size_t key_len, size_t tag_len); 253 254 // EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on 255 // |ctx|. 256 OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx); 257 258 // EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl| 259 // argument is ignored and should be NULL. Authentication tags may be truncated 260 // by passing a size as |tag_len|. A |tag_len| of zero indicates the default 261 // tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for 262 // readability. 263 // 264 // Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In 265 // the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's 266 // harmless to do so. 267 OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, 268 const uint8_t *key, size_t key_len, 269 size_t tag_len, ENGINE *impl); 270 271 // EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to 272 // call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to 273 // all zeros. 274 OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx); 275 276 // EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and 277 // authenticates |ad_len| bytes from |ad| and writes the result to |out|. It 278 // returns one on success and zero otherwise. 279 // 280 // This function may be called concurrently with itself or any other seal/open 281 // function on the same |EVP_AEAD_CTX|. 282 // 283 // At most |max_out_len| bytes are written to |out| and, in order to ensure 284 // success, |max_out_len| should be |in_len| plus the result of 285 // |EVP_AEAD_max_overhead|. On successful return, |*out_len| is set to the 286 // actual number of bytes written. 287 // 288 // The length of |nonce|, |nonce_len|, must be equal to the result of 289 // |EVP_AEAD_nonce_length| for this AEAD. 290 // 291 // |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is 292 // insufficient, zero will be returned. If any error occurs, |out| will be 293 // filled with zero bytes and |*out_len| set to zero. 294 // 295 // If |in| and |out| alias then |out| must be == |in|. 296 OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out, 297 size_t *out_len, size_t max_out_len, 298 const uint8_t *nonce, size_t nonce_len, 299 const uint8_t *in, size_t in_len, 300 const uint8_t *ad, size_t ad_len); 301 302 // EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes 303 // from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on 304 // success and zero otherwise. 305 // 306 // This function may be called concurrently with itself or any other seal/open 307 // function on the same |EVP_AEAD_CTX|. 308 // 309 // At most |in_len| bytes are written to |out|. In order to ensure success, 310 // |max_out_len| should be at least |in_len|. On successful return, |*out_len| 311 // is set to the the actual number of bytes written. 312 // 313 // The length of |nonce|, |nonce_len|, must be equal to the result of 314 // |EVP_AEAD_nonce_length| for this AEAD. 315 // 316 // |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is 317 // insufficient, zero will be returned. If any error occurs, |out| will be 318 // filled with zero bytes and |*out_len| set to zero. 319 // 320 // If |in| and |out| alias then |out| must be == |in|. 321 OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out, 322 size_t *out_len, size_t max_out_len, 323 const uint8_t *nonce, size_t nonce_len, 324 const uint8_t *in, size_t in_len, 325 const uint8_t *ad, size_t ad_len); 326 327 // EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in| 328 // and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of 329 // ciphertext to |out| and the authentication tag to |out_tag|. It returns one 330 // on success and zero otherwise. 331 // 332 // This function may be called concurrently with itself or any other seal/open 333 // function on the same |EVP_AEAD_CTX|. 334 // 335 // Exactly |in_len| bytes are written to |out|, and up to 336 // |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful 337 // return, |*out_tag_len| is set to the actual number of bytes written to 338 // |out_tag|. 339 // 340 // |extra_in| may point to an additional plaintext input buffer if the cipher 341 // supports it. If present, |extra_in_len| additional bytes of plaintext are 342 // encrypted and authenticated, and the ciphertext is written (before the tag) 343 // to |out_tag|. |max_out_tag_len| must be sized to allow for the additional 344 // |extra_in_len| bytes. 345 // 346 // The length of |nonce|, |nonce_len|, must be equal to the result of 347 // |EVP_AEAD_nonce_length| for this AEAD. 348 // 349 // |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If 350 // |max_out_tag_len| is insufficient, zero will be returned. If any error 351 // occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len| 352 // set to zero. 353 // 354 // If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias 355 // any other argument. 356 OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter( 357 const EVP_AEAD_CTX *ctx, uint8_t *out, 358 uint8_t *out_tag, size_t *out_tag_len, size_t max_out_tag_len, 359 const uint8_t *nonce, size_t nonce_len, 360 const uint8_t *in, size_t in_len, 361 const uint8_t *extra_in, size_t extra_in_len, 362 const uint8_t *ad, size_t ad_len); 363 364 // EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in| 365 // and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of 366 // authentication tag from |in_tag|. If successful, it writes |in_len| bytes of 367 // plaintext to |out|. It returns one on success and zero otherwise. 368 // 369 // This function may be called concurrently with itself or any other seal/open 370 // function on the same |EVP_AEAD_CTX|. 371 // 372 // The length of |nonce|, |nonce_len|, must be equal to the result of 373 // |EVP_AEAD_nonce_length| for this AEAD. 374 // 375 // |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error 376 // occurs, |out| will be filled with zero bytes. 377 // 378 // If |in| and |out| alias then |out| must be == |in|. 379 OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather( 380 const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce, 381 size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag, 382 size_t in_tag_len, const uint8_t *ad, size_t ad_len); 383 384 // EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has 385 // not been set. 386 OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx); 387 388 389 // TLS-specific AEAD algorithms. 390 // 391 // These AEAD primitives do not meet the definition of generic AEADs. They are 392 // all specific to TLS and should not be used outside of that context. They must 393 // be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may 394 // not be used concurrently. Any nonces are used as IVs, so they must be 395 // unpredictable. They only accept an |ad| parameter of length 11 (the standard 396 // TLS one with length omitted). 397 398 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void); 399 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void); 400 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha256_tls(void); 401 402 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void); 403 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void); 404 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha256_tls(void); 405 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha384_tls(void); 406 407 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void); 408 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); 409 410 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_tls(void); 411 412 // EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS 413 // 1.2 nonce construction. 414 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls12(void); 415 416 // EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS 417 // 1.2 nonce construction. 418 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls12(void); 419 420 // EVP_aead_aes_128_gcm_tls13 is AES-128 in Galois Counter Mode using the TLS 421 // 1.3 nonce construction. 422 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls13(void); 423 424 // EVP_aead_aes_256_gcm_tls13 is AES-256 in Galois Counter Mode using the TLS 425 // 1.3 nonce construction. 426 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls13(void); 427 428 429 // Obscure functions. 430 431 // evp_aead_direction_t denotes the direction of an AEAD operation. 432 enum evp_aead_direction_t { 433 evp_aead_open, 434 evp_aead_seal, 435 }; 436 437 // EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal 438 // AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a 439 // given direction. 440 OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction( 441 EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, 442 size_t tag_len, enum evp_aead_direction_t dir); 443 444 // EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and 445 // sets |*out_iv| to point to that many bytes of the current IV. This is only 446 // meaningful for AEADs with implicit IVs (i.e. CBC mode in TLS 1.0). 447 // 448 // It returns one on success or zero on error. 449 OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx, 450 const uint8_t **out_iv, size_t *out_len); 451 452 // EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by 453 // |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one 454 // on success or zero on error. |in_len| and |extra_in_len| must equal the 455 // arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|. 456 OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx, 457 size_t *out_tag_len, 458 const size_t in_len, 459 const size_t extra_in_len); 460 461 462 #if defined(__cplusplus) 463 } // extern C 464 465 #if !defined(BORINGSSL_NO_CXX) 466 extern "C++" { 467 468 BSSL_NAMESPACE_BEGIN 469 470 using ScopedEVP_AEAD_CTX = 471 internal::StackAllocated<EVP_AEAD_CTX, void, EVP_AEAD_CTX_zero, 472 EVP_AEAD_CTX_cleanup>; 473 474 BORINGSSL_MAKE_DELETER(EVP_AEAD_CTX, EVP_AEAD_CTX_free) 475 476 BSSL_NAMESPACE_END 477 478 } // extern C++ 479 #endif 480 481 #endif 482 483 #endif // OPENSSL_HEADER_AEAD_H 484