New manual page EVP_aes_128_gcm(3).

The main benefit is moving the cumbersome and error-prone method of
using EVP_EncryptInit(3) for AES-GCM out of the important, but obese
manual page EVP_EncryptInit(3), and to create a logical place for
pointing readers to the safer and more flexible EVP_AEAD_CTX_init(3).

As a side benefit, document three control commands that were so far
undocumented and make the description of three others more precise.

Feedback and OK tb@.

4 files changed, 260 insertions, 75 deletions

diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3
index 3e0cec8f9e..8f977b7a2a 100644
--- a/src/lib/libcrypto/man/EVP_EncryptInit.3
+++ b/src/lib/libcrypto/man/EVP_EncryptInit.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_EncryptInit.3,v 1.54 2024/12/08 17:41:23 schwarze Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.55 2024/12/17 18:11:44 schwarze Exp $
 .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800
 .\"   EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod
 .\"   7c6d372a Nov 20 13:20:01 2018 +0000
@@ -69,7 +69,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 8 2024 $
+.Dd $Mdocdate: December 17 2024 $
 .Dt EVP_ENCRYPTINIT 3
 .Os
 .Sh NAME
@@ -600,6 +600,7 @@ Some algorithms are documented in separate manual pages:
 .Bl -column "EVP_camellia_128_cbc(3)" "block size" -compact
 .It manual page               Ta block size Ta Fa key No size Pq in bits
 .It Xr EVP_aes_128_cbc 3      Ta 128        Ta 128, 192, 256
+.It Xr EVP_aes_128_gcm 3      Ta 128        Ta 128, 192, 256
 .It Xr EVP_camellia_128_cbc 3 Ta 128        Ta 128, 192, 256
 .It Xr EVP_chacha20 3         Ta stream     Ta 256
 .It Xr EVP_des_cbc 3          Ta 64         Ta 64
@@ -607,58 +608,6 @@ Some algorithms are documented in separate manual pages:
 .It Xr EVP_rc4 3              Ta stream     Ta variable, default 128
 .It Xr EVP_sm4_cbc 3          Ta 128        Ta 128
 .El
-.Ss GCM mode
-For GCM mode ciphers, the behaviour of the EVP interface
-is subtly altered and several additional ctrl operations are
-supported.
-.Pp
-To specify any additional authenticated data (AAD), a call to
-.Fn EVP_CipherUpdate ,
-.Fn EVP_EncryptUpdate ,
-or
-.Fn EVP_DecryptUpdate
-should be made with the output parameter
-.Fa out
-set to
-.Dv NULL .
-.Pp
-When decrypting, the return value of
-.Fn EVP_DecryptFinal ,
-.Fn EVP_DecryptFinal_ex ,
-.Fn EVP_CipherFinal ,
-or
-.Fn EVP_CipherFinal_ex
-indicates if the operation was successful.
-If it does not indicate success, the authentication operation has
-failed and any output data MUST NOT be used as it is corrupted.
-.Pp
-The following ctrls are supported in GCM mode:
-.Bl -tag -width Ds
-.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_IVLEN ivlen NULL
-Sets the IV length: this call can only be made before specifying an IV.
-If not called, a default IV length is used.
-For GCM AES the default is 12, i.e. 96 bits.
-.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_GET_TAG taglen tag
-Writes
-.Fa taglen
-bytes of the tag value to the buffer indicated by
-.Fa tag .
-This call can only be made when encrypting data and after all data has
-been processed, e.g. after an
-.Fn EVP_EncryptFinal
-or
-.Fn EVP_EncryptFinal_ex
-call.
-.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag
-Sets the expected tag to
-.Fa taglen
-bytes from
-.Fa tag .
-This call is only legal when decrypting data and must be made before
-any data is processed, e.g. before any
-.Fa EVP_DecryptUpdate
-call.
-.El
 .Ss CCM mode
 The behaviour of CCM mode ciphers is similar to GCM mode, but with
 a few additional requirements and different ctrl values.
