From 714de72ef79567e1eda9e297e3120252140151ae Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 8 Dec 2024 17:41:23 +0000 Subject: Move the algorithm-specific functions EVP_rc2_*(3) out of EVP_EncryptInit(3) and document them properly in their own manual page, including the control commands EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS that were so far undocumented. Arguably, the main benefit is another small step making the important, but still obese EVP_EncryptInit(3) manual page more palatable. --- src/lib/libcrypto/man/EVP_CIPHER_CTX_ctrl.3 | 8 +- src/lib/libcrypto/man/EVP_EncryptInit.3 | 56 +------- src/lib/libcrypto/man/EVP_rc2_cbc.3 | 201 ++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 4 +- 4 files changed, 214 insertions(+), 55 deletions(-) create mode 100644 src/lib/libcrypto/man/EVP_rc2_cbc.3 (limited to 'src') diff --git a/src/lib/libcrypto/man/EVP_CIPHER_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_CIPHER_CTX_ctrl.3 index ba0e4b074d..a75b722cd4 100644 --- a/src/lib/libcrypto/man/EVP_CIPHER_CTX_ctrl.3 +++ b/src/lib/libcrypto/man/EVP_CIPHER_CTX_ctrl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_CIPHER_CTX_ctrl.3,v 1.2 2023/10/01 18:23:50 tb Exp $ +.\" $OpenBSD: EVP_CIPHER_CTX_ctrl.3,v 1.3 2024/12/08 17:41:23 schwarze Exp $ .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 .\" .\" This file is a derived work. @@ -67,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: October 1 2023 $ +.Dd $Mdocdate: December 8 2024 $ .Dt EVP_CIPHER_CTX_CTRL 3 .Os .Sh NAME @@ -131,7 +131,9 @@ .Sh DESCRIPTION .Fn EVP_CIPHER_CTX_ctrl allows various cipher specific parameters to be determined and set. -Currently only the RC2 effective key length can be set. +Currently only the RC2 effective key length can be set; see +.Xr EVP_rc2_cbc 3 +for details. .Pp .Fn EVP_CIPHER_CTX_set_padding enables or disables padding. diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3 index 32ed3349b9..3e0cec8f9e 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.53 2024/11/09 22:03:49 schwarze Exp $ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.54 2024/12/08 17:41:23 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: November 9 2024 $ +.Dd $Mdocdate: December 8 2024 $ .Dt EVP_ENCRYPTINIT 3 .Os .Sh NAME @@ -103,13 +103,6 @@ .Nm EVP_idea_cfb64 , .Nm EVP_idea_cfb , .Nm EVP_idea_ofb , -.Nm EVP_rc2_cbc , -.Nm EVP_rc2_ecb , -.Nm EVP_rc2_cfb64 , -.Nm EVP_rc2_cfb , -.Nm EVP_rc2_ofb , -.Nm EVP_rc2_40_cbc , -.Nm EVP_rc2_64_cbc , .Nm EVP_bf_cbc , .Nm EVP_bf_ecb , .Nm EVP_bf_cfb64 , @@ -570,34 +563,6 @@ is an alias for .Fn EVP_idea_cfb64 , implemented as a macro. .It Xo -.Fn EVP_rc2_cbc , -.Fn EVP_rc2_ecb , -.Fn EVP_rc2_cfb64 , -.Fn EVP_rc2_ofb -.Xc -RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. -RC2 is a block cipher operating on 64 bit blocks using a variable -.Fa key -length with an additional parameter called -"effective key bits" or "effective key length". -By default both are set to 128 bits. -.Fn EVP_rc2_cfb -is an alias for -.Fn EVP_rc2_cfb64 , -implemented as a macro. -.It Xo -.Fn EVP_rc2_40_cbc , -.Fn EVP_rc2_64_cbc -.Xc -RC2 algorithm in CBC mode with a default key length and effective key -length of 40 and 64 bits. -These are obsolete and new code should use -.Fn EVP_rc2_cbc , -.Xr EVP_CIPHER_CTX_set_key_length 3 , -and -.Xr EVP_CIPHER_CTX_ctrl 3 -to set the key length and effective key length. -.It Xo .Fn EVP_bf_cbc , .Fn EVP_bf_ecb , .Fn EVP_bf_cfb64 , @@ -638,6 +603,7 @@ Some algorithms are documented in separate manual pages: .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 +.It Xr EVP_rc2_cbc 3 Ta 64 Ta variable, default 128 .It Xr EVP_rc4 3 Ta stream Ta variable, default 128 .It Xr EVP_sm4_cbc 3 Ta 128 Ta 128 .El @@ -864,6 +830,7 @@ do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) .Xr EVP_CIPHER_nid 3 , .Xr EVP_des_cbc 3 , .Xr EVP_OpenInit 3 , +.Xr EVP_rc2_cbc 3 , .Xr EVP_rc4 3 , .Xr EVP_SealInit 3 , .Xr EVP_sm4_cbc 3 @@ -884,12 +851,6 @@ do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) and .Fn EVP_idea_ofb first appeared in SSLeay 0.5.1. -.Fn EVP_rc2_cbc , -.Fn EVP_rc2_ecb , -.Fn EVP_rc2_cfb , -and -.Fn EVP_rc2_ofb -first appeared in SSLeay 0.5.2. .Fn EVP_bf_cbc , .Fn EVP_bf_ecb , .Fn EVP_bf_cfb , @@ -906,12 +867,6 @@ first appeared in SSLeay 0.8.1. All these functions have been available since .Ox 2.4 . .Pp -.Fn EVP_rc2_40_cbc -and -.Fn EVP_rc2_64_cbc -first appeared in SSLeay 0.9.1 and have been available since -.Ox 2.6 . -.Pp .Fn EVP_EncryptInit_ex , .Fn EVP_EncryptFinal_ex , .Fn EVP_DecryptInit_ex , @@ -924,9 +879,8 @@ first appeared in OpenSSL 0.9.7 and have been available since .Pp .Fn EVP_bf_cfb64 , .Fn EVP_cast5_cfb64 , -.Fn EVP_idea_cfb64 , and -.Fn EVP_rc2_cfb64 +.Fn EVP_idea_cfb64 first appeared in OpenSSL 0.9.7e and have been available since .Ox 3.8 . .Pp diff --git a/src/lib/libcrypto/man/EVP_rc2_cbc.3 b/src/lib/libcrypto/man/EVP_rc2_cbc.3 new file mode 100644 index 0000000000..38c8184260 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_rc2_cbc.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: EVP_rc2_cbc.3,v 1.1 2024/12/08 17:41:23 schwarze Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: December 8 2024 $ +.Dt EVP_RC2_CBC 3 +.Os +.Sh NAME +.Nm EVP_rc2_cbc , +.Nm EVP_rc2_ecb , +.Nm EVP_rc2_cfb64 , +.Nm EVP_rc2_cfb , +.Nm EVP_rc2_ofb , +.Nm EVP_rc2_40_cbc , +.Nm EVP_rc2_64_cbc +.Nd Rivest Cipher 2 in the EVP framework +.Sh SYNOPSIS +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cfb64 void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_40_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_64_cbc void +.In openssl/rc2.h +.Fd #define RC2_BLOCK 8 +.Fd #define RC2_KEY_LENGTH 16 +.Sh DESCRIPTION +RC2 is a block cipher operating on blocks of +.Dv RC2_BLOCK No = 8 +bytes, equivalent to 64 bits, using a variable +.Fa key +length with an additional parameter called +.Dq effective key bits +or +.Dq effective key length . +.Pp +.Fn EVP_rc2_cbc , +.Fn EVP_rc2_ecb , +.Fn EVP_rc2_cfb64 , +and +.Fn EVP_rc2_ofb +provide the RC2 encryption algorithm in CBC, ECB, CFB and OFB mode, +respectively. +.Fn EVP_rc2_cfb +is an alias for +.Fn EVP_rc2_cfb64 , +implemented as a macro. +.Pp +By default, these functions set both the key length +and the effective key length to +.Dv RC2_KEY_LENGTH No = 16 +bytes, which is not a very useful value because it is quite short. +.Pp +Configuring normally requires a multi-step process: +.Bl -enum -width 2n +.It +Create a new, empty +.Vt EVP_CIPHER_CTX +object with +.Xr EVP_CIPHER_CTX_new 3 . +.It +Select the operation mode by calling +.Xr EVP_EncryptInit 3 +with the desired +.Fa type +argument, passing +.Dv NULL +pointers for the +.Fa key +and +.Fa iv +arguments. +.It +Select the +.Fa key +length by passing the desired number of bytes to +.Xr EVP_CIPHER_CTX_set_key_length 3 . +Doing so overrides the default key length of +.Dv RC2_KEY_LENGTH No = 16 . +Valid values for +.Fa keylen +are positive and less than or equal to 128. +.It +Select the effective key length by calling +.Xr EVP_CIPHER_CTX_ctrl 3 +with a +.Fa type +argument of +.Dv EVP_CTRL_SET_RC2_KEY_BITS , +passing the desired number of bits in +.Fa arg . +Doing so overrides the default effective key length of 128 bits. +Valid values for +.Fa arg +are positive and less than or equal to 1024. +The +.Fa ptr +argument is ignored; passing +.Dv NULL +is recommended. +.It +Call +.Xr EVP_EncryptInit 3 +a second time, this time passing +.Dv NULL +for the type argument. +The +.Fa key +argument points to an array containing the number of bytes that was passed to +.Xr EVP_CIPHER_CTX_set_key_length 3 , +and the +.Fa iv +argument points to an array of eight bytes. +.It +Finally, +.Xr EVP_EncryptUpdate 3 +and +.Xr EVP_EncryptFinal 3 +can be used in the normal way. +.El +.Pp +Once a +.Fa ctx +object is fully configured, calling +.Xr EVP_CIPHER_CTX_ctrl 3 +with a +.Fa type +argument of +.Dv EVP_CTRL_GET_RC2_KEY_BITS +interprets +.Fa ptr +as a pointer to +.Vt int +and stores the effective key length in bits at that location. +In this case, +.Fa arg +is ignored and passing 0 is recommended. +.Pp +In the CFB and OFB modes, the minimum required total length in bytes +of the output buffer is equal to the total number of input bytes to +be encoded. +In the CBC and ECB modes, the minimum required total length +of the output buffer has to be rounded up to the next multiple +of the block size of eight bytes. +.Pp +.Fn EVP_rc2_40_cbc +and +.Fn EVP_rc2_64_cbc +are obsolete functions that provide the RC2 algorithm in CBC mode +with a key length and an effective key length of 40 and 64 bits, +respectively. +.Sh RETURN VALUES +With the +.Vt EVP_CIPHER +objects documented in the present manual page, +.Fn EVP_CIPHER_CTX_ctrl +returns 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_CTX_set_key_length 3 , +.Xr EVP_EncryptInit 3 , +.Xr RC2_encrypt 3 +.Sh HISTORY +.Fn EVP_rc2_cbc , +.Fn EVP_rc2_ecb , +.Fn EVP_rc2_cfb , +and +.Fn EVP_rc2_ofb +first appeared in SSLeay 0.5.2 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_rc2_40_cbc +and +.Fn EVP_rc2_64_cbc +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Pp +.Fn EVP_rc2_cfb64 +first appeared in OpenSSL 0.9.7e and has been available since +.Ox 3.8 . diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 11213cb518..c69fe73af2 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.299 2024/12/06 14:27:49 schwarze Exp $ +# $OpenBSD: Makefile,v 1.300 2024/12/08 17:41:23 schwarze Exp $ .include @@ -199,6 +199,7 @@ MAN= \ EVP_camellia_128_cbc.3 \ EVP_chacha20.3 \ EVP_des_cbc.3 \ + EVP_rc2_cbc.3 \ EVP_rc4.3 \ EVP_sha1.3 \ EVP_sha3_224.3 \ @@ -264,6 +265,7 @@ MAN= \ RAND_bytes.3 \ RAND_load_file.3 \ RAND_set_rand_method.3 \ + RC2_encrypt.3 \ RC4.3 \ RIPEMD160.3 \ RSA_PSS_PARAMS_new.3 \ -- cgit v1.2.3-55-g6feb