Mention key and nonce lengths of AEAD ciphers.

Mention portability considerations regarding the EVP_AEAD API. Avoid confusing words like "older" and "native" API, be specific. Mention RFC 7905. Move publications we don't implement from STANDARDS to CAVEATS. Based on input from jsing@ and tb@, OK tb@.
author: schwarze <> 2023-08-23 13:46:42 +0000
committer: schwarze <> 2023-08-23 13:46:42 +0000
commit: 97184c838031f54fdac94903bf1398ad10376f64 (patch)
tree: 51a4c75176f2af72188f1dd4458f1ca22aba1a88 /src
parent: d9289904109bdb2232c6c3d78f74cdeff79fdfac (diff)
download: openbsd-97184c838031f54fdac94903bf1398ad10376f64.tar.gz
openbsd-97184c838031f54fdac94903bf1398ad10376f64.tar.bz2
openbsd-97184c838031f54fdac94903bf1398ad10376f64.zip
2 files changed, 105 insertions, 33 deletions
diff --git a/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 b/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3
index 269dcbd9fa..fac1696d74 100644
--- a/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3
+++ b/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.11 2023/05/09 07:19:24 tb Exp $
+.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.12 2023/08/23 13:46:42 schwarze Exp $
 .\"
 .\" Copyright (c) 2014, Google Inc.
 .\" Parts of the text were written by Adam Langley and David Benjamin.
@@ -16,7 +16,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: May 9 2023 $
+.Dd $Mdocdate: August 23 2023 $
 .Dt EVP_AEAD_CTX_INIT 3
 .Os
 .Sh NAME
@@ -245,23 +245,44 @@ All cipher algorithms have a fixed key length unless otherwise stated.
 The following ciphers are available:
 .Bl -tag -width Ds -offset indent
 .It Fn EVP_aead_aes_128_gcm
-AES-128 in Galois Counter Mode.
+AES-128 in Galois Counter Mode, using a
+.Fa key_len
+of 16 bytes and a
+.Fa nonce_len
+of 12 bytes.
 .It Fn EVP_aead_aes_256_gcm
-AES-256 in Galois Counter Mode.
+AES-256 in Galois Counter Mode, using a
+.Fa key_len
+of 32 bytes and a
+.Fa nonce_len
+of 12 bytes.
 .It Fn EVP_aead_chacha20_poly1305
-ChaCha20 with a Poly1305 authenticator.
+ChaCha20 with a Poly1305 authenticator, using a
+.Fa key_len
+of 32 bytes and a
+.Fa nonce_len
+of 12 bytes.
 .It Fn EVP_aead_xchacha20_poly1305
-XChaCha20 with a Poly1305 authenticator.
+XChaCha20 with a Poly1305 authenticator, using a
+.Fa key_len
+of 32 bytes and a
+.Fa nonce_len
+of 24 bytes.
 .El
 .Pp
-Where possible the
+Unless compatibility with other implementations
+like OpenSSL or BoringSSL is required, using the
 .Sy EVP_AEAD
-interface to AEAD ciphers should be used in preference to the older
+interface to AEAD ciphers is recommended
-.Sy EVP
+in preference to the functions documented in the
-variants or to the low level interfaces.
+.Xr EVP_EncryptInit 3 ,
-This is because the code then becomes transparent to the AEAD cipher
+.Xr EVP_aes_256_gcm 3 ,
-used and much more flexible.
+and
-It is also safer to use as it prevents common mistakes with the native APIs.
+.Xr EVP_chacha20_poly1305 3
+manual pages.
+The code then becomes transparent to the AEAD cipher used
+and much more flexible.
+It is also safer to use as it prevents common mistakes with the EVP APIs.
 .Sh RETURN VALUES
 .Fn EVP_AEAD_CTX_new
 returns the new
@@ -319,17 +340,12 @@ EVP_AEAD_CTX_free(ctx);
 .Rs
 .%A A. Langley
 .%A W. Chang
