Mention the key lengths of some encryption algorithms.

This is relevant because EVP_EncryptInit(3) takes a "key" argument,
and users need to consider the size of that argument.

While here, also mention whether ciphers are stream ciphers
or block ciphers and what the block size is.

4 files changed, 47 insertions, 21 deletions

diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3
index a0adfbab09c..32ed3349b9b 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.52 2024/07/21 08:36:43 tb Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.53 2024/11/09 22:03:49 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: July 21 2024 $
+.Dd $Mdocdate: November 9 2024 $
 .Dt EVP_ENCRYPTINIT 3
 .Os
 .Sh NAME
@@ -553,7 +553,6 @@ returns an
 .Vt EVP_CIPHER
 structure.
 .Sh CIPHER LISTING
-All algorithms have a fixed key length unless otherwise stated.
 .Bl -tag -width Ds
 .It Fn EVP_enc_null
 Null cipher: does nothing.
@@ -564,6 +563,8 @@ Null cipher: does nothing.
 .Fn EVP_idea_ofb
 .Xc
 IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+IDEA is a block cipher operating on 64 bit blocks using a 128 bit
+.Fa key .
 .Fn EVP_idea_cfb
 is an alias for
 .Fn EVP_idea_cfb64 ,
@@ -575,7 +576,9 @@ implemented as a macro.
 .Fn EVP_rc2_ofb
 .Xc
 RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
-This is a variable key length cipher with an additional parameter called
+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
@@ -602,7 +605,10 @@ to set the key length and effective key length.
 .Xc
 Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes
 respectively.
-This is a variable key length cipher.
+Blowfish is a block cipher operating on 64 bit blocks using a variable
+.Fa key
+length.
+The default key length is 128 bits.
 .Fn EVP_bf_cfb
 is an alias for
 .Fn EVP_bf_cfb64 ,
@@ -613,21 +619,28 @@ implemented as a macro.
 .Fn EVP_cast5_cfb64 ,
 .Fn EVP_cast5_ofb
 .Xc
-CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
-This is a variable key length cipher.
+CAST-128 encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+CAST-128 is a block cipher operating on 64 bit blocks using a variable
+.Fa key
+length.
+The default and maximum key length is 128 bits.
 .Fn EVP_cast5_cfb
 is an alias for
 .Fn EVP_cast5_cfb64 ,
 implemented as a macro.
 .El
 .Pp
-See also
-.Xr EVP_aes_128_cbc 3 ,
-.Xr EVP_camellia_128_cbc 3 ,
-.Xr EVP_des_cbc 3 ,
-.Xr EVP_rc4 3 ,
-and
-.Xr EVP_sm4_cbc 3 .
+Some algorithms are documented in separate manual pages:
+.Pp
+.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_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_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
diff --git a/lib/libcrypto/man/EVP_aes_128_cbc.3 b/lib/libcrypto/man/EVP_aes_128_cbc.3
index 4d153e5cbd5..6249bf73489 100644
--- a/lib/libcrypto/man/EVP_aes_128_cbc.3
+++ b/lib/libcrypto/man/EVP_aes_128_cbc.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.5 2023/11/16 20:27:43 schwarze Exp $
+.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.6 2024/11/09 22:03:49 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 16 2023 $
+.Dd $Mdocdate: November 9 2024 $
 .Dt EVP_AES_128_CBC 3
 .Os
 .Sh NAME
@@ -170,6 +170,8 @@
 These functions provide the AES encryption algorithm in the
 .Xr evp 3
 framework.
+AES is a family of block ciphers operating on 128 bit blocks
+using key lengths of 128, 192, and 256 bits.
 .Pp
 .Fn EVP_aes_128_cbc ,
 .Fn EVP_aes_192_cbc ,
diff --git a/lib/libcrypto/man/EVP_camellia_128_cbc.3 b/lib/libcrypto/man/EVP_camellia_128_cbc.3
index 190247a68ba..6f15a85f7ff 100644
--- a/lib/libcrypto/man/EVP_camellia_128_cbc.3
+++ b/lib/libcrypto/man/EVP_camellia_128_cbc.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_camellia_128_cbc.3,v 1.2 2020/06/24 18:15:00 jmc Exp $
+.\" $OpenBSD: EVP_camellia_128_cbc.3,v 1.3 2024/11/09 22:03:49 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: June 24 2020 $
+.Dd $Mdocdate: November 9 2024 $
 .Dt EVP_CAMELLIA_128_CBC 3
 .Os
 .Sh NAME
@@ -122,7 +122,9 @@
 These functions provide the Camellia encryption algorithm in the
 .Xr evp 3
 framework.
-They use 128, 192, and 256-bit keys in the following modes, respectively:
+Camellia is a block cipher operating on 128 bit blocks.
+These functions use 128, 192, and 256-bit keys
+in the following modes, respectively:
 CBC, CFB with 1-bit shift, CFB with 8-bit shift, CFB with 128-bit shift,
 ECB, and OFB.
 .Pp
diff --git a/lib/libcrypto/man/EVP_des_cbc.3 b/lib/libcrypto/man/EVP_des_cbc.3
index 759e03fac0b..7c8a08c7dbe 100644
--- a/lib/libcrypto/man/EVP_des_cbc.3
+++ b/lib/libcrypto/man/EVP_des_cbc.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_des_cbc.3,v 1.1 2019/03/21 12:54:37 schwarze Exp $
+.\" $OpenBSD: EVP_des_cbc.3,v 1.2 2024/11/09 22:03:49 schwarze Exp $
 .\" full merge up to:
 .\"   OpenSSL EVP_desx_cbc.pod 8fa4d95e Oct 21 11:59:09 2017 +0900
 .\" selective merge up to:
@@ -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: March 21 2019 $
+.Dd $Mdocdate: November 9 2024 $
 .Dt EVP_DES_CBC 3
 .Os
 .Sh NAME
@@ -128,6 +128,15 @@
 These functions provide the DES encryption algorithm in the
 .Xr evp 3
 framework.
+DES is a block cipher operating on 64 bit blocks.
+The key length to be used for
+.Xr EVP_EncryptInit 3
+is 64 bits.
+However, only 56 of these bits are used in the encryption algorithm.
+The least significant bit in each of the eight bytes is only used
+for checking parity.
+Using this algorithm is discouraged because the short key length
+makes it vulnerable to brute force attacks.
 .Pp
 .Fn EVP_des_cbc ,
 .Fn EVP_des_cfb1 ,