aead.h 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480
  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. #ifndef OPENSSL_HEADER_AEAD_H
  15. #define OPENSSL_HEADER_AEAD_H
  16. #include <openssl/base.h>
  17. #if defined(__cplusplus)
  18. extern "C" {
  19. #endif
  20. // Authenticated Encryption with Additional Data.
  21. //
  22. // AEAD couples confidentiality and integrity in a single primitive. AEAD
  23. // algorithms take a key and then can seal and open individual messages. Each
  24. // message has a unique, per-message nonce and, optionally, additional data
  25. // which is authenticated but not included in the ciphertext.
  26. //
  27. // The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and
  28. // performs any precomputation needed to use |aead| with |key|. The length of
  29. // the key, |key_len|, is given in bytes.
  30. //
  31. // The |tag_len| argument contains the length of the tags, in bytes, and allows
  32. // for the processing of truncated authenticators. A zero value indicates that
  33. // the default tag length should be used and this is defined as
  34. // |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using
  35. // truncated tags increases an attacker's chance of creating a valid forgery.
  36. // Be aware that the attacker's chance may increase more than exponentially as
  37. // would naively be expected.
  38. //
  39. // When no longer needed, the initialised |EVP_AEAD_CTX| structure must be
  40. // passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used.
  41. //
  42. // With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These
  43. // operations are intended to meet the standard notions of privacy and
  44. // authenticity for authenticated encryption. For formal definitions see
  45. // Bellare and Namprempre, "Authenticated encryption: relations among notions
  46. // and analysis of the generic composition paradigm," Lecture Notes in Computer
  47. // Science B<1976> (2000), 531–545,
  48. // http://www-cse.ucsd.edu/~mihir/papers/oem.html.
  49. //
  50. // When sealing messages, a nonce must be given. The length of the nonce is
  51. // fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The
  52. // nonce must be unique for all messages with the same key*. This is critically
  53. // important - nonce reuse may completely undermine the security of the AEAD.
  54. // Nonces may be predictable and public, so long as they are unique. Uniqueness
  55. // may be achieved with a simple counter or, if large enough, may be generated
  56. // randomly. The nonce must be passed into the "open" operation by the receiver
  57. // so must either be implicit (e.g. a counter), or must be transmitted along
  58. // with the sealed message.
  59. //
  60. // The "seal" and "open" operations are atomic - an entire message must be
  61. // encrypted or decrypted in a single call. Large messages may have to be split
  62. // up in order to accommodate this. When doing so, be mindful of the need not to
  63. // repeat nonces and the possibility that an attacker could duplicate, reorder
  64. // or drop message chunks. For example, using a single key for a given (large)
  65. // message and sealing chunks with nonces counting from zero would be secure as
  66. // long as the number of chunks was securely transmitted. (Otherwise an
  67. // attacker could truncate the message by dropping chunks from the end.)
  68. //
  69. // The number of chunks could be transmitted by prefixing it to the plaintext,
  70. // for example. This also assumes that no other message would ever use the same
  71. // key otherwise the rule that nonces must be unique for a given key would be
  72. // violated.
  73. //
  74. // The "seal" and "open" operations also permit additional data to be
  75. // authenticated via the |ad| parameter. This data is not included in the
  76. // ciphertext and must be identical for both the "seal" and "open" call. This
  77. // permits implicit context to be authenticated but may be empty if not needed.
  78. //
  79. // The "seal" and "open" operations may work in-place if the |out| and |in|
  80. // arguments are equal. Otherwise, if |out| and |in| alias, input data may be
  81. // overwritten before it is read. This situation will cause an error.
  82. //
  83. // The "seal" and "open" operations return one on success and zero on error.
  84. // AEAD algorithms.
  85. // EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode.
  86. //
  87. // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it
  88. // is specified to take a variable-length nonce, nonces with other lengths are
  89. // effectively randomized, which means one must consider collisions. Unless
  90. // implementing an existing protocol which has already specified incorrect
  91. // parameters, only use 12-byte nonces.
  92. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void);
  93. // EVP_aead_aes_192_gcm is AES-192 in Galois Counter Mode.
  94. //
  95. // WARNING: AES-192 is superfluous and shouldn't exist. NIST should never have
  96. // defined it. Use only when interop with another system requires it, never
  97. // de novo.
  98. //
  99. // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it
  100. // is specified to take a variable-length nonce, nonces with other lengths are
  101. // effectively randomized, which means one must consider collisions. Unless
  102. // implementing an existing protocol which has already specified incorrect
  103. // parameters, only use 12-byte nonces.
  104. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_192_gcm(void);
  105. // EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode.
  106. //
  107. // Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it
  108. // is specified to take a variable-length nonce, nonces with other lengths are
  109. // effectively randomized, which means one must consider collisions. Unless
  110. // implementing an existing protocol which has already specified incorrect
  111. // parameters, only use 12-byte nonces.
  112. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void);
  113. // EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and
  114. // Poly1305 as described in RFC 8439.
  115. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void);
  116. // EVP_aead_xchacha20_poly1305 is ChaCha20-Poly1305 with an extended nonce that
  117. // makes random generation of nonces safe.
  118. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xchacha20_poly1305(void);
  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.
  122. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void);
  123. // EVP_aead_aes_256_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. // EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See
  127. // https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02
  128. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_siv(void);
  129. // EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See
  130. // https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02
  131. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_siv(void);
  132. // EVP_aead_aes_128_gcm_randnonce is AES-128 in Galois Counter Mode with
  133. // internal nonce generation. The 12-byte nonce is appended to the tag
  134. // and is generated internally. The "tag", for the purpurses of the API, is thus
  135. // 12 bytes larger. The nonce parameter when using this AEAD must be
  136. // zero-length. Since the nonce is random, a single key should not be used for
  137. // more than 2^32 seal operations.
  138. //
  139. // Warning: this is for use for FIPS compliance only. It is probably not
  140. // suitable for other uses. Using standard AES-GCM AEADs allows one to achieve
  141. // the same effect, but gives more control over nonce storage.
  142. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_randnonce(void);
  143. // EVP_aead_aes_256_gcm_randnonce is AES-256 in Galois Counter Mode with
  144. // internal nonce generation. The 12-byte nonce is appended to the tag
  145. // and is generated internally. The "tag", for the purpurses of the API, is thus
  146. // 12 bytes larger. The nonce parameter when using this AEAD must be
  147. // zero-length. Since the nonce is random, a single key should not be used for
  148. // more than 2^32 seal operations.
  149. //
  150. // Warning: this is for use for FIPS compliance only. It is probably not
  151. // suitable for other uses. Using standard AES-GCM AEADs allows one to achieve
  152. // the same effect, but gives more control over nonce storage.
  153. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_randnonce(void);
  154. // EVP_aead_aes_128_ccm_bluetooth is AES-128-CCM with M=4 and L=2 (4-byte tags
  155. // and 13-byte nonces), as decribed in the Bluetooth Core Specification v5.0,
  156. // Volume 6, Part E, Section 1.
  157. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth(void);
  158. // EVP_aead_aes_128_ccm_bluetooth_8 is AES-128-CCM with M=8 and L=2 (8-byte tags
  159. // and 13-byte nonces), as used in the Bluetooth Mesh Networking Specification
  160. // v1.0.
  161. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth_8(void);
  162. // EVP_has_aes_hardware returns one if we enable hardware support for fast and
  163. // constant-time AES-GCM.
  164. OPENSSL_EXPORT int EVP_has_aes_hardware(void);
  165. // Utility functions.
  166. // EVP_AEAD_key_length returns the length, in bytes, of the keys used by
  167. // |aead|.
  168. OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead);
  169. // EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce
  170. // for |aead|.
  171. OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead);
  172. // EVP_AEAD_max_overhead returns the maximum number of additional bytes added
  173. // by the act of sealing data with |aead|.
  174. OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead);
  175. // EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This
  176. // is the largest value that can be passed as |tag_len| to
  177. // |EVP_AEAD_CTX_init|.
  178. OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead);
  179. // AEAD operations.
  180. union evp_aead_ctx_st_state {
  181. uint8_t opaque[580];
  182. uint64_t alignment;
  183. };
  184. // An evp_aead_ctx_st (typedefed as |EVP_AEAD_CTX| in base.h) represents an AEAD
  185. // algorithm configured with a specific key and message-independent IV.
  186. struct evp_aead_ctx_st {
  187. const EVP_AEAD *aead;
  188. union evp_aead_ctx_st_state state;
  189. // tag_len may contain the actual length of the authentication tag if it is
  190. // known at initialization time.
  191. uint8_t tag_len;
  192. };
  193. // EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by
  194. // any AEAD defined in this header.
  195. #define EVP_AEAD_MAX_KEY_LENGTH 80
  196. // EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by
  197. // any AEAD defined in this header.
  198. #define EVP_AEAD_MAX_NONCE_LENGTH 24
  199. // EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD
  200. // defined in this header.
  201. #define EVP_AEAD_MAX_OVERHEAD 64
  202. // EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to
  203. // EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should
  204. // be used.
  205. #define EVP_AEAD_DEFAULT_TAG_LENGTH 0
  206. // EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be
  207. // initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not
  208. // necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for
  209. // more uniform cleanup of |EVP_AEAD_CTX|.
  210. OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx);
  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.
  213. OPENSSL_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. // EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on
  217. // |ctx|.
  218. OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx);
  219. // EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl|
  220. // argument is ignored and should be NULL. Authentication tags may be truncated
  221. // by passing a size as |tag_len|. A |tag_len| of zero indicates the default
  222. // tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for
  223. // readability.
  224. //
  225. // Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In
  226. // the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's
  227. // harmless to do so.
  228. OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
  229. const uint8_t *key, size_t key_len,
  230. size_t tag_len, ENGINE *impl);
  231. // EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to
  232. // call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to
  233. // all zeros.
  234. OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);
  235. // EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and
  236. // authenticates |ad_len| bytes from |ad| and writes the result to |out|. It
  237. // returns one on success and zero otherwise.
  238. //
  239. // This function may be called concurrently with itself or any other seal/open
  240. // function on the same |EVP_AEAD_CTX|.
  241. //
  242. // At most |max_out_len| bytes are written to |out| and, in order to ensure
  243. // success, |max_out_len| should be |in_len| plus the result of
  244. // |EVP_AEAD_max_overhead|. On successful return, |*out_len| is set to the
  245. // 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_seal| never results in a partial output. If |max_out_len| is
  251. // insufficient, zero will be returned. If any error occurs, |out| will be
  252. // filled with zero bytes and |*out_len| set to zero.
  253. //
  254. // If |in| and |out| alias then |out| must be == |in|.
  255. OPENSSL_EXPORT int EVP_AEAD_CTX_seal(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. // EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes
  261. // from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on
  262. // success and zero otherwise.
  263. //
  264. // This function may be called concurrently with itself or any other seal/open
  265. // function on the same |EVP_AEAD_CTX|.
  266. //
  267. // At most |in_len| bytes are written to |out|. In order to ensure success,
  268. // |max_out_len| should be at least |in_len|. On successful return, |*out_len|
  269. // is set to the the actual number of bytes written.
  270. //
  271. // The length of |nonce|, |nonce_len|, must be equal to the result of
  272. // |EVP_AEAD_nonce_length| for this AEAD.
  273. //
  274. // |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is
  275. // insufficient, zero will be returned. If any error occurs, |out| will be
  276. // filled with zero bytes and |*out_len| set to zero.
  277. //
  278. // If |in| and |out| alias then |out| must be == |in|.
  279. OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out,
  280. size_t *out_len, size_t max_out_len,
  281. const uint8_t *nonce, size_t nonce_len,
  282. const uint8_t *in, size_t in_len,
  283. const uint8_t *ad, size_t ad_len);
  284. // EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in|
  285. // and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of
  286. // ciphertext to |out| and the authentication tag to |out_tag|. It returns one
  287. // on success and zero otherwise.
  288. //
  289. // This function may be called concurrently with itself or any other seal/open
  290. // function on the same |EVP_AEAD_CTX|.
  291. //
  292. // Exactly |in_len| bytes are written to |out|, and up to
  293. // |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful
  294. // return, |*out_tag_len| is set to the actual number of bytes written to
  295. // |out_tag|.
  296. //
  297. // |extra_in| may point to an additional plaintext input buffer if the cipher
  298. // supports it. If present, |extra_in_len| additional bytes of plaintext are
  299. // encrypted and authenticated, and the ciphertext is written (before the tag)
  300. // to |out_tag|. |max_out_tag_len| must be sized to allow for the additional
  301. // |extra_in_len| bytes.
  302. //
  303. // The length of |nonce|, |nonce_len|, must be equal to the result of
  304. // |EVP_AEAD_nonce_length| for this AEAD.
  305. //
  306. // |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If
  307. // |max_out_tag_len| is insufficient, zero will be returned. If any error
  308. // occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len|
  309. // set to zero.
  310. //
  311. // If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias
  312. // any other argument.
  313. OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter(
  314. const EVP_AEAD_CTX *ctx, uint8_t *out,
  315. uint8_t *out_tag, size_t *out_tag_len, size_t max_out_tag_len,
  316. const uint8_t *nonce, size_t nonce_len,
  317. const uint8_t *in, size_t in_len,
  318. const uint8_t *extra_in, size_t extra_in_len,
  319. const uint8_t *ad, size_t ad_len);
  320. // EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in|
  321. // and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of
  322. // authentication tag from |in_tag|. If successful, it writes |in_len| bytes of
  323. // plaintext to |out|. It returns one on success and zero otherwise.
  324. //
  325. // This function may be called concurrently with itself or any other seal/open
  326. // function on the same |EVP_AEAD_CTX|.
  327. //
  328. // The length of |nonce|, |nonce_len|, must be equal to the result of
  329. // |EVP_AEAD_nonce_length| for this AEAD.
  330. //
  331. // |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error
  332. // occurs, |out| will be filled with zero bytes.
  333. //
  334. // If |in| and |out| alias then |out| must be == |in|.
  335. OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather(
  336. const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce,
  337. size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag,
  338. size_t in_tag_len, const uint8_t *ad, size_t ad_len);
  339. // EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has
  340. // not been set.
  341. OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx);
  342. // TLS-specific AEAD algorithms.
  343. //
  344. // These AEAD primitives do not meet the definition of generic AEADs. They are
  345. // all specific to TLS and should not be used outside of that context. They must
  346. // be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may
  347. // not be used concurrently. Any nonces are used as IVs, so they must be
  348. // unpredictable. They only accept an |ad| parameter of length 11 (the standard
  349. // TLS one with length omitted).
  350. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void);
  351. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void);
  352. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void);
  353. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void);
  354. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void);
  355. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void);
  356. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_tls(void);
  357. // EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS
  358. // 1.2 nonce construction.
  359. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls12(void);
  360. // EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS
  361. // 1.2 nonce construction.
  362. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls12(void);
  363. // EVP_aead_aes_128_gcm_tls13 is AES-128 in Galois Counter Mode using the TLS
  364. // 1.3 nonce construction.
  365. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls13(void);
  366. // EVP_aead_aes_256_gcm_tls13 is AES-256 in Galois Counter Mode using the TLS
  367. // 1.3 nonce construction.
  368. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls13(void);
  369. // Obscure functions.
  370. // evp_aead_direction_t denotes the direction of an AEAD operation.
  371. enum evp_aead_direction_t {
  372. evp_aead_open,
  373. evp_aead_seal,
  374. };
  375. // EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal
  376. // AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a
  377. // given direction.
  378. OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction(
  379. EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len,
  380. size_t tag_len, enum evp_aead_direction_t dir);
  381. // EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and
  382. // sets |*out_iv| to point to that many bytes of the current IV. This is only
  383. // meaningful for AEADs with implicit IVs (i.e. CBC mode in TLS 1.0).
  384. //
  385. // It returns one on success or zero on error.
  386. OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx,
  387. const uint8_t **out_iv, size_t *out_len);
  388. // EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by
  389. // |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one
  390. // on success or zero on error. |in_len| and |extra_in_len| must equal the
  391. // arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|.
  392. OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx,
  393. size_t *out_tag_len,
  394. const size_t in_len,
  395. const size_t extra_in_len);
  396. #if defined(__cplusplus)
  397. } // extern C
  398. #if !defined(BORINGSSL_NO_CXX)
  399. extern "C++" {
  400. BSSL_NAMESPACE_BEGIN
  401. using ScopedEVP_AEAD_CTX =
  402. internal::StackAllocated<EVP_AEAD_CTX, void, EVP_AEAD_CTX_zero,
  403. EVP_AEAD_CTX_cleanup>;
  404. BORINGSSL_MAKE_DELETER(EVP_AEAD_CTX, EVP_AEAD_CTX_free)
  405. BSSL_NAMESPACE_END
  406. } // extern C++
  407. #endif
  408. #endif
  409. #endif // OPENSSL_HEADER_AEAD_H