| 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 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 the AEAD built from ChaCha20 and |
| 102 |
* Poly1305 as described in RFC 7539. */ |
| 103 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); |
| 104 |
|
| 105 |
/* EVP_aead_chacha20_poly1305_old is an AEAD built from ChaCha20 and |
| 106 |
* Poly1305 that is used in the experimental ChaCha20-Poly1305 TLS cipher |
| 107 |
* suites. */ |
| 108 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305_old(void); |
| 109 |
|
| 110 |
/* EVP_aead_aes_128_key_wrap is AES-128 Key Wrap mode. This should never be |
| 111 |
* used except to interoperate with existing systems that use this mode. |
| 112 |
* |
| 113 |
* If the nonce is empty then the default nonce will be used, otherwise it must |
| 114 |
* be eight bytes long. The input must be a multiple of eight bytes long. No |
| 115 |
* additional data can be given to this mode. */ |
| 116 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_key_wrap(void); |
| 117 |
|
| 118 |
/* EVP_aead_aes_256_key_wrap is AES-256 in Key Wrap mode. This should never be |
| 119 |
* used except to interoperate with existing systems that use this mode. |
| 120 |
* |
| 121 |
* See |EVP_aead_aes_128_key_wrap| for details. */ |
| 122 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap(void); |
| 123 |
|
| 124 |
/* EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for |
| 125 |
* authentication. The nonce is 12 bytes; the bottom 32-bits are used as the |
| 126 |
* block counter, thus the maximum plaintext size is 64GB. */ |
| 127 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); |
| 128 |
|
| 129 |
/* EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for |
| 130 |
* authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. */ |
| 131 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void); |
| 132 |
|
| 133 |
/* EVP_has_aes_hardware returns one if we enable hardware support for fast and |
| 134 |
* constant-time AES-GCM. */ |
| 135 |
OPENSSL_EXPORT int EVP_has_aes_hardware(void); |
| 136 |
|
| 137 |
|
| 138 |
/* Utility functions. */ |
| 139 |
|
| 140 |
/* EVP_AEAD_key_length returns the length, in bytes, of the keys used by |
| 141 |
* |aead|. */ |
| 142 |
OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); |
| 143 |
|
| 144 |
/* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce |
| 145 |
* for |aead|. */ |
| 146 |
OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); |
| 147 |
|
| 148 |
/* EVP_AEAD_max_overhead returns the maximum number of additional bytes added |
| 149 |
* by the act of sealing data with |aead|. */ |
| 150 |
OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); |
| 151 |
|
| 152 |
/* EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This |
| 153 |
* is the largest value that can be passed as |tag_len| to |
| 154 |
* |EVP_AEAD_CTX_init|. */ |
| 155 |
OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); |
| 156 |
|
| 157 |
|
| 158 |
/* AEAD operations. */ |
| 159 |
|
| 160 |
/* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key |
| 161 |
* and message-independent IV. */ |
| 162 |
typedef struct evp_aead_ctx_st { |
| 163 |
const EVP_AEAD *aead; |
| 164 |
/* aead_state is an opaque pointer to whatever state the AEAD needs to |
| 165 |
* maintain. */ |
| 166 |
void *aead_state; |
| 167 |
} EVP_AEAD_CTX; |
| 168 |
|
| 169 |
/* EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by |
| 170 |
* any AEAD defined in this header. */ |
| 171 |
#define EVP_AEAD_MAX_KEY_LENGTH 80 |
| 172 |
|
| 173 |
/* EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by |
| 174 |
* any AEAD defined in this header. */ |
| 175 |
#define EVP_AEAD_MAX_NONCE_LENGTH 16 |
| 176 |
|
| 177 |
/* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD |
| 178 |
* defined in this header. */ |
| 179 |
#define EVP_AEAD_MAX_OVERHEAD 64 |
| 180 |
|
| 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. */ |
| 184 |
#define EVP_AEAD_DEFAULT_TAG_LENGTH 0 |
| 185 |
|
| 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|. */ |
| 190 |
OPENSSL_EXPORT void EVP_AEAD_CTX_zero(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. */ |
| 201 |
OPENSSL_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. */ |
| 208 |
OPENSSL_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 (with the same |EVP_AEAD_CTX|) concurrently with |
| 215 |
* itself or |EVP_AEAD_CTX_open|. |
| 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. (In this case, |*out_len| is set to |
| 227 |
* zero.) |
| 228 |
* |
| 229 |
* If |in| and |out| alias then |out| must be == |in|. */ |
| 230 |
OPENSSL_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 (with the same |EVP_AEAD_CTX|) concurrently with |
| 241 |
* itself or |EVP_AEAD_CTX_seal|. |
| 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. (In this case, |*out_len| is set to |
| 252 |
* zero.) |
| 253 |
* |
| 254 |
* If |in| and |out| alias then |out| must be == |in|. */ |
| 255 |
OPENSSL_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 |
|
| 262 |
/* TLS-specific AEAD algorithms. |
| 263 |
* |
| 264 |
* These AEAD primitives do not meet the definition of generic AEADs. They are |
| 265 |
* all specific to TLS and should not be used outside of that context. They must |
| 266 |
* be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may |
| 267 |
* not be used concurrently. Any nonces are used as IVs, so they must be |
| 268 |
* unpredictable. They only accept an |ad| parameter of length 11 (the standard |
| 269 |
* TLS one with length omitted). */ |
| 270 |
|
| 271 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_tls(void); |
| 272 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_tls(void); |
| 273 |
|
| 274 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void); |
| 275 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void); |
| 276 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha256_tls(void); |
| 277 |
|
| 278 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void); |
| 279 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void); |
| 280 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha256_tls(void); |
| 281 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha384_tls(void); |
| 282 |
|
| 283 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void); |
| 284 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); |
| 285 |
|
| 286 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_tls(void); |
| 287 |
|
| 288 |
|
| 289 |
/* SSLv3-specific AEAD algorithms. |
| 290 |
* |
| 291 |
* These AEAD primitives do not meet the definition of generic AEADs. They are |
| 292 |
* all specific to SSLv3 and should not be used outside of that context. They |
| 293 |
* must be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, |
| 294 |
* and may not be used concurrently. They only accept an |ad| parameter of |
| 295 |
* length 9 (the standard TLS one with length and version omitted). */ |
| 296 |
|
| 297 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_ssl3(void); |
| 298 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_ssl3(void); |
| 299 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_ssl3(void); |
| 300 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_ssl3(void); |
| 301 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_ssl3(void); |
| 302 |
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_ssl3(void); |
| 303 |
|
| 304 |
|
| 305 |
/* Obscure functions. */ |
| 306 |
|
| 307 |
/* evp_aead_direction_t denotes the direction of an AEAD operation. */ |
| 308 |
enum evp_aead_direction_t { |
| 309 |
evp_aead_open, |
| 310 |
evp_aead_seal, |
| 311 |
}; |
| 312 |
|
| 313 |
/* EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal |
| 314 |
* AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a |
| 315 |
* given direction. */ |
| 316 |
OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction( |
| 317 |
EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, |
| 318 |
size_t tag_len, enum evp_aead_direction_t dir); |
| 319 |
|
| 320 |
/* EVP_AEAD_CTX_get_rc4_state sets |*out_key| to point to an RC4 key structure. |
| 321 |
* It returns one on success or zero if |ctx| doesn't have an RC4 key. */ |
| 322 |
OPENSSL_EXPORT int EVP_AEAD_CTX_get_rc4_state(const EVP_AEAD_CTX *ctx, |
| 323 |
const RC4_KEY **out_key); |
| 324 |
|
| 325 |
/* EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and |
| 326 |
* sets |*out_iv| to point to that many bytes of the current IV. This is only |
| 327 |
* meaningful for AEADs with implicit IVs (i.e. CBC mode in SSLv3 and TLS 1.0). |
| 328 |
* |
| 329 |
* It returns one on success or zero on error. */ |
| 330 |
OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx, |
| 331 |
const uint8_t **out_iv, size_t *out_len); |
| 332 |
|
| 333 |
|
| 334 |
#if defined(__cplusplus) |
| 335 |
} /* extern C */ |
| 336 |
#endif |
| 337 |
|
| 338 |
#endif /* OPENSSL_HEADER_AEAD_H */ |