From 5101a881aa58b68350e6e84a35942d6fb2a0c89c Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 1 Dec 2023 10:40:21 +0000 Subject: [PATCH] EVP_EncryptInit(3) is among the most important "how to drive" manuals, but it is still excessively long and complicated. To reduce the amount of distractions a bit, split out three deprecated functions into a new manual page EVP_CIPHER_CTX_init(3). No text change. In part suggested by tb@, who agrees with the direction. --- lib/libcrypto/man/EVP_CIPHER_CTX_init.3 | 150 ++++++++++++++++++++++++ lib/libcrypto/man/EVP_EncryptInit.3 | 72 ++---------- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/evp.3 | 5 +- 4 files changed, 165 insertions(+), 65 deletions(-) create mode 100644 lib/libcrypto/man/EVP_CIPHER_CTX_init.3 diff --git a/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 b/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 new file mode 100644 index 00000000000..3bb40018f57 --- /dev/null +++ b/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 @@ -0,0 +1,150 @@ +.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.1 2023/12/01 10:40:21 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Richard Levitte . +.\" Copyright (c) 2000-2001, 2015 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 1 2023 $ +.Dt EVP_CIPHER_CTX_INIT 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_init , +.Nm EVP_CIPHER_CTX_cleanup , +.Nm EVP_Cipher +.Nd obsolete EVP cipher functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft void +.Fo EVP_CIPHER_CTX_init +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_cleanup +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_Cipher +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "const unsigned char *in" +.Fa "unsigned int inl" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_CTX_init +is a deprecated function to clear a cipher context on the stack +before use. +Do not use it on a cipher context returned from +.Xr EVP_CIPHER_CTX_new 3 +or one that was already used. +.Pp +.Fn EVP_CIPHER_CTX_cleanup +is a deprecated alias for +.Xr EVP_CIPHER_CTX_reset 3 . +It clears all information from +.Fa ctx +and frees all allocated memory associated with it, except the +.Fa ctx +object itself. +.Pp +.Fn EVP_Cipher +encrypts or decrypts aligned blocks of data +whose lengths match the cipher block size. +It requires that the previous encryption or decryption operation +using the same +.Fa ctx , +if there was any, ended exactly on a block boundary and that +.Fa inl +is an integer multiple of the cipher block size. +If either of these conditions is violated, +.Fn EVP_Cipher +silently produces incorrect results. +For that reason, using the function +.Xr EVP_CipherUpdate 3 +instead is strongly recommended. +The latter can safely handle partial blocks, and even if +.Fa inl +actually is a multiple of the cipher block size for all calls, +the overhead incurred by using +.Xr EVP_CipherUpdate 3 +is minimal. +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_cleanup +and +.Fn EVP_Cipher +return 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_Cipher +first appeared in SSLeay 0.6.5. +.Fn EVP_CIPHER_CTX_cleanup +first appeared in SSLeay 0.8.0. +.Fn EVP_CIPHER_CTX_init +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3 index ddec4e7e796..8fc615b07ee 100644 --- a/lib/libcrypto/man/EVP_EncryptInit.3 +++ b/lib/libcrypto/man/EVP_EncryptInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_EncryptInit.3,v 1.48 2023/08/31 17:27:41 schwarze Exp $ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.49 2023/12/01 10:40:21 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,14 +69,12 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 31 2023 $ +.Dd $Mdocdate: December 1 2023 $ .Dt EVP_ENCRYPTINIT 3 .Os .Sh NAME .Nm EVP_CIPHER_CTX_new , .Nm EVP_CIPHER_CTX_reset , -.Nm EVP_CIPHER_CTX_cleanup , -.Nm EVP_CIPHER_CTX_init , .Nm EVP_CIPHER_CTX_free , .Nm EVP_CIPHER_CTX_copy , .Nm EVP_EncryptInit_ex , @@ -94,7 +92,6 @@ .Nm EVP_DecryptFinal , .Nm EVP_CipherInit , .Nm EVP_CipherFinal , -.Nm EVP_Cipher , .Nm EVP_CIPHER_CTX_encrypting , .Nm EVP_get_cipherbyname , .Nm EVP_get_cipherbynid , @@ -132,14 +129,6 @@ .Fo EVP_CIPHER_CTX_reset .Fa "EVP_CIPHER_CTX *ctx" .Fc -.Ft int -.Fo EVP_CIPHER_CTX_cleanup -.Fa "EVP_CIPHER_CTX *ctx" -.Fc -.Ft void -.Fo EVP_CIPHER_CTX_init -.Fa "EVP_CIPHER_CTX *ctx" -.Fc .Ft void .Fo EVP_CIPHER_CTX_free .Fa "EVP_CIPHER_CTX *ctx" @@ -257,13 +246,6 @@ .Fa "int *outl" .Fc .Ft int -.Fo EVP_Cipher -.Fa "EVP_CIPHER_CTX *ctx" -.Fa "unsigned char *out" -.Fa "const unsigned char *in" -.Fa "unsigned int inl" -.Fc -.Ft int .Fo EVP_CIPHER_CTX_encrypting .Fa "const EVP_CIPHER_CTX *ctx" .Fc @@ -300,16 +282,6 @@ object itself, such that it can be reused for another series of calls to .Fn EVP_CipherUpdate , and .Fn EVP_CipherFinal . -.Fn EVP_CIPHER_CTX_cleanup -is a deprecated alias for -.Fn EVP_CIPHER_CTX_reset . -.Pp -.Fn EVP_CIPHER_CTX_init -is a deprecated function to clear a cipher context on the stack -before use. -Do not use it on a cipher context returned from -.Fn EVP_CIPHER_CTX_new -or one that was already used. .Pp .Fn EVP_CIPHER_CTX_free clears all information from @@ -507,28 +479,6 @@ or .Fn EVP_CIPHER_CTX_free must be called to free any context resources. .Pp -.Fn EVP_Cipher -encrypts or decrypts aligned blocks of data -whose lengths match the cipher block size. -It requires that the previous encryption or decryption operation -using the same -.Fa ctx , -if there was any, ended exactly on a block boundary and that -.Fa inl -is an integer multiple of the cipher block size. -If either of these conditions is violated, -.Fn EVP_Cipher -silently produces incorrect results. -For that reason, using the function -.Fn EVP_CipherUpdate -instead is strongly recommended. -The latter can safely handle partial blocks, and even if -.Fa inl -actually is a multiple of the cipher block size for all calls, -the overhead incurred by using -.Fn EVP_CipherUpdate -is minimal. -.Pp .Fn EVP_get_cipherbyname , .Fn EVP_get_cipherbynid , and @@ -602,7 +552,6 @@ for success or for failure. .Pp .Fn EVP_CIPHER_CTX_reset , -.Fn EVP_CIPHER_CTX_cleanup , .Fn EVP_CIPHER_CTX_copy , .Fn EVP_EncryptInit_ex , .Fn EVP_EncryptUpdate , @@ -618,9 +567,8 @@ for failure. .Fn EVP_DecryptInit , .Fn EVP_DecryptFinal , .Fn EVP_CipherInit , -.Fn EVP_CipherFinal , and -.Fn EVP_Cipher +.Fn EVP_CipherFinal return 1 for success or 0 for failure. .Pp .Fn EVP_CIPHER_CTX_encrypting @@ -729,7 +677,9 @@ To specify any additional authenticated data (AAD), a call to .Fn EVP_EncryptUpdate , or .Fn EVP_DecryptUpdate -should be made with the output parameter out set to +should be made with the output parameter +.Fa out +set to .Dv NULL . .Pp When decrypting, the return value of @@ -775,7 +725,9 @@ by calling .Fn EVP_EncryptUpdate , or .Fn EVP_DecryptUpdate -with the output parameter out set to +with the output parameter +.Fa out +set to .Dv NULL . Additionally, the total plaintext or ciphertext length MUST be passed to @@ -929,6 +881,7 @@ do_crypt(FILE *in, FILE *out, int do_encrypt) .Xr EVP_chacha20 3 , .Xr EVP_CIPHER_CTX_ctrl 3 , .Xr EVP_CIPHER_CTX_get_cipher_data 3 , +.Xr EVP_CIPHER_CTX_init 3 , .Xr EVP_CIPHER_CTX_set_flags 3 , .Xr EVP_CIPHER_nid 3 , .Xr EVP_des_cbc 3 , @@ -959,15 +912,12 @@ first appeared in SSLeay 0.5.1. and .Fn EVP_rc2_ofb first appeared in SSLeay 0.5.2. -.Fn EVP_Cipher -first appeared in SSLeay 0.6.5. .Fn EVP_bf_cbc , .Fn EVP_bf_ecb , .Fn EVP_bf_cfb , and .Fn EVP_bf_ofb first appeared in SSLeay 0.6.6. -.Fn EVP_CIPHER_CTX_cleanup , .Fn EVP_get_cipherbyobj , .Fn EVP_CIPHER_CTX_cipher , and @@ -975,8 +925,6 @@ and first appeared in SSLeay 0.8.0. .Fn EVP_get_cipherbynid first appeared in SSLeay 0.8.1. -.Fn EVP_CIPHER_CTX_init -first appeared in SSLeay 0.9.0. All these functions have been available since .Ox 2.4 . .Pp diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 01be881165b..a5cd8c53d1f 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.277 2023/11/19 10:36:14 tb Exp $ +# $OpenBSD: Makefile,v 1.278 2023/12/01 10:40:21 schwarze Exp $ .include @@ -158,6 +158,7 @@ MAN= \ EVP_BytesToKey.3 \ EVP_CIPHER_CTX_ctrl.3 \ EVP_CIPHER_CTX_get_cipher_data.3 \ + EVP_CIPHER_CTX_init.3 \ EVP_CIPHER_CTX_set_flags.3 \ EVP_CIPHER_do_all.3 \ EVP_CIPHER_meth_new.3 \ diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index 9ae3012667d..9ce7ac83a81 100644 --- a/lib/libcrypto/man/evp.3 +++ b/lib/libcrypto/man/evp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: evp.3,v 1.25 2023/11/19 10:25:28 tb Exp $ +.\" $OpenBSD: evp.3,v 1.26 2023/12/01 10:40:21 schwarze Exp $ .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Ulf Moeller , @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 19 2023 $ +.Dd $Mdocdate: December 1 2023 $ .Dt EVP 3 .Os .Sh NAME @@ -175,6 +175,7 @@ family of functions provides base64 encoding and decoding. .Xr EVP_chacha20 3 , .Xr EVP_CIPHER_CTX_ctrl 3 , .Xr EVP_CIPHER_CTX_get_cipher_data 3 , +.Xr EVP_CIPHER_CTX_init 3 , .Xr EVP_CIPHER_CTX_set_flags 3 , .Xr EVP_CIPHER_do_all 3 , .Xr EVP_CIPHER_meth_new 3 , -- 2.20.1