@@ -821,6 +770,7 @@ do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt)
 .Xr evp 3 ,
 .Xr EVP_AEAD_CTX_init 3 ,
 .Xr EVP_aes_128_cbc 3 ,
+.Xr EVP_aes_128_gcm 3 ,
 .Xr EVP_camellia_128_cbc 3 ,
 .Xr EVP_chacha20 3 ,
 .Xr EVP_CIPHER_CTX_ctrl 3 ,
diff --git a/src/lib/libcrypto/man/EVP_aes_128_cbc.3 b/src/lib/libcrypto/man/EVP_aes_128_cbc.3
index 6249bf7348..cbb68e1543 100644
--- a/src/lib/libcrypto/man/EVP_aes_128_cbc.3
+++ b/src/lib/libcrypto/man/EVP_aes_128_cbc.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.6 2024/11/09 22:03:49 schwarze Exp $
+.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.7 2024/12/17 18:11:44 schwarze Exp $
 .\" selective merge up to: OpenSSL 7c6d372a Nov 20 13:20:01 2018 +0000
 .\"
 .\" This file was written by Ronald Tse <ronald.tse@ribose.com>
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 9 2024 $
+.Dd $Mdocdate: December 17 2024 $
 .Dt EVP_AES_128_CBC 3
 .Os
 .Sh NAME
@@ -81,9 +81,6 @@
 .Nm EVP_aes_128_ccm ,
 .Nm EVP_aes_192_ccm ,
 .Nm EVP_aes_256_ccm ,
-.Nm EVP_aes_128_gcm ,
-.Nm EVP_aes_192_gcm ,
-.Nm EVP_aes_256_gcm ,
 .Nm EVP_aes_128_wrap ,
 .Nm EVP_aes_192_wrap ,
 .Nm EVP_aes_256_wrap ,
@@ -151,12 +148,6 @@
 .Ft const EVP_CIPHER *
 .Fn EVP_aes_256_ccm void
 .Ft const EVP_CIPHER *
-.Fn EVP_aes_128_gcm void
-.Ft const EVP_CIPHER *
-.Fn EVP_aes_192_gcm void
-.Ft const EVP_CIPHER *
-.Fn EVP_aes_256_gcm void
-.Ft const EVP_CIPHER *
 .Fn EVP_aes_128_wrap void
 .Ft const EVP_CIPHER *
 .Fn EVP_aes_192_wrap void
@@ -222,13 +213,9 @@ These ciphers do not conform to the EVP AEAD interface.
 .Pp
 .Fn EVP_aes_128_ccm ,
 .Fn EVP_aes_192_ccm ,
-.Fn EVP_aes_256_ccm ,
-.Fn EVP_aes_128_gcm ,
-.Fn EVP_aes_192_gcm ,
 and
-.Fn EVP_aes_256_gcm
-provide AES for 128, 192 and 256-bit keys in CBC-MAC Mode (CCM)
-and Galois Counter Mode (GCM), respectively.
+.Fn EVP_aes_256_ccm
+provide AES for 128, 192 and 256-bit keys in CBC-MAC Mode (CCM), respectively.
 These ciphers require additional control operations to function
 correctly; see
 .Xr EVP_EncryptInit 3
@@ -284,6 +271,7 @@ structure that provides the implementation of the symmetric cipher.
 .Sh SEE ALSO
 .Xr AES_encrypt 3 ,
 .Xr evp 3 ,
+.Xr EVP_aes_128_gcm 3 ,
 .Xr EVP_EncryptInit 3
 .Sh HISTORY
 .Fn EVP_aes_128_cbc ,
@@ -323,9 +311,6 @@ first appeared in OpenSSL 0.9.7e and have been available since
 .Fn EVP_aes_128_ccm ,
 .Fn EVP_aes_192_ccm ,
 .Fn EVP_aes_256_ccm ,
-.Fn EVP_aes_128_gcm ,
-.Fn EVP_aes_192_gcm ,
-.Fn EVP_aes_256_gcm ,
 .Fn EVP_aes_128_xts ,
 and
 .Fn EVP_aes_256_xts