-.%D November 2013
+.%A N. Mavrogiannopoulos
-.%R draft-agl-tls-chacha20poly1305-04
+.%A J. Strombergson
-.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
+.%A S. Josefsson
-.Re
+.%D June 2016
-.Pp
+.%R RFC 7905
-.Rs
+.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS)
-.%A Y. Nir
-.%A A. Langley
-.%D May 2015
-.%R RFC 7539
-.%T ChaCha20 and Poly1305 for IETF Protocols
 .Re
 .Pp
 .Rs
@@ -341,6 +357,7 @@ EVP_AEAD_CTX_free(ctx);
 .Sh HISTORY
 AEAD is based on the implementation by
 .An Adam Langley
+.\" OpenSSL commit 9a8646510b Sep 9 12:13:24 2013 -0400
 for Chromium/BoringSSL and first appeared in
 .Ox 5.6 .
 .Pp
@@ -349,3 +366,28 @@ and
 .Fn EVP_AEAD_CTX_free
 first appeared in
 .Ox 7.1 .
+.Sh CAVEATS
+The original publications and code by
+.An Adam Langley
+used a modified AEAD construction that is incompatible with the common
+style used by AEAD in TLS and incompatible with RFC 7905:
+.Pp
+.Rs
+.%A A. Langley
+.%A W. Chang
+.%D November 2013
+.%R draft-agl-tls-chacha20poly1305-04
+.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
+.Re
+.Pp
+.Rs
+.%A Y. Nir
+.%A A. Langley
+.%D May 2015
+.%R RFC 7539
+.%T ChaCha20 and Poly1305 for IETF Protocols
+.Re
+.Pp
+In particular, the original version used a
+.Fa nonce_len
+of 8 bytes.
diff --git a/src/lib/libcrypto/man/EVP_chacha20.3 b/src/lib/libcrypto/man/EVP_chacha20.3
index 8d9ea068f9..0dcd7a14c2 100644
--- a/src/lib/libcrypto/man/EVP_chacha20.3
+++ b/src/lib/libcrypto/man/EVP_chacha20.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_chacha20.3,v 1.3 2023/08/21 03:26:42 jsg Exp $
+.\" $OpenBSD: EVP_chacha20.3,v 1.4 2023/08/23 13:46:42 schwarze Exp $
 .\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 21 2023 $
+.Dd $Mdocdate: August 23 2023 $
 .Dt EVP_CHACHA20 3
 .Os
 .Sh NAME
@@ -114,6 +114,16 @@ objects created from
 .Pp
 .Fn EVP_chacha20_poly1305
 provides authenticated encryption with ChaCha20-Poly1305.
+Unless compatibility with other implementations
+like OpenSSL or BoringSSL is required, using
+.Xr EVP_AEAD_CTX_init 3
+with
+.Xr EVP_aead_chacha20_poly1305 3
+is recommended instead because the code then becomes transparent
+to the AEAD cipher used, more flexible, and less error prone.
+.Pp
+With
+.Fn EVP_chacha20_poly1305 ,
 .Xr EVP_EncryptInit_ex 3 ,
 .Xr EVP_DecryptInit_ex 3 ,
 and
@@ -237,6 +247,32 @@ returns 1 for success or 0 for failure.
 .Rs
 .%A A. Langley
 .%A W. Chang
+.%A N. Mavrogiannopoulos
+.%A J. Strombergson
+.%A S. Josefsson
+.%D June 2016
+.%R RFC 7905
+.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS)
+.Re
+.Sh HISTORY
+.Fn EVP_chacha20
+first appeared in
+.Ox 5.6 .
+.Pp
+.Fn EVP_chacha20_poly1305
+first appeared in OpenSSL 1.1.0
+.\" OpenSSL commit bd989745 Dec 9 21:30:56 2015 +0100 Andy Polyakov
+and has been available since
+.Ox 7.2 .
+.Sh CAVEATS
+The original publications and code by
+.An Adam Langley
+used a modified AEAD construction that is incompatible with the common
+style used by AEAD in TLS and incompatible with RFC 7905:
+.Pp
+.Rs
+.%A A. Langley
+.%A W. Chang
 .%D November 2013
 .%R draft-agl-tls-chacha20poly1305-04
 .%T ChaCha20 and Poly1305 based Cipher Suites for TLS
