From 3ffb29eb7d7c39a5372f935d9d484159fb66771a Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Tue, 17 Dec 2024 18:11:44 +0000 Subject: 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@. --- src/lib/libcrypto/man/EVP_EncryptInit.3 | 58 +------- src/lib/libcrypto/man/EVP_aes_128_cbc.3 | 25 +--- src/lib/libcrypto/man/EVP_aes_128_gcm.3 | 249 ++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 3 +- 4 files changed, 260 insertions(+), 75 deletions(-) create mode 100644 src/lib/libcrypto/man/EVP_aes_128_gcm.3 (limited to 'src') 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 @@ -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 +.\" +.\" 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 +.\" 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 @@ -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 \ -- cgit v1.2.3-55-g6feb