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