@@ -249,11 +285,5 @@ returns 1 for success or 0 for failure.
 .%R RFC 7539
 .%T ChaCha20 and Poly1305 for IETF Protocols
 .Re
-.Sh HISTORY
-.Fn EVP_chacha20
-first appeared in
-.Ox 5.6 .
 .Pp
-.Fn EVP_chacha20_poly1305
+In particular, the original version used a nonce of 8 instead of 12 bytes.
-first appeared in OpenSSL 1.1.0 and has been available since
-.Ox 7.2 .
author	schwarze <>	2023-08-23 13:46:42 +0000
committer	schwarze <>	2023-08-23 13:46:42 +0000
commit	97184c838031f54fdac94903bf1398ad10376f64 (patch)
tree	51a4c75176f2af72188f1dd4458f1ca22aba1a88 /src
parent	d9289904109bdb2232c6c3d78f74cdeff79fdfac (diff)
download	openbsd-97184c838031f54fdac94903bf1398ad10376f64.tar.gz openbsd-97184c838031f54fdac94903bf1398ad10376f64.tar.bz2 openbsd-97184c838031f54fdac94903bf1398ad10376f64.zip

diff --git a/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 b/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 index 269dcbd9fa..fac1696d74 100644 --- a/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 +++ b/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3
@@ -1,4 +1,4 @@
1	.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.11 2023/05/09 07:19:24 tb Exp $	1	.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.12 2023/08/23 13:46:42 schwarze Exp $
2	.\"	2	.\"
3	.\" Copyright (c) 2014, Google Inc.	3	.\" Copyright (c) 2014, Google Inc.
4	.\" Parts of the text were written by Adam Langley and David Benjamin.	4	.\" Parts of the text were written by Adam Langley and David Benjamin.
@@ -16,7 +16,7 @@
16	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF	16	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.	17	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18	.\"	18	.\"
19	.Dd $Mdocdate: May 9 2023 $	19	.Dd $Mdocdate: August 23 2023 $
20	.Dt EVP_AEAD_CTX_INIT 3	20	.Dt EVP_AEAD_CTX_INIT 3
21	.Os	21	.Os
22	.Sh NAME	22	.Sh NAME
@@ -245,23 +245,44 @@ All cipher algorithms have a fixed key length unless otherwise stated.
245	The following ciphers are available:	245	The following ciphers are available:
246	.Bl -tag -width Ds -offset indent	246	.Bl -tag -width Ds -offset indent
247	.It Fn EVP_aead_aes_128_gcm	247	.It Fn EVP_aead_aes_128_gcm
248	AES-128 in Galois Counter Mode.	248	AES-128 in Galois Counter Mode, using a
		249	.Fa key_len
		250	of 16 bytes and a
		251	.Fa nonce_len
		252	of 12 bytes.
249	.It Fn EVP_aead_aes_256_gcm	253	.It Fn EVP_aead_aes_256_gcm
250	AES-256 in Galois Counter Mode.	254	AES-256 in Galois Counter Mode, using a
		255	.Fa key_len
		256	of 32 bytes and a
		257	.Fa nonce_len
		258	of 12 bytes.
251	.It Fn EVP_aead_chacha20_poly1305	259	.It Fn EVP_aead_chacha20_poly1305
252	ChaCha20 with a Poly1305 authenticator.	260	ChaCha20 with a Poly1305 authenticator, using a
		261	.Fa key_len
		262	of 32 bytes and a
		263	.Fa nonce_len
		264	of 12 bytes.
253	.It Fn EVP_aead_xchacha20_poly1305	265	.It Fn EVP_aead_xchacha20_poly1305
254	XChaCha20 with a Poly1305 authenticator.	266	XChaCha20 with a Poly1305 authenticator, using a
		267	.Fa key_len
		268	of 32 bytes and a
		269	.Fa nonce_len
		270	of 24 bytes.