diff --git a/src/lib/libcrypto/man/EVP_aes_128_gcm.3 b/src/lib/libcrypto/man/EVP_aes_128_gcm.3
new file mode 100644
index 0000000000..1e15cb79aa
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_aes_128_gcm.3
@@ -0,0 +1,249 @@
+.\" $OpenBSD: EVP_aes_128_gcm.3,v 1.1 2024/12/17 18:11:44 schwarze Exp $
+.\" full merge up to:
+.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100
+.\" OpenSSL EVP_aes.pod a1ec85c1 Apr 21 10:49:12 2020 +0100
+.\"
+.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" This file is a derived work containing a few sentences
+.\" written by Dr. Stephen Henson <steve@openssl.org>
+.\" covered by the following license:
+.\"
+.\" Copyright (c) 2012 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 17 2024 $
+.Dt EVP_AES_128_GCM 3
+.Os
+.Sh NAME
+.Nm EVP_aes_128_gcm ,
+.Nm EVP_aes_192_gcm ,
+.Nm EVP_aes_256_gcm
+.Nd EVP AES cipher in Galois Counter Mode
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft const EVP_CIPHER *
+.Fn EVP_aes_128_gcm void
+.Ft const EVP_CIPHER *
+.Fn EVP_aes_192_gcm void
+.Ft const EVP_CIPHER *
+.Fn EVP_aes_256_gcm void
+.Sh DESCRIPTION
+.Fn EVP_aes_128_gcm ,
+.Fn EVP_aes_192_gcm ,
+and
+.Fn EVP_aes_256_gcm
+provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit
+keys in and Galois Counter Mode in the
+.Xr evp 3
+framework.
+.Pp
+For GCM mode ciphers, the behaviour of the EVP interface is subtly
+altered and several additional
+.Xr EVP_CIPHER_CTX_ctrl 3
+operations are required to function correctly.
+.Pp
+To avoid using the cumbersome and error-prone API documented
+in the present manual page, consider using the functions documented in
+.Xr EVP_AEAD_CTX_init 3
+instead.
+.Ss Configuration controls
+.\" The following constants are intentionally undocumented
+.\" because they are very rarely used in application programs:
+.\" EVP_GCM_TLS_FIXED_IV_LEN (unused in the library)
+.\" EVP_GCM_TLS_EXPLICIT_IV_LEN and EVP_GCM_TLS_TAG_LEN (used internally
+.\" only in aes_gcm_tls_cipher(), which is unused)
+.Bl -tag -width Ds
+.It Dv EVP_CTRL_GCM_SET_IVLEN
+Set the length of the initialization vector to
+.Fa arg
+bytes; the
+.Fa ptr
+argument is ignored and passing
+.Dv NULL
+is recommended.
+This call can only be made before specifying an initialization vector.
+If not called, the default IV length of 12 bytes is used.
+.Pp
+Using this control command is discouraged because section 5.2.1.1 of the
+specification explicitly recommends that implementations of GCM restrict
+support to the default IV length of 12 bytes for interoperability,
+efficiency, and simplicity of design.
+.It Dv EVP_CTRL_GCM_SET_IV_FIXED
+Usually, \-1 is passed for
+.Fa arg .
+In that case, the complete initialization vector is copied from
+.Fa ptr .
+.Pp
+Otherwise, set the fixed field at the beginning of the initialization
+vector to the
+.Fa arg
+bytes pointed to by
+.Fa ptr .
+When encrypting, also generate the remaining bytes
+of the initialization vector at random.
+It is an error to specify an
+.Fa arg
+that is less than 4 or so large that less than 8 bytes remain.
+.El
+.Ss Encryption controls
+.Bl -tag -width Ds
+.It Dv EVP_CTRL_GCM_IV_GEN
+Generate the precounter block from the initialization vector,
+copy the last
+.Fa arg
+bytes of the initialization vector to the location pointed to by
+.Fa ptr ,
+or all of it if
+.Fa arg
+is less than 1 or greater than the length of the initialization vector,
+and increment the initialization vector by 1.
+Incrementing ignores the IV length and the fixed field length
+that may have been configured earlier and always operates on the
+last eight bytes of the initialization vector.
+It is an error to issue this command
+when no key or no initialization vector is set.
+.It Dv EVP_CTRL_GCM_GET_TAG
+Write
+.Fa arg
+bytes of the tag value to the location pointed to by
+.Fa ptr .
+This control command only makes sense after all data has been processed,
+e.g. after calling
+.Xr EVP_EncryptFinal 3 .
+It is an error to issue this command while decrypting,
+before any data has been processed, or to specify an
+.Fa arg
+that is less than 1 or greater than 16.
+.El
+.Pp
+To specify any additional authenticated data (AAD), call
+.Xr EVP_EncryptUpdate 3
+with the
+.Fa out
+argument set to
+.Dv NULL .
+.Ss Decryption controls
+.Bl -tag -width Ds
+.It Dv EVP_CTRL_GCM_SET_IV_INV
+Copy
+.Fa arg
+bytes from
+.Fa ptr
+to the last bytes of the initialization vector
+and generate the precounter block from the initialization vector.
+The library does not check whether the arguments are consistent
+with the configured initialization vector and fixed field lengths.
+When default lengths are in use, pass 8 for
+.Fa arg .
+In that case, this control command sets the invocation field.
+It is an error to issue this command
+when no key or no initialization vector is set, or when encrypting.
+.It Dv EVP_CTRL_GCM_SET_TAG
+Set the expected tag to the
+.Fa arg
+bytes located at
+.Fa ptr .
+This control command is mandatory before any data is processed,
+e.g. before calling
+.Xr EVP_DecryptUpdate 3 .
+It is an error to issue this command while encrypting or to specify an
+.Fa arg
+that is less than 1 or greater than 16.
+.El
+.Pp
+To specify any additional authenticated data (AAD), call
+.Xr EVP_DecryptUpdate 3
+with the
+.Fa out
+argument set to
+.Dv NULL .
+.Pp
+If the return value of
+.Xr EVP_DecryptFinal 3 ,
+.Xr EVP_DecryptFinal_ex 3 ,
+.Xr EVP_CipherFinal 3 ,
+or
+.Xr EVP_CipherFinal_ex 3
+does not indicate success when decrypting,
+the authentication operation failed.
+In that case, regard any output data as corrupted.
+.Sh SEE ALSO
+.Xr AES_encrypt 3 ,
+.Xr evp 3 ,
+.Xr EVP_AEAD_CTX_init 3 ,
+.Xr EVP_aes_128_cbc 3 ,
+.Xr EVP_CIPHER_CTX_ctrl 3 ,
+.Xr EVP_EncryptInit 3
+.Sh STANDARDS
+.Rs
+.%A Morris Dworkin
+.%I National Institute of Standards and Technology
+.%R Recommendation for Block Cipher Modes of Operation:\
+ Galois/Counter Mode (GCM) and GMAC
+.%N NIST Special Publication 800-38D
+.%C Gaithersburg, Maryland
+.%D November 2007
+.Re
+.Sh HISTORY
+.Fn EVP_aes_128_gcm ,
+.Fn EVP_aes_192_gcm ,
+and
+.Fn EVP_aes_256_gcm
+first appeared in OpenSSL 1.0.1 and have been available since
+.Ox 5.3 .
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index c69fe73af2..137540c69a 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.300 2024/12/08 17:41:23 schwarze Exp $
+# $OpenBSD: Makefile,v 1.301 2024/12/17 18:11:44 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -196,6 +196,7 @@ MAN=	\
         EVP_SignInit.3 \
         EVP_VerifyInit.3 \
         EVP_aes_128_cbc.3 \
+        EVP_aes_128_gcm.3 \
         EVP_camellia_128_cbc.3 \
         EVP_chacha20.3 \
         EVP_des_cbc.3 \