aead.h revision fe7cd2122ef131c19c9db15672594fd4f0232496
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) 21extern "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. */ 94OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void); 95 96/* EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. */ 97OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void); 98 99/* EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and 100 * Poly1305 as described in RFC 7539. */ 101OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); 102 103/* EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for 104 * authentication. The nonce is 12 bytes; the bottom 32-bits are used as the 105 * block counter, thus the maximum plaintext size is 64GB. */ 106OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); 107 108/* EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for 109 * authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. */ 110OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void); 111 112/* EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See 113 * https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 */ 114OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_siv(void); 115 116/* EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See 117 * https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 */ 118OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_siv(void); 119 120/* EVP_has_aes_hardware returns one if we enable hardware support for fast and 121 * constant-time AES-GCM. */ 122OPENSSL_EXPORT int EVP_has_aes_hardware(void); 123 124 125/* Utility functions. */ 126 127/* EVP_AEAD_key_length returns the length, in bytes, of the keys used by 128 * |aead|. */ 129OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); 130 131/* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce 132 * for |aead|. */ 133OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); 134 135/* EVP_AEAD_max_overhead returns the maximum number of additional bytes added 136 * by the act of sealing data with |aead|. */ 137OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); 138 139/* EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This 140 * is the largest value that can be passed as |tag_len| to 141 * |EVP_AEAD_CTX_init|. */ 142OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); 143 144 145/* AEAD operations. */ 146 147/* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key 148 * and message-independent IV. */ 149typedef struct evp_aead_ctx_st { 150 const EVP_AEAD *aead; 151 /* aead_state is an opaque pointer to whatever state the AEAD needs to 152 * maintain. */ 153 void *aead_state; 154 /* tag_len may contain the actual length of the authentication tag if it is 155 * known at initialization time. */ 156 uint8_t tag_len; 157} EVP_AEAD_CTX; 158 159/* EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by 160 * any AEAD defined in this header. */ 161#define EVP_AEAD_MAX_KEY_LENGTH 80 162 163/* EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by 164 * any AEAD defined in this header. */ 165#define EVP_AEAD_MAX_NONCE_LENGTH 16 166 167/* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD 168 * defined in this header. */ 169#define EVP_AEAD_MAX_OVERHEAD 64 170 171/* EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to 172 * EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should 173 * be used. */ 174#define EVP_AEAD_DEFAULT_TAG_LENGTH 0 175 176/* EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be 177 * initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not 178 * necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for 179 * more uniform cleanup of |EVP_AEAD_CTX|. */ 180OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx); 181 182/* EVP_AEAD_CTX_new allocates an |EVP_AEAD_CTX|, calls |EVP_AEAD_CTX_init| and 183 * returns the |EVP_AEAD_CTX|, or NULL on error. */ 184OPENSSL_EXPORT EVP_AEAD_CTX *EVP_AEAD_CTX_new(const EVP_AEAD *aead, 185 const uint8_t *key, 186 size_t key_len, size_t tag_len); 187 188/* EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on 189 * |ctx|. */ 190OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx); 191 192/* EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl| 193 * argument is ignored and should be NULL. Authentication tags may be truncated 194 * by passing a size as |tag_len|. A |tag_len| of zero indicates the default 195 * tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for 196 * readability. 197 * 198 * Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In 199 * the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's 200 * harmless to do so. */ 201OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, 202 const uint8_t *key, size_t key_len, 203 size_t tag_len, ENGINE *impl); 204 205/* EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to 206 * call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to 207 * all zeros. */ 208OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx); 209 210/* EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and 211 * authenticates |ad_len| bytes from |ad| and writes the result to |out|. It 212 * returns one on success and zero otherwise. 213 * 214 * This function may be called concurrently with itself or any other seal/open 215 * function on the same |EVP_AEAD_CTX|. 216 * 217 * At most |max_out_len| bytes are written to |out| and, in order to ensure 218 * success, |max_out_len| should be |in_len| plus the result of 219 * |EVP_AEAD_max_overhead|. On successful return, |*out_len| is set to the 220 * actual number of bytes written. 221 * 222 * The length of |nonce|, |nonce_len|, must be equal to the result of 223 * |EVP_AEAD_nonce_length| for this AEAD. 224 * 225 * |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is 226 * insufficient, zero will be returned. If any error occurs, |out| will be 227 * filled with zero bytes and |*out_len| set to zero. 228 * 229 * If |in| and |out| alias then |out| must be == |in|. */ 230OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out, 231 size_t *out_len, size_t max_out_len, 232 const uint8_t *nonce, size_t nonce_len, 233 const uint8_t *in, size_t in_len, 234 const uint8_t *ad, size_t ad_len); 235 236/* EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes 237 * from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on 238 * success and zero otherwise. 239 * 240 * This function may be called concurrently with itself or any other seal/open 241 * function on the same |EVP_AEAD_CTX|. 242 * 243 * At most |in_len| bytes are written to |out|. In order to ensure success, 244 * |max_out_len| should be at least |in_len|. On successful return, |*out_len| 245 * is set to the the actual number of bytes written. 246 * 247 * The length of |nonce|, |nonce_len|, must be equal to the result of 248 * |EVP_AEAD_nonce_length| for this AEAD. 249 * 250 * |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is 251 * insufficient, zero will be returned. If any error occurs, |out| will be 252 * filled with zero bytes and |*out_len| set to zero. 253 * 254 * If |in| and |out| alias then |out| must be == |in|. */ 255OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out, 256 size_t *out_len, size_t max_out_len, 257 const uint8_t *nonce, size_t nonce_len, 258 const uint8_t *in, size_t in_len, 259 const uint8_t *ad, size_t ad_len); 260 261/* EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in| 262 * and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of 263 * ciphertext to |out| and the authentication tag to |out_tag|. It returns one 264 * on success and zero otherwise. 265 * 266 * This function may be called concurrently with itself or any other seal/open 267 * function on the same |EVP_AEAD_CTX|. 268 * 269 * Exactly |in_len| bytes are written to |out|, and up to 270 * |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful 271 * return, |*out_tag_len| is set to the actual number of bytes written to 272 * |out_tag|. 273 * 274 * |extra_in| may point to an additional plaintext input buffer if the cipher 275 * supports it. If present, |extra_in_len| additional bytes of plaintext are 276 * encrypted and authenticated, and the ciphertext is written (before the tag) 277 * to |out_tag|. |max_out_tag_len| must be sized to allow for the additional 278 * |extra_in_len| bytes. 279 * 280 * The length of |nonce|, |nonce_len|, must be equal to the result of 281 * |EVP_AEAD_nonce_length| for this AEAD. 282 * 283 * |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If 284 * |max_out_tag_len| is insufficient, zero will be returned. If any error 285 * occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len| 286 * set to zero. 287 * 288 * If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias 289 * any other argument. */ 290OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter( 291 const EVP_AEAD_CTX *ctx, uint8_t *out, 292 uint8_t *out_tag, size_t *out_tag_len, size_t max_out_tag_len, 293 const uint8_t *nonce, size_t nonce_len, 294 const uint8_t *in, size_t in_len, 295 const uint8_t *extra_in, size_t extra_in_len, 296 const uint8_t *ad, size_t ad_len); 297 298/* EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in| 299 * and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of 300 * authentication tag from |in_tag|. If successful, it writes |in_len| bytes of 301 * plaintext to |out|. It returns one on success and zero otherwise. 302 * 303 * This function may be called concurrently with itself or any other seal/open 304 * function on the same |EVP_AEAD_CTX|. 305 * 306 * The length of |nonce|, |nonce_len|, must be equal to the result of 307 * |EVP_AEAD_nonce_length| for this AEAD. 308 * 309 * |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error 310 * occurs, |out| will be filled with zero bytes. 311 * 312 * If |in| and |out| alias then |out| must be == |in|. */ 313OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather( 314 const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce, 315 size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag, 316 size_t in_tag_len, const uint8_t *ad, size_t ad_len); 317 318/* EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has 319 * not been set. */ 320OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx); 321 322 323/* TLS-specific AEAD algorithms. 324 * 325 * These AEAD primitives do not meet the definition of generic AEADs. They are 326 * all specific to TLS and should not be used outside of that context. They must 327 * be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may 328 * not be used concurrently. Any nonces are used as IVs, so they must be 329 * unpredictable. They only accept an |ad| parameter of length 11 (the standard 330 * TLS one with length omitted). */ 331 332OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void); 333OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void); 334OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha256_tls(void); 335 336OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void); 337OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void); 338OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha256_tls(void); 339OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha384_tls(void); 340 341OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void); 342OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); 343 344OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_tls(void); 345 346/* EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS 347 * 1.2 nonce construction. */ 348OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls12(void); 349 350/* EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS 351 * 1.2 nonce construction. */ 352OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls12(void); 353 354 355/* SSLv3-specific AEAD algorithms. 356 * 357 * These AEAD primitives do not meet the definition of generic AEADs. They are 358 * all specific to SSLv3 and should not be used outside of that context. They 359 * must be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, 360 * and may not be used concurrently. They only accept an |ad| parameter of 361 * length 9 (the standard TLS one with length and version omitted). */ 362 363OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_ssl3(void); 364OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_ssl3(void); 365OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_ssl3(void); 366OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_ssl3(void); 367 368 369/* Obscure functions. */ 370 371/* evp_aead_direction_t denotes the direction of an AEAD operation. */ 372enum evp_aead_direction_t { 373 evp_aead_open, 374 evp_aead_seal, 375}; 376 377/* EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal 378 * AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a 379 * given direction. */ 380OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction( 381 EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, 382 size_t tag_len, enum evp_aead_direction_t dir); 383 384/* EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and 385 * sets |*out_iv| to point to that many bytes of the current IV. This is only 386 * meaningful for AEADs with implicit IVs (i.e. CBC mode in SSLv3 and TLS 1.0). 387 * 388 * It returns one on success or zero on error. */ 389OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx, 390 const uint8_t **out_iv, size_t *out_len); 391 392/* EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by 393 * |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one 394 * on success or zero on error. |in_len| and |extra_in_len| must equal the 395 * arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|. */ 396OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx, 397 size_t *out_tag_len, 398 const size_t in_len, 399 const size_t extra_in_len); 400 401 402#if defined(__cplusplus) 403} /* extern C */ 404 405#if !defined(BORINGSSL_NO_CXX) 406extern "C++" { 407 408namespace bssl { 409 410using ScopedEVP_AEAD_CTX = 411 internal::StackAllocated<EVP_AEAD_CTX, void, EVP_AEAD_CTX_zero, 412 EVP_AEAD_CTX_cleanup>; 413 414BORINGSSL_MAKE_DELETER(EVP_AEAD_CTX, EVP_AEAD_CTX_free) 415 416} // namespace bssl 417 418} // extern C++ 419#endif 420 421#endif 422 423#endif /* OPENSSL_HEADER_AEAD_H */ 424