From 6bf59eda898875d5b4bd5d8c2dff44b6697a1cf8 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 1 Sep 2023 17:28:21 +0000 Subject: [PATCH] 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 --- lib/libcrypto/man/EVP_CIPHER_nid.3 | 157 ++++++++++++++++++++--------- 1 file 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 +.\" Copyright (c) 2018, 2023 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 @@ -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. -- 2.20.1