-.\" $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
.\" 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
.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
.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
.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
.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
.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 ,
.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.
projects / openbsd / commitdiff