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.

4 files changed, 214 insertions, 55 deletions

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 <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.
+.\"
+.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 <bsd.own.mk>
 
@@ -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 \