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