255	.El	271	.El
256	.Pp	272	.Pp
257	Where possible the	273	Unless compatibility with other implementations
		274	like OpenSSL or BoringSSL is required, using the
258	.Sy EVP_AEAD	275	.Sy EVP_AEAD
259	interface to AEAD ciphers should be used in preference to the older	276	interface to AEAD ciphers is recommended
260	.Sy EVP	277	in preference to the functions documented in the
261	variants or to the low level interfaces.	278	.Xr EVP_EncryptInit 3 ,
262	This is because the code then becomes transparent to the AEAD cipher	279	.Xr EVP_aes_256_gcm 3 ,
263	used and much more flexible.	280	and
264	It is also safer to use as it prevents common mistakes with the native APIs.	281	.Xr EVP_chacha20_poly1305 3
		282	manual pages.
		283	The code then becomes transparent to the AEAD cipher used
		284	and much more flexible.
		285	It is also safer to use as it prevents common mistakes with the EVP APIs.
265	.Sh RETURN VALUES	286	.Sh RETURN VALUES
266	.Fn EVP_AEAD_CTX_new	287	.Fn EVP_AEAD_CTX_new
267	returns the new	288	returns the new
@@ -319,17 +340,12 @@ EVP_AEAD_CTX_free(ctx);
319	.Rs	340	.Rs
320	.%A A. Langley	341	.%A A. Langley
321	.%A W. Chang	342	.%A W. Chang
322	.%D November 2013	343	.%A N. Mavrogiannopoulos
323	.%R draft-agl-tls-chacha20poly1305-04	344	.%A J. Strombergson
324	.%T ChaCha20 and Poly1305 based Cipher Suites for TLS	345	.%A S. Josefsson
325	.Re	346	.%D June 2016
326	.Pp	347	.%R RFC 7905
327	.Rs	348	.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS)
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	349	.Re
334	.Pp	350	.Pp
335	.Rs	351	.Rs
@@ -341,6 +357,7 @@ EVP_AEAD_CTX_free(ctx);
341	.Sh HISTORY	357	.Sh HISTORY
342	AEAD is based on the implementation by	358	AEAD is based on the implementation by
343	.An Adam Langley	359	.An Adam Langley
		360	.\" OpenSSL commit 9a8646510b Sep 9 12:13:24 2013 -0400
344	for Chromium/BoringSSL and first appeared in	361	for Chromium/BoringSSL and first appeared in
345	.Ox 5.6 .	362	.Ox 5.6 .
346	.Pp	363	.Pp
@@ -349,3 +366,28 @@ and
349	.Fn EVP_AEAD_CTX_free	366	.Fn EVP_AEAD_CTX_free
350	first appeared in	367	first appeared in
351	.Ox 7.1 .	368	.Ox 7.1 .
		369	.Sh CAVEATS
		370	The original publications and code by
		371	.An Adam Langley
		372	used a modified AEAD construction that is incompatible with the common
		373	style used by AEAD in TLS and incompatible with RFC 7905:
		374	.Pp
		375	.Rs
		376	.%A A. Langley
		377	.%A W. Chang
		378	.%D November 2013
		379	.%R draft-agl-tls-chacha20poly1305-04
		380	.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
		381	.Re
		382	.Pp
		383	.Rs
		384	.%A Y. Nir
		385	.%A A. Langley
		386	.%D May 2015
		387	.%R RFC 7539
		388	.%T ChaCha20 and Poly1305 for IETF Protocols
		389	.Re
		390	.Pp
		391	In particular, the original version used a
		392	.Fa nonce_len
		393	of 8 bytes.


diff --git a/src/lib/libcrypto/man/EVP_chacha20.3 b/src/lib/libcrypto/man/EVP_chacha20.3 index 8d9ea068f9..0dcd7a14c2 100644 --- a/src/lib/libcrypto/man/EVP_chacha20.3 +++ b/src/lib/libcrypto/man/EVP_chacha20.3
@@ -1,4 +1,4 @@
1	.\" $OpenBSD: EVP_chacha20.3,v 1.3 2023/08/21 03:26:42 jsg Exp $	1	.\" $OpenBSD: EVP_chacha20.3,v 1.4 2023/08/23 13:46:42 schwarze Exp $
2	.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200	2	.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
3	.\"	3	.\"
4	.\" This file is a derived work.	4	.\" This file is a derived work.
@@ -65,7 +65,7 @@
65	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	65	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	66	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67	.\"	67	.\"
68	.Dd $Mdocdate: August 21 2023 $	68	.Dd $Mdocdate: August 23 2023 $
69	.Dt EVP_CHACHA20 3	69	.Dt EVP_CHACHA20 3
70	.Os	70	.Os
71	.Sh NAME	71	.Sh NAME
@@ -114,6 +114,16 @@ objects created from
114	.Pp	114	.Pp
115	.Fn EVP_chacha20_poly1305	115	.Fn EVP_chacha20_poly1305
116	provides authenticated encryption with ChaCha20-Poly1305.	116	provides authenticated encryption with ChaCha20-Poly1305.
		117	Unless compatibility with other implementations
		118	like OpenSSL or BoringSSL is required, using
		119	.Xr EVP_AEAD_CTX_init 3
		120	with
		121	.Xr EVP_aead_chacha20_poly1305 3
		122	is recommended instead because the code then becomes transparent
		123	to the AEAD cipher used, more flexible, and less error prone.
		124	.Pp
		125	With
		126	.Fn EVP_chacha20_poly1305 ,
117	.Xr EVP_EncryptInit_ex 3 ,	127	.Xr EVP_EncryptInit_ex 3 ,
118	.Xr EVP_DecryptInit_ex 3 ,	128	.Xr EVP_DecryptInit_ex 3 ,
119	and	129	and
@@ -237,6 +247,32 @@ returns 1 for success or 0 for failure.
237	.Rs	247	.Rs
238	.%A A. Langley	248	.%A A. Langley
239	.%A W. Chang	249	.%A W. Chang
		250	.%A N. Mavrogiannopoulos
		251	.%A J. Strombergson
		252	.%A S. Josefsson
		253	.%D June 2016
		254	.%R RFC 7905
		255	.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS)
		256	.Re
		257	.Sh HISTORY
		258	.Fn EVP_chacha20
		259	first appeared in
		260	.Ox 5.6 .
		261	.Pp
		262	.Fn EVP_chacha20_poly1305
		263	first appeared in OpenSSL 1.1.0
		264	.\" OpenSSL commit bd989745 Dec 9 21:30:56 2015 +0100 Andy Polyakov
		265	and has been available since
		266	.Ox 7.2 .
		267	.Sh CAVEATS
		268	The original publications and code by
		269	.An Adam Langley
		270	used a modified AEAD construction that is incompatible with the common
		271	style used by AEAD in TLS and incompatible with RFC 7905:
		272	.Pp
		273	.Rs
		274	.%A A. Langley
		275	.%A W. Chang
240	.%D November 2013	276	.%D November 2013
241	.%R draft-agl-tls-chacha20poly1305-04	277	.%R draft-agl-tls-chacha20poly1305-04
242	.%T ChaCha20 and Poly1305 based Cipher Suites for TLS	278	.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
@@ -249,11 +285,5 @@ returns 1 for success or 0 for failure.
249	.%R RFC 7539	285	.%R RFC 7539
250	.%T ChaCha20 and Poly1305 for IETF Protocols	286	.%T ChaCha20 and Poly1305 for IETF Protocols
251	.Re	287	.Re
252	.Sh HISTORY
253	.Fn EVP_chacha20
254	first appeared in
255	.Ox 5.6 .
256	.Pp	288	.Pp
257	.Fn EVP_chacha20_poly1305	289	In particular, the original version used a nonce of 8 instead of 12 bytes.
258	first appeared in OpenSSL 1.1.0 and has been available since
259	.Ox 7.2 .