Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [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 | |
| 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 | |
David Benjamin | d4178fd | 2014-08-14 17:07:45 -0400 | [diff] [blame] | 95 | /* EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 96 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 97 | |
David Benjamin | d4178fd | 2014-08-14 17:07:45 -0400 | [diff] [blame] | 98 | /* EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 99 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 100 | |
Adam Langley | de0b202 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 101 | /* EVP_aead_chacha20_poly1305 is an AEAD built from ChaCha20 and Poly1305. */ |
David Benjamin | c44d2f4 | 2014-08-20 16:24:00 -0400 | [diff] [blame] | 102 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); |
Adam Langley | de0b202 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 103 | |
Adam Langley | 93a3dcd | 2014-07-25 15:40:44 -0700 | [diff] [blame] | 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 emtpy 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. */ |
David Benjamin | c44d2f4 | 2014-08-20 16:24:00 -0400 | [diff] [blame] | 110 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_key_wrap(void); |
Adam Langley | 93a3dcd | 2014-07-25 15:40:44 -0700 | [diff] [blame] | 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. */ |
David Benjamin | c44d2f4 | 2014-08-20 16:24:00 -0400 | [diff] [blame] | 116 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap(void); |
Adam Langley | 93a3dcd | 2014-07-25 15:40:44 -0700 | [diff] [blame] | 117 | |
David Benjamin | 5213df4 | 2014-08-20 14:19:54 -0400 | [diff] [blame] | 118 | /* EVP_has_aes_hardware returns one if we enable hardware support for fast and |
| 119 | * constant-time AES-GCM. */ |
| 120 | OPENSSL_EXPORT int EVP_has_aes_hardware(void); |
| 121 | |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 122 | |
Adam Langley | 45ec21b | 2014-06-24 17:26:59 -0700 | [diff] [blame] | 123 | /* TLS specific AEAD algorithms. |
| 124 | * |
| 125 | * These AEAD primitives do not meet the definition of generic AEADs. They are |
| 126 | * all specific to TLS in some fashion and should not be used outside of that |
| 127 | * context. */ |
| 128 | |
| 129 | /* EVP_aead_rc4_md5_tls uses RC4 and HMAC(MD5) in MAC-then-encrypt mode. Unlike |
| 130 | * a standard AEAD, this is stateful as the RC4 state is carried from operation |
| 131 | * to operation. */ |
David Benjamin | c44d2f4 | 2014-08-20 16:24:00 -0400 | [diff] [blame] | 132 | OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_tls(void); |
Adam Langley | 45ec21b | 2014-06-24 17:26:59 -0700 | [diff] [blame] | 133 | |
| 134 | |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 135 | /* Utility functions. */ |
| 136 | |
| 137 | /* EVP_AEAD_key_length returns the length, in bytes, of the keys used by |
| 138 | * |aead|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 139 | OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 140 | |
| 141 | /* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce |
| 142 | * for |aead|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 143 | OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 144 | |
| 145 | /* EVP_AEAD_max_overhead returns the maximum number of additional bytes added |
| 146 | * by the act of sealing data with |aead|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 147 | OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 148 | |
| 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 | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 152 | OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 153 | |
| 154 | |
| 155 | /* AEAD operations. */ |
| 156 | |
| 157 | /* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key |
| 158 | * and message-independent IV. */ |
| 159 | typedef struct evp_aead_ctx_st { |
| 160 | const EVP_AEAD *aead; |
| 161 | /* aead_state is an opaque pointer to whatever state the AEAD needs to |
| 162 | * maintain. */ |
| 163 | void *aead_state; |
| 164 | } EVP_AEAD_CTX; |
| 165 | |
| 166 | /* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD |
| 167 | * defined in this header. */ |
| 168 | #define EVP_AEAD_MAX_OVERHEAD 16 |
| 169 | |
| 170 | /* EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to |
| 171 | * EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should |
| 172 | * be used. */ |
| 173 | #define EVP_AEAD_DEFAULT_TAG_LENGTH 0 |
| 174 | |
| 175 | /* EVP_AEAD_init initializes |ctx| for the given AEAD algorithm from |impl|. |
| 176 | * The |impl| argument may be NULL to choose the default implementation. |
| 177 | * Authentication tags may be truncated by passing a size as |tag_len|. A |
| 178 | * |tag_len| of zero indicates the default tag length and this is defined as |
| 179 | * EVP_AEAD_DEFAULT_TAG_LENGTH for readability. |
| 180 | * Returns 1 on success. Otherwise returns 0 and pushes to the error stack. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 181 | OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, |
| 182 | const uint8_t *key, size_t key_len, |
| 183 | size_t tag_len, ENGINE *impl); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 184 | |
| 185 | /* EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 186 | OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 187 | |
| 188 | /* EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and |
| 189 | * authenticates |ad_len| bytes from |ad| and writes the result to |out|. It |
| 190 | * returns one on success and zero otherwise. |
| 191 | * |
| 192 | * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with |
| 193 | * itself or |EVP_AEAD_CTX_open|. |
| 194 | * |
| 195 | * At most |max_out_len| bytes are written to |out| and, in order to ensure |
| 196 | * success, |max_out_len| should be |in_len| plus the result of |
| 197 | * |EVP_AEAD_overhead|. On successful return, |*out_len| is set to the actual |
| 198 | * number of bytes written. |
| 199 | * |
| 200 | * The length of |nonce|, |nonce_len|, must be equal to the result of |
| 201 | * |EVP_AEAD_nonce_length| for this AEAD. |
| 202 | * |
| 203 | * |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is |
| 204 | * insufficient, zero will be returned. (In this case, |*out_len| is set to |
| 205 | * zero.) |
| 206 | * |
| 207 | * If |in| and |out| alias then |out| must be <= |in|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 208 | OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out, |
| 209 | size_t *out_len, size_t max_out_len, |
| 210 | const uint8_t *nonce, size_t nonce_len, |
| 211 | const uint8_t *in, size_t in_len, |
| 212 | const uint8_t *ad, size_t ad_len); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 213 | |
| 214 | /* EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes |
| 215 | * from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on |
| 216 | * success and zero otherwise. |
| 217 | * |
| 218 | * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with |
| 219 | * itself or |EVP_AEAD_CTX_seal|. |
| 220 | * |
| 221 | * At most |in_len| bytes are written to |out|. In order to ensure success, |
| 222 | * |max_out_len| should be at least |in_len|. On successful return, |*out_len| |
| 223 | * is set to the the actual number of bytes written. |
| 224 | * |
| 225 | * The length of |nonce|, |nonce_len|, must be equal to the result of |
| 226 | * |EVP_AEAD_nonce_length| for this AEAD. |
| 227 | * |
| 228 | * |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is |
| 229 | * insufficient, zero will be returned. (In this case, |*out_len| is set to |
| 230 | * zero.) |
| 231 | * |
| 232 | * If |in| and |out| alias then |out| must be <= |in|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 233 | OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out, |
| 234 | size_t *out_len, size_t max_out_len, |
| 235 | const uint8_t *nonce, size_t nonce_len, |
| 236 | const uint8_t *in, size_t in_len, |
| 237 | const uint8_t *ad, size_t ad_len); |
Adam Langley | fd772a5 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 238 | |
| 239 | |
| 240 | #if defined(__cplusplus) |
| 241 | } /* extern C */ |
| 242 | #endif |
| 243 | |
| 244 | #endif /* OPENSSL_HEADER_AEAD_H */ |