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 primtive. 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 accomodate 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. They may also be used to shift the data left inside the 86 * same buffer if |out| is less than |in|. However, |out| may not point inside 87 * the input data otherwise the input may be overwritten before it has been 88 * read. This situation will cause an error. 89 * 90 * The "seal" and "open" operations return one on success and zero on error. */ 91 92 93 /* AEAD algorithms. */ 94 95 /* EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode. */ 96 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void); 97 98 /* EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. */ 99 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void); 100 101 /* EVP_aead_chacha20_poly1305 is an AEAD built from ChaCha20 and Poly1305. */ 102 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); 103 104 /* EVP_aead_aes_128_key_wrap is AES-128 Key Wrap mode. This should never be 105 * used except to interoperate with existing systems that use this mode. 106 * 107 * If the nonce is empty then the default nonce will be used, otherwise it must 108 * be eight bytes long. The input must be a multiple of eight bytes long. No 109 * additional data can be given to this mode. */ 110 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_key_wrap(void); 111 112 /* EVP_aead_aes_256_key_wrap is AES-256 in Key Wrap mode. This should never be 113 * used except to interoperate with existing systems that use this mode. 114 * 115 * See |EVP_aead_aes_128_key_wrap| for details. */ 116 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap(void); 117 118 /* EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for 119 * authentication. The nonce is 12 bytes; the bottom 32-bits are used as the 120 * block counter, thus the maximum plaintext size is 64GB. */ 121 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); 122 123 /* EVP_aead_aes_128_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for 124 * authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. */ 125 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void); 126 127 /* EVP_has_aes_hardware returns one if we enable hardware support for fast and 128 * constant-time AES-GCM. */ 129 OPENSSL_EXPORT int EVP_has_aes_hardware(void); 130 131 132 /* TLS-specific AEAD algorithms. 133 * 134 * These AEAD primitives do not meet the definition of generic AEADs. They are 135 * all specific to TLS and should not be used outside of that context. They must 136 * be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may 137 * not be used concurrently. Any nonces are used as IVs, so they must be 138 * unpredictable. They only accept an |ad| parameter of length 11 (the standard 139 * TLS one with length omitted). */ 140 141 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_tls(void); 142 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_tls(void); 143 144 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void); 145 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void); 146 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha256_tls(void); 147 148 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void); 149 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void); 150 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha256_tls(void); 151 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha384_tls(void); 152 153 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void); 154 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); 155 156 157 /* SSLv3-specific AEAD algorithms. 158 * 159 * These AEAD primitives do not meet the definition of generic AEADs. They are 160 * all specific to SSLv3 and should not be used outside of that context. They 161 * must be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, 162 * and may not be used concurrently. They only accept an |ad| parameter of 163 * length 9 (the standard TLS one with length and version omitted). */ 164 165 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_ssl3(void); 166 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_ssl3(void); 167 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_ssl3(void); 168 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_ssl3(void); 169 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_ssl3(void); 170 171 172 /* Utility functions. */ 173 174 /* EVP_AEAD_key_length returns the length, in bytes, of the keys used by 175 * |aead|. */ 176 OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); 177 178 /* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce 179 * for |aead|. */ 180 OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); 181 182 /* EVP_AEAD_max_overhead returns the maximum number of additional bytes added 183 * by the act of sealing data with |aead|. */ 184 OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); 185 186 /* EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This 187 * is the largest value that can be passed as |tag_len| to 188 * |EVP_AEAD_CTX_init|. */ 189 OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); 190 191 192 /* AEAD operations. */ 193 194 /* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key 195 * and message-independent IV. */ 196 typedef struct evp_aead_ctx_st { 197 const EVP_AEAD *aead; 198 /* aead_state is an opaque pointer to whatever state the AEAD needs to 199 * maintain. */ 200 void *aead_state; 201 } EVP_AEAD_CTX; 202 203 /* EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by 204 * any AEAD defined in this header. */ 205 #define EVP_AEAD_MAX_KEY_LENGTH 80 206 207 /* EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by 208 * any AEAD defined in this header. */ 209 #define EVP_AEAD_MAX_NONCE_LENGTH 16 210 211 /* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD 212 * defined in this header. */ 213 #define EVP_AEAD_MAX_OVERHEAD 64 214 215 /* EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to 216 * EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should 217 * be used. */ 218 #define EVP_AEAD_DEFAULT_TAG_LENGTH 0 219 220 /* evp_aead_direction_t denotes the direction of an AEAD operation. */ 221 enum evp_aead_direction_t { 222 evp_aead_open, 223 evp_aead_seal, 224 }; 225 226 /* EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm from |impl|. 227 * The |impl| argument may be NULL to choose the default implementation. 228 * Authentication tags may be truncated by passing a size as |tag_len|. A 229 * |tag_len| of zero indicates the default tag length and this is defined as 230 * EVP_AEAD_DEFAULT_TAG_LENGTH for readability. 231 * 232 * Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In 233 * the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's 234 * harmless to do so. */ 235 OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, 236 const uint8_t *key, size_t key_len, 237 size_t tag_len, ENGINE *impl); 238 239 /* EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal 240 * AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a 241 * given direction. */ 242 OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction( 243 EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, 244 size_t tag_len, enum evp_aead_direction_t dir); 245 246 /* EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to 247 * call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to 248 * all zeros. */ 249 OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx); 250 251 /* EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and 252 * authenticates |ad_len| bytes from |ad| and writes the result to |out|. It 253 * returns one on success and zero otherwise. 254 * 255 * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with 256 * itself or |EVP_AEAD_CTX_open|. 257 * 258 * At most |max_out_len| bytes are written to |out| and, in order to ensure 259 * success, |max_out_len| should be |in_len| plus the result of 260 * |EVP_AEAD_max_overhead|. On successful return, |*out_len| is set to the 261 * actual number of bytes written. 262 * 263 * The length of |nonce|, |nonce_len|, must be equal to the result of 264 * |EVP_AEAD_nonce_length| for this AEAD. 265 * 266 * |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is 267 * insufficient, zero will be returned. (In this case, |*out_len| is set to 268 * zero.) 269 * 270 * If |in| and |out| alias then |out| must be <= |in|. */ 271 OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out, 272 size_t *out_len, size_t max_out_len, 273 const uint8_t *nonce, size_t nonce_len, 274 const uint8_t *in, size_t in_len, 275 const uint8_t *ad, size_t ad_len); 276 277 /* EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes 278 * from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on 279 * success and zero otherwise. 280 * 281 * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with 282 * itself or |EVP_AEAD_CTX_seal|. 283 * 284 * At most |in_len| bytes are written to |out|. In order to ensure success, 285 * |max_out_len| should be at least |in_len|. On successful return, |*out_len| 286 * is set to the the 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_open| never results in a partial output. If |max_out_len| is 292 * insufficient, zero will be returned. (In this case, |*out_len| is set to 293 * zero.) 294 * 295 * If |in| and |out| alias then |out| must be <= |in|. */ 296 OPENSSL_EXPORT int EVP_AEAD_CTX_open(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 303 /* Obscure functions. */ 304 305 /* EVP_AEAD_CTX_get_rc4_state sets |*out_key| to point to an RC4 key structure. 306 * It returns one on success or zero if |ctx| doesn't have an RC4 key. */ 307 OPENSSL_EXPORT int EVP_AEAD_CTX_get_rc4_state(const EVP_AEAD_CTX *ctx, 308 const RC4_KEY **out_key); 309 310 311 #if defined(__cplusplus) 312 } /* extern C */ 313 #endif 314 315 #endif /* OPENSSL_HEADER_AEAD_H */ 316