xref: /openbsd-src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 (revision c1a45aed656e7d5627c30c92421893a76f370ccb) 
1.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.10 2022/01/10 22:44:22 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: January 10 2022 $
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 or
270.Dv NULL
271on failure.
272.Fn EVP_AEAD_CTX_init ,
273.Fn EVP_AEAD_CTX_open ,
274and
275.Fn EVP_AEAD_CTX_seal
276return 1 for success or zero for failure.
277.Pp
278.Fn EVP_AEAD_key_length
279returns the length of the key used for this AEAD.
280.Pp
281.Fn EVP_AEAD_max_overhead
282returns the maximum number of additional bytes added by the act of
283sealing data with the AEAD.
284.Pp
285.Fn EVP_AEAD_max_tag_len
286returns the maximum tag length when using this AEAD.
287This is the largest value that can be passed as a tag length to
288.Fn EVP_AEAD_CTX_init .
289.Pp
290.Fn EVP_AEAD_nonce_length
291returns the length of the per-message nonce.
292.Sh EXAMPLES
293Encrypt a string using ChaCha20-Poly1305:
294.Bd -literal -offset indent
295const EVP_AEAD *aead = EVP_aead_chacha20_poly1305();
296static const unsigned char nonce[32] = {0};
297size_t buf_len, nonce_len;
298EVP_AEAD_CTX *ctx;
299
300ctx = EVP_AEAD_CTX_new();
301EVP_AEAD_CTX_init(ctx, aead, key32, EVP_AEAD_key_length(aead),
302    EVP_AEAD_DEFAULT_TAG_LENGTH, NULL);
303nonce_len = EVP_AEAD_nonce_length(aead);
304
305EVP_AEAD_CTX_seal(ctx, out, &out_len, BUFSIZE, nonce,
306    nonce_len, in, in_len, NULL, 0);
307
308EVP_AEAD_CTX_free(ctx);
309.Ed
310.Sh SEE ALSO
311.Xr evp 3 ,
312.Xr EVP_EncryptInit 3
313.Sh STANDARDS
314.Rs
315.%A A. Langley
316.%A W. Chang
317.%D November 2013
318.%R draft-agl-tls-chacha20poly1305-04
319.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
320.Re
321.Pp
322.Rs
323.%A Y. Nir
324.%A A. Langley
325.%D May 2015
326.%R RFC 7539
327.%T ChaCha20 and Poly1305 for IETF Protocols
328.Re
329.Pp
330.Rs
331.%A S. Arciszewski
332.%D October 2018
333.%R draft-arciszewski-xchacha-02
334.%T XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305
335.Re
336.Sh HISTORY
337AEAD is based on the implementation by
338.An Adam Langley
339for Chromium/BoringSSL and first appeared in
340.Ox 5.6 .
341.Pp
342.Fn EVP_AEAD_CTX_new
343and
344.Fn EVP_AEAD_CTX_free
345first appeared in
346.Ox 7.1 .
347