1.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.16 2024/07/21 08:36:43 tb Exp $ 2.\" 3.\" Copyright (c) 2014, Google Inc. 4.\" Parts of the text were written by Adam Langley and David Benjamin. 5.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org> 6.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and/or distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: July 21 2024 $ 21.Dt EVP_AEAD_CTX_INIT 3 22.Os 23.Sh NAME 24.Nm EVP_AEAD_CTX_new , 25.Nm EVP_AEAD_CTX_free , 26.Nm EVP_AEAD_CTX_init , 27.Nm EVP_AEAD_CTX_cleanup , 28.Nm EVP_AEAD_CTX_open , 29.Nm EVP_AEAD_CTX_seal , 30.Nm EVP_AEAD_key_length , 31.Nm EVP_AEAD_max_overhead , 32.Nm EVP_AEAD_max_tag_len , 33.Nm EVP_AEAD_nonce_length , 34.Nm EVP_aead_aes_128_gcm , 35.Nm EVP_aead_aes_256_gcm , 36.Nm EVP_aead_chacha20_poly1305 , 37.Nm EVP_aead_xchacha20_poly1305 38.Nd authenticated encryption with additional data 39.Sh SYNOPSIS 40.In openssl/evp.h 41.Ft EVP_AEAD_CTX * 42.Fn EVP_AEAD_CTX_new void 43.Ft void 44.Fo EVP_AEAD_CTX_free 45.Fa "EVP_AEAD_CTX *ctx" 46.Fc 47.Ft int 48.Fo EVP_AEAD_CTX_init 49.Fa "EVP_AEAD_CTX *ctx" 50.Fa "const EVP_AEAD *aead" 51.Fa "const unsigned char *key" 52.Fa "size_t key_len" 53.Fa "size_t tag_len" 54.Fa "ENGINE *engine" 55.Fc 56.Ft void 57.Fo EVP_AEAD_CTX_cleanup 58.Fa "EVP_AEAD_CTX *ctx" 59.Fc 60.Ft int 61.Fo EVP_AEAD_CTX_open 62.Fa "const EVP_AEAD_CTX *ctx" 63.Fa "unsigned char *out" 64.Fa "size_t *out_len" 65.Fa "size_t max_out_len" 66.Fa "const unsigned char *nonce" 67.Fa "size_t nonce_len" 68.Fa "const unsigned char *in" 69.Fa "size_t in_len" 70.Fa "const unsigned char *ad" 71.Fa "size_t ad_len" 72.Fc 73.Ft int 74.Fo EVP_AEAD_CTX_seal 75.Fa "const EVP_AEAD_CTX *ctx" 76.Fa "unsigned char *out" 77.Fa "size_t *out_len" 78.Fa "size_t max_out_len" 79.Fa "const unsigned char *nonce" 80.Fa "size_t nonce_len" 81.Fa "const unsigned char *in" 82.Fa "size_t in_len" 83.Fa "const unsigned char *ad" 84.Fa "size_t ad_len" 85.Fc 86.Ft size_t 87.Fo EVP_AEAD_key_length 88.Fa "const EVP_AEAD *aead" 89.Fc 90.Ft size_t 91.Fo EVP_AEAD_max_overhead 92.Fa "const EVP_AEAD *aead" 93.Fc 94.Ft size_t 95.Fo EVP_AEAD_max_tag_len 96.Fa "const EVP_AEAD *aead" 97.Fc 98.Ft size_t 99.Fo EVP_AEAD_nonce_length 100.Fa "const EVP_AEAD *aead" 101.Fc 102.Ft const EVP_AEAD * 103.Fo EVP_aead_aes_128_gcm 104.Fa void 105.Fc 106.Ft const EVP_AEAD * 107.Fo EVP_aead_aes_256_gcm 108.Fa void 109.Fc 110.Ft const EVP_AEAD * 111.Fo EVP_aead_chacha20_poly1305 112.Fa void 113.Fc 114.Ft const EVP_AEAD * 115.Fo EVP_aead_xchacha20_poly1305 116.Fa void 117.Fc 118.Sh DESCRIPTION 119AEAD (Authenticated Encryption with Additional Data) couples 120confidentiality and integrity in a single primitive. 121AEAD algorithms take a key and can then seal and open individual 122messages. 123Each message has a unique, per-message nonce and, optionally, additional 124data which is authenticated but not included in the output. 125.Pp 126.Fn EVP_AEAD_CTX_new 127allocates a new context for use with 128.Fn EVP_AEAD_CTX_init . 129It can be cleaned up for reuse with 130.Fn EVP_AEAD_CTX_cleanup 131and must be freed with 132.Fn EVP_AEAD_CTX_free . 133.Pp 134.Fn EVP_AEAD_CTX_free 135cleans up 136.Fa ctx 137and frees the space allocated to it. 138.Pp 139.Fn EVP_AEAD_CTX_init 140initializes the context 141.Fa ctx 142for the given AEAD algorithm 143.Fa aead . 144The 145.Fa engine 146argument must be 147.Dv NULL 148for the default implementation; 149other values are not supported. 150Authentication tags may be truncated by passing a tag length. 151A 152.Fa tag_len 153argument of 154.Dv EVP_AEAD_DEFAULT_TAG_LENGTH , 155which has the value 0, causes the default tag length to be used. 156.Pp 157.Fn EVP_AEAD_CTX_cleanup 158frees any data allocated for the context 159.Fa ctx . 160After 161.Fn EVP_AEAD_CTX_cleanup , 162.Fa ctx 163is in the same state as after 164.Fn EVP_AEAD_CTX_new . 165.Pp 166.Fn EVP_AEAD_CTX_open 167authenticates the input 168.Fa in 169and optional additional data 170.Fa ad , 171decrypting the input and writing it as output 172.Fa out . 173This function may be called (with the same 174.Vt EVP_AEAD_CTX ) 175concurrently with itself or with 176.Fn EVP_AEAD_CTX_seal . 177At most the number of input bytes are written as output. 178In order to ensure success, 179.Fa max_out_len 180should be at least the same as the input length 181.Fa in_len . 182On successful return 183.Fa out_len 184is set to the actual number of bytes written. 185The length of the 186.Fa nonce 187specified with 188.Fa nonce_len 189must be equal to the result of EVP_AEAD_nonce_length for this AEAD. 190.Fn EVP_AEAD_CTX_open 191never results in partial output. 192If 193.Fa max_out_len 194is insufficient, zero will be returned and 195.Fa out_len 196will be set to zero. 197If the input and output are aliased then 198.Fa out 199must be <= 200.Fa in . 201.Pp 202.Fn EVP_AEAD_CTX_seal 203encrypts and authenticates the input and authenticates any additional 204data provided in 205.Fa ad , 206the encrypted input and authentication tag being written as output 207.Fa out . 208This function may be called (with the same 209.Vt EVP_AEAD_CTX ) 210concurrently with itself or with 211.Fn EVP_AEAD_CTX_open . 212At most 213.Fa max_out_len 214bytes are written as output and, in order to ensure success, this value 215should be the 216.Fa in_len 217plus the result of 218.Fn EVP_AEAD_max_overhead . 219On successful return, 220.Fa out_len 221is set to the actual number of bytes written. 222The length of the 223.Fa nonce 224specified with 225.Fa nonce_len 226must be equal to the result of 227.Fn EVP_AEAD_nonce_length 228for this AEAD. 229.Fn EVP_AEAD_CTX_seal 230never results in a partial output. 231If 232.Fa max_out_len 233is insufficient, zero will be returned and 234.Fa out_len 235will be set to zero. 236If the input and output are aliased then 237.Fa out 238must be <= 239.Fa in . 240.Pp 241.Fn EVP_AEAD_key_length , 242.Fn EVP_AEAD_max_overhead , 243.Fn EVP_AEAD_max_tag_len , 244and 245.Fn EVP_AEAD_nonce_length 246provide information about the AEAD algorithm 247.Fa aead . 248.Pp 249.Fn EVP_AEAD_max_tag_len 250returns the maximum tag length that can be used with the given 251.Fa aead . 252This is the largest value that can be passed as the 253.Fa tag_len 254argument to 255.Fn EVP_AEAD_CTX_init . 256No built-in 257.Vt EVP_AEAD 258object has a maximum tag length larger than the constant 259.Dv EVP_AEAD_MAX_TAG_LENGTH . 260.Pp 261All cipher algorithms have a fixed key length unless otherwise stated. 262The following ciphers are available: 263.Bl -tag -width Ds -offset indent 264.It Fn EVP_aead_aes_128_gcm 265AES-128 in Galois Counter Mode, using a 266.Fa key_len 267of 16 bytes and a 268.Fa nonce_len 269of 12 bytes. 270.It Fn EVP_aead_aes_256_gcm 271AES-256 in Galois Counter Mode, using a 272.Fa key_len 273of 32 bytes and a 274.Fa nonce_len 275of 12 bytes. 276.It Fn EVP_aead_chacha20_poly1305 277ChaCha20 with a Poly1305 authenticator, using a 278.Fa key_len 279of 32 bytes and a 280.Fa nonce_len 281of 12 bytes. 282The constant 283.Dv EVP_CHACHAPOLY_TLS_TAG_LEN 284specifies the length of the authentication tag in bytes and has a value of 16. 285.It Fn EVP_aead_xchacha20_poly1305 286XChaCha20 with a Poly1305 authenticator, using a 287.Fa key_len 288of 32 bytes and a 289.Fa nonce_len 290of 24 bytes. 291.El 292.Pp 293Unless compatibility with other implementations 294like OpenSSL or BoringSSL is required, using the 295.Sy EVP_AEAD 296interface to AEAD ciphers is recommended 297in preference to the functions documented in the 298.Xr EVP_EncryptInit 3 , 299.Xr EVP_aes_256_gcm 3 , 300and 301.Xr EVP_chacha20_poly1305 3 302manual pages. 303The code then becomes transparent to the AEAD cipher used 304and much more flexible. 305It is also safer to use as it prevents common mistakes with the EVP APIs. 306.Sh RETURN VALUES 307.Fn EVP_AEAD_CTX_new 308returns the new 309.Vt EVP_AEAD_CTX 310object on success; 311otherwise 312.Dv NULL 313is returned and 314.Va errno 315is set to 316.Er ENOMEM . 317.Pp 318.Fn EVP_AEAD_CTX_init , 319.Fn EVP_AEAD_CTX_open , 320and 321.Fn EVP_AEAD_CTX_seal 322return 1 for success or zero for failure. 323.Pp 324.Fn EVP_AEAD_key_length 325returns the length of the key used for this AEAD. 326.Pp 327.Fn EVP_AEAD_max_overhead 328returns the maximum number of additional bytes added by the act of 329sealing data with the AEAD. 330.Pp 331.Fn EVP_AEAD_max_tag_len 332returns the maximum tag length when using this AEAD. 333.Pp 334.Fn EVP_AEAD_nonce_length 335returns the length of the per-message nonce. 336.Sh EXAMPLES 337Encrypt a string using ChaCha20-Poly1305: 338.Bd -literal -offset indent 339const EVP_AEAD *aead = EVP_aead_chacha20_poly1305(); 340static const unsigned char nonce[32] = {0}; 341size_t buf_len, nonce_len; 342EVP_AEAD_CTX *ctx; 343 344ctx = EVP_AEAD_CTX_new(); 345EVP_AEAD_CTX_init(ctx, aead, key32, EVP_AEAD_key_length(aead), 346 EVP_AEAD_DEFAULT_TAG_LENGTH, NULL); 347nonce_len = EVP_AEAD_nonce_length(aead); 348 349EVP_AEAD_CTX_seal(ctx, out, &out_len, BUFSIZE, nonce, 350 nonce_len, in, in_len, NULL, 0); 351 352EVP_AEAD_CTX_free(ctx); 353.Ed 354.Sh SEE ALSO 355.Xr evp 3 , 356.Xr EVP_EncryptInit 3 357.Sh STANDARDS 358.Rs 359.%A A. Langley 360.%A W. Chang 361.%A N. Mavrogiannopoulos 362.%A J. Strombergson 363.%A S. Josefsson 364.%D June 2016 365.%R RFC 7905 366.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS) 367.Re 368.Pp 369.Rs 370.%A S. Arciszewski 371.%D October 2018 372.%R draft-arciszewski-xchacha-02 373.%T XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 374.Re 375.Sh HISTORY 376AEAD is based on the implementation by 377.An Adam Langley 378.\" OpenSSL commit 9a8646510b Sep 9 12:13:24 2013 -0400 379for Chromium/BoringSSL and first appeared in 380.Ox 5.6 . 381.Pp 382.Fn EVP_AEAD_CTX_new 383and 384.Fn EVP_AEAD_CTX_free 385first appeared in 386.Ox 7.1 . 387.Sh CAVEATS 388The original publications and code by 389.An Adam Langley 390used a modified AEAD construction that is incompatible with the common 391style used by AEAD in TLS and incompatible with RFC 7905: 392.Pp 393.Rs 394.%A A. Langley 395.%A W. Chang 396.%D November 2013 397.%R draft-agl-tls-chacha20poly1305-04 398.%T ChaCha20 and Poly1305 based Cipher Suites for TLS 399.Re 400.Pp 401.Rs 402.%A Y. Nir 403.%A A. Langley 404.%D June 2018 405.%R RFC 8439 406.%T ChaCha20 and Poly1305 for IETF Protocols 407.Re 408.Pp 409In particular, the original version used a 410.Fa nonce_len 411of 8 bytes. 412