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