1.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.3 2023/09/05 14:54:21 schwarze Exp $ 2.\" full merge up to: OpenSSL man3/EVP_EncryptInit.pod 3.\" 0874d7f2 Oct 11 13:13:47 2022 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2018, 2023 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: September 5 2023 $ 70.Dt EVP_CIPHER_NID 3 71.Os 72.Sh NAME 73.Nm EVP_CIPHER_nid , 74.Nm EVP_CIPHER_CTX_nid , 75.Nm EVP_CIPHER_name , 76.Nm EVP_CIPHER_type , 77.Nm EVP_CIPHER_CTX_type , 78.Nm EVP_CIPHER_block_size , 79.Nm EVP_CIPHER_CTX_block_size , 80.Nm EVP_CIPHER_flags , 81.Nm EVP_CIPHER_CTX_flags , 82.Nm EVP_CIPHER_mode , 83.Nm EVP_CIPHER_CTX_mode 84.Nd inspect EVP_CIPHER objects 85.Sh SYNOPSIS 86.In openssl/evp.h 87.Ft int 88.Fo EVP_CIPHER_nid 89.Fa "const EVP_CIPHER *cipher" 90.Fc 91.Ft int 92.Fo EVP_CIPHER_CTX_nid 93.Fa "const EVP_CIPHER_CTX *ctx" 94.Fc 95.Ft const char * 96.Fo EVP_CIPHER_name 97.Fa "const EVP_CIPHER *cipher" 98.Fc 99.Ft int 100.Fo EVP_CIPHER_type 101.Fa "const EVP_CIPHER *ctx" 102.Fc 103.Ft int 104.Fo EVP_CIPHER_CTX_type 105.Fa "const EVP_CIPHER_CTX *ctx" 106.Fc 107.Ft int 108.Fo EVP_CIPHER_block_size 109.Fa "const EVP_CIPHER *cipher" 110.Fc 111.Ft int 112.Fo EVP_CIPHER_CTX_block_size 113.Fa "const EVP_CIPHER_CTX *ctx" 114.Fc 115.Ft unsigned long 116.Fo EVP_CIPHER_flags 117.Fa "const EVP_CIPHER *cipher" 118.Fc 119.Ft unsigned long 120.Fo EVP_CIPHER_CTX_flags 121.Fa "const EVP_CIPHER_CTX *ctx" 122.Fc 123.Ft unsigned long 124.Fo EVP_CIPHER_mode 125.Fa "const EVP_CIPHER *cipher" 126.Fc 127.Ft unsigned long 128.Fo EVP_CIPHER_CTX_mode 129.Fa "const EVP_CIPHER_CTX *ctx" 130.Fc 131.Sh DESCRIPTION 132.Fn EVP_CIPHER_nid 133returns the numerical identifier (NID) of the 134.Fa cipher . 135The NID is an internal value which may or may not have a corresponding 136ASN.1 OBJECT IDENTIFIER; see 137.Xr OBJ_nid2obj 3 138for details. 139.Pp 140.Fn EVP_CIPHER_CTX_nid 141returns the NID of the cipher that 142.Fa ctx 143is configured to use. 144.Pp 145.Fn EVP_CIPHER_name 146converts the NID of the 147.Fa cipher 148to its short name with 149.Xr OBJ_nid2sn 3 . 150.Pp 151.Fn EVP_CIPHER_type 152returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the 153.Fa cipher , 154ignoring the cipher parameters. 155For example, 156.Xr EVP_aes_256_cfb1 3 , 157.Xr EVP_aes_256_cfb8 3 , 158and 159.Xr EVP_aes_256_cfb128 3 160all return the same NID, 161.Dv NID_aes_256_cfb128 . 162.Pp 163.Fn EVP_CIPHER_CTX_type 164returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the cipher that 165.Fa ctx 166is configured to use. 167.Pp 168.Fn EVP_CIPHER_block_size 169returns the block size of the 170.Fa cipher 171in bytes. 172.Fn EVP_CIPHER_CTX_block_size 173returns the block size of the cipher that 174.Fa ctx 175is configured to use. 176Block sizes are guaranteed to be less than or equal to the constant 177.Dv EVP_MAX_BLOCK_LENGTH . 178Currently, 179.Xr EVP_CipherInit_ex 3 180and the other functions documented in the same manual page 181only support block sizes of 1, 8, and 16 bytes. 182.Pp 183.Fn EVP_CIPHER_flags 184returns the cipher flags used by the 185.Fa cipher . 186The meaning of the flags is described in the 187.Xr EVP_CIPHER_meth_set_flags 3 188manual page. 189.Pp 190.Fn EVP_CIPHER_CTX_flags 191returns the cipher flags of the cipher that 192.Fa ctx 193is configured to use. 194Be careful to not confuse these with the unrelated cipher context flags 195that can be inspected with 196.Xr EVP_CIPHER_CTX_test_flags 3 . 197.Pp 198.Fn EVP_CIPHER_mode 199returns the 200.Fa cipher 201mode, which is the logical AND of the constant 202.Dv EVP_CIPH_MODE 203and the return value of 204.Fn EVP_CIPHER_flags . 205.Pp 206.Fn EVP_CIPHER_CTX_mode 207returns the cipher mode of the cipher that 208.Fa ctx 209is configured to use. 210.Pp 211.Fn EVP_CIPHER_name , 212.Fn EVP_CIPHER_CTX_type , 213.Fn EVP_CIPHER_mode , 214and 215.Fn EVP_CIPHER_CTX_mode 216are implemented as macros. 217.Sh RETURN VALUES 218.Fn EVP_CIPHER_nid 219and 220.Fn EVP_CIPHER_CTX_nid 221return an NID. 222.Pp 223.Fn EVP_CIPHER_name 224returns a pointer to a string that is owned by an internal library object or 225.Dv NULL 226if the NID is neither built into the library nor added to the global 227object table by one of the functions documented in the manual page 228.Xr OBJ_create 3 , 229of if the object does not contain a short name. 230.Pp 231.Fn EVP_CIPHER_type 232and 233.Fn EVP_CIPHER_CTX_type 234return the NID of the cipher's OBJECT IDENTIFIER or 235.Dv NID_undef 236if it is not associated with an OBJECT IDENTIFIER. 237.Pp 238.Fn EVP_CIPHER_block_size 239and 240.Fn EVP_CIPHER_CTX_block_size 241return the block size in bytes. 242.Pp 243.Fn EVP_CIPHER_flags 244and 245.Fn EVP_CIPHER_CTX_flags 246return one or more 247.Dv EVP_CIPH_* 248flag bits OR'ed together. 249.Pp 250.Fn EVP_CIPHER_mode 251and 252.Fn EVP_CIPHER_CTX_mode 253return one of the constants 254.Dv EVP_CIPH_ECB_MODE , 255.Dv EVP_CIPH_CBC_MODE , 256.Dv EVP_CIPH_CFB_MODE , 257.Dv EVP_CIPH_OFB_MODE , 258.Dv EVP_CIPH_CTR_MODE , 259.Dv EVP_CIPH_GCM_MODE , 260.Dv EVP_CIPH_CCM_MODE , 261.Dv EVP_CIPH_XTS_MODE , 262or 263.Dv EVP_CIPH_WRAP_MODE 264to indicate a block cipher or 265.Dv EVP_CIPH_STREAM_CIPHER 266to indicate a stream cipher. 267.Sh SEE ALSO 268.Xr evp 3 , 269.Xr EVP_CIPHER_CTX_ctrl 3 , 270.Xr EVP_EncryptInit 3 , 271.Xr OBJ_nid2obj 3 272.Sh HISTORY 273.Fn EVP_CIPHER_type , 274.Fn EVP_CIPHER_CTX_type , 275.Fn EVP_CIPHER_block_size , 276and 277.Fn EVP_CIPHER_CTX_block_size 278first appeared in SSLeay 0.6.5. 279.Fn EVP_CIPHER_nid 280and 281.Fn EVP_CIPHER_CTX_nid 282first appeared in SSLeay 0.8.0. 283All these functions have been available since 284.Ox 2.4 . 285.Pp 286.Fn EVP_CIPHER_flags , 287.Fn EVP_CIPHER_CTX_flags , 288.Fn EVP_CIPHER_mode , 289and 290.Fn EVP_CIPHER_CTX_mode 291first appeared in OpenSSL 0.9.6 and have been available since 292.Ox 2.9 . 293.Pp 294.Fn EVP_CIPHER_name 295first appeared in OpenSSL 0.9.7 and has been available since 296.Ox 3.2 . 297.Sh CAVEATS 298The behaviour of the functions taking an 299.Vt EVP_CIPHER_CTX 300argument is undefined if they are called on a 301.Fa ctx 302that has no cipher configured yet, for example one freshly returned from 303.Xr EVP_CIPHER_CTX_new 3 . 304In that case, the program may for example be terminated by a 305.Dv NULL 306pointer access. 307