Many improvements, almost amounting to a partial rewrite:

* more precision what the CIPHER_CTX functions do
* more precision what an NID is
* avoid talking about RC2, use AES-256 for an example instead
* clarify that block sizes are measured in bytes
* mention additional restrictions regarding valid block sizes
* add the missing description of the *_flags(3) functions
* mention the public mask constant EVP_CIPH_MODE
* add three missing modes that can occur as return values
* add the missing entries for *_flags(3) and *_mode(3) below RETURN VALUES
* tweak various wordings for precision and conciseness

1 files changed, 109 insertions, 48 deletions

diff --git a/lib/libcrypto/man/EVP_CIPHER_nid.3 b/lib/libcrypto/man/EVP_CIPHER_nid.3
index 3a3c42d0b4c..1c0683980bd 100644
--- a/lib/libcrypto/man/EVP_CIPHER_nid.3
+++ b/lib/libcrypto/man/EVP_CIPHER_nid.3
@@ -1,10 +1,11 @@
-.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.1 2023/08/31 17:27:41 schwarze Exp $
-.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800
+.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.2 2023/09/01 17:28:21 schwarze Exp $
+.\" full merge up to: OpenSSL man3/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 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2018, 2023 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
@@ -65,7 +66,7 @@
 .\" 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: September 1 2023 $
 .Dt EVP_CIPHER_NID 3
 .Os
 .Sh NAME
@@ -84,7 +85,7 @@
 .In openssl/evp.h
 .Ft int
 .Fo EVP_CIPHER_nid
-.Fa "const EVP_CIPHER *e"
+.Fa "const EVP_CIPHER *cipher"
 .Fc
 .Ft int
 .Fo EVP_CIPHER_CTX_nid
@@ -100,7 +101,7 @@
 .Fc
 .Ft int
 .Fo EVP_CIPHER_block_size
-.Fa "const EVP_CIPHER *e"
+.Fa "const EVP_CIPHER *cipher"
 .Fc
 .Ft int
 .Fo EVP_CIPHER_CTX_block_size
@@ -108,7 +109,7 @@
 .Fc
 .Ft unsigned long
 .Fo EVP_CIPHER_flags
-.Fa "const EVP_CIPHER *e"
+.Fa "const EVP_CIPHER *cipher"
 .Fc
 .Ft unsigned long
 .Fo EVP_CIPHER_CTX_flags
@@ -116,7 +117,7 @@
 .Fc
 .Ft unsigned long
 .Fo EVP_CIPHER_mode
-.Fa "const EVP_CIPHER *e"
+.Fa "const EVP_CIPHER *cipher"
 .Fc
 .Ft unsigned long
 .Fo EVP_CIPHER_CTX_mode
@@ -124,74 +125,124 @@
 .Fc
 .Sh DESCRIPTION
 .Fn EVP_CIPHER_nid
-and
+returns the numerical identifier (NID) of the
+.Fa cipher .
+The NID is an internal value which may or may not have a corresponding
+ASN.1 OBJECT IDENTIFIER; see
+.Xr OBJ_nid2obj 3
+for details.
+.Pp
 .Fn EVP_CIPHER_CTX_nid
-return the NID of a cipher when passed an
-.Vt EVP_CIPHER
-or
-.Vt EVP_CIPHER_CTX
-structure.
-The actual NID value is an internal value which may not have a
-corresponding OBJECT IDENTIFIER.
+returns the NID of the cipher that
+.Fa ctx
+is configured to use.
 .Pp
 .Fn EVP_CIPHER_type
+returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the
+.Fa cipher ,
+ignoring the cipher parameters.
+For example,
+.Xr EVP_aes_256_cfb1 3 ,
+.Xr EVP_aes_256_cfb8 3 ,
 and
+.Xr EVP_aes_256_cfb128 3
+all return the same NID,
+.Dv NID_aes_256_cfb128 .
+.Pp
 .Fn EVP_CIPHER_CTX_type
-return the type of the passed cipher or context.
-This "type" is the actual NID of the cipher OBJECT IDENTIFIER as such it
-ignores the cipher parameters and 40-bit RC2 and 128-bit RC2 have the
-same NID.
-If the cipher does not have an object identifier or does not
-have ASN.1 support, this function will return
-.Dv NID_undef .
+returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the cipher that
+.Fa ctx
+is configured to use.
 .Pp
 .Fn EVP_CIPHER_block_size
-and
+returns the block size of the
+.Fa cipher
+in bytes.
 .Fn EVP_CIPHER_CTX_block_size
-return the block size of a cipher when passed an
-.Vt EVP_CIPHER
-or
-.Vt EVP_CIPHER_CTX
-structure.
-The constant
-.Dv EVP_MAX_BLOCK_LENGTH
-is also the maximum block length for all ciphers.
+returns the block size of the cipher that
+.Fa ctx
+is configured to use.
+Block sizes are guaranteed to be less than or equal to the constant
+.Dv EVP_MAX_BLOCK_LENGTH .
+Currently,
+.Xr EVP_CipherInit_ex 3
+and the other functions documented in the same manual page
+only support block sizes of 1, 8, and 16 bytes.
+.Pp
+.Fn EVP_CIPHER_flags
+returns the cipher flags used by the
+.Fa cipher .
+The meaning of the flags is described in the
+.Xr EVP_CIPHER_meth_set_flags 3
+manual page.
+.Pp
+.Fn EVP_CIPHER_CTX_flags
+returns the cipher flags of the cipher that
+.Fa ctx
+is configured to use.
+Be careful to not confuse these with the unrelated cipher context flags
+that can be inspected with
+.Xr EVP_CIPHER_CTX_test_flags 3 .
 .Pp
 .Fn EVP_CIPHER_mode
-and
+returns the
+.Fa cipher
+mode, which is the logical AND of the constant
+.Dv EVP_CIPH_MODE
+and the return value of
+.Fn EVP_CIPHER_flags .
+.Pp
 .Fn EVP_CIPHER_CTX_mode
-return the block cipher mode:
-.Dv EVP_CIPH_ECB_MODE ,
-.Dv EVP_CIPH_CBC_MODE ,
-.Dv EVP_CIPH_CFB_MODE ,
-.Dv EVP_CIPH_OFB_MODE ,
-.Dv EVP_CIPH_CTR_MODE ,
-or
-.Dv EVP_CIPH_XTS_MODE .
-If the cipher is a stream cipher then
-.Dv EVP_CIPH_STREAM_CIPHER
-is returned.
+returns the cipher mode of the cipher that
+.Fa ctx
+is configured to use.
 .Sh RETURN VALUES
 .Fn EVP_CIPHER_nid
 and
 .Fn EVP_CIPHER_CTX_nid
-return a NID.
+return an NID.
 .Pp
 .Fn EVP_CIPHER_type
 and
 .Fn EVP_CIPHER_CTX_type
 return the NID of the cipher's OBJECT IDENTIFIER or
 .Dv NID_undef
-if it has no defined OBJECT IDENTIFIER.
+if it is not associated with an OBJECT IDENTIFIER.
 .Pp
 .Fn EVP_CIPHER_block_size
 and
 .Fn EVP_CIPHER_CTX_block_size
-return the block size.
+return the block size in bytes.
+.Pp
+.Fn EVP_CIPHER_flags
+and
+.Fn EVP_CIPHER_CTX_flags
+return one or more
+.Dv EVP_CIPH_*
+flag bits OR'ed together.
+.Pp
+.Fn EVP_CIPHER_mode
+and
+.Fn EVP_CIPHER_CTX_mode
+return one of the constants
+.Dv EVP_CIPH_ECB_MODE ,
+.Dv EVP_CIPH_CBC_MODE ,
+.Dv EVP_CIPH_CFB_MODE ,
+.Dv EVP_CIPH_OFB_MODE ,
+.Dv EVP_CIPH_CTR_MODE ,
+.Dv EVP_CIPH_GCM_MODE ,
+.Dv EVP_CIPH_CCM_MODE ,
+.Dv EVP_CIPH_XTS_MODE ,
+or
+.Dv EVP_CIPH_WRAP_MODE
+to indicate a block cipher or
+.Dv EVP_CIPH_STREAM_CIPHER
+to indicate a stream cipher.
 .Sh SEE ALSO
 .Xr evp 3 ,
 .Xr EVP_CIPHER_CTX_ctrl 3 ,
-.Xr EVP_EncryptInit 3
+.Xr EVP_EncryptInit 3 ,
+.Xr OBJ_nid2obj 3
 .Sh HISTORY
 .Fn EVP_CIPHER_type ,
 .Fn EVP_CIPHER_CTX_type ,
@@ -213,3 +264,13 @@ and
 .Fn EVP_CIPHER_CTX_mode
 first appeared in OpenSSL 0.9.6 and have been available since
 .Ox 2.9 .
+.Sh CAVEATS
+The behaviour of the functions taking an
+.Vt EVP_CIPHER_CTX
+argument is undefined if they are called on a
+.Fa ctx
+that has no cipher configured yet, for example one freshly returned from
+.Xr EVP_CIPHER_CTX_new 3 .
+In that case, the program may for example be terminated by a
+.Dv NULL
+pointer access.