From a16ee84e63460156ce6979aa104f14ca17da9f2a Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Wed, 23 Aug 2023 13:46:42 +0000
Subject: [PATCH] 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@.
---
 lib/libcrypto/man/EVP_AEAD_CTX_init.3 | 90 ++++++++++++++++++++-------
 lib/libcrypto/man/EVP_chacha20.3      | 48 +++++++++++---
 2 files changed, 105 insertions(+), 33 deletions(-)

diff --git a/lib/libcrypto/man/EVP_AEAD_CTX_init.3 b/lib/libcrypto/man/EVP_AEAD_CTX_init.3
index 269dcbd9fa2..fac1696d749 100644
--- a/lib/libcrypto/man/EVP_AEAD_CTX_init.3
+++ b/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
-.Sy EVP
-variants or to the low level interfaces.
-This is because 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 native APIs.
+interface to AEAD ciphers is recommended
+in preference to the functions documented in the
+.Xr EVP_EncryptInit 3 ,
+.Xr EVP_aes_256_gcm 3 ,
+and
+.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
-.%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
+.%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
 .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/lib/libcrypto/man/EVP_chacha20.3 b/lib/libcrypto/man/EVP_chacha20.3
index 8d9ea068f99..0dcd7a14c2c 100644
--- a/lib/libcrypto/man/EVP_chacha20.3
+++ b/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
-first appeared in OpenSSL 1.1.0 and has been available since
-.Ox 7.2 .
+In particular, the original version used a nonce of 8 instead of 12 bytes.
-- 
2.20.1