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