1.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.6 2024/03/04 09:49:07 tb Exp $ 2.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Richard Levitte <levitte@openssl.org> 22.\" Copyright (c) 2015 The OpenSSL Project. 23.\" 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: March 4 2024 $ 70.Dt EVP_CIPHER_METH_NEW 3 71.Os 72.Sh NAME 73.Nm EVP_CIPHER_meth_new , 74.Nm EVP_CIPHER_meth_dup , 75.Nm EVP_CIPHER_meth_free , 76.Nm EVP_CIPHER_meth_set_iv_length , 77.Nm EVP_CIPHER_meth_set_flags , 78.Nm EVP_CIPHER_meth_set_impl_ctx_size , 79.Nm EVP_CIPHER_meth_set_init , 80.Nm EVP_CIPHER_meth_set_do_cipher , 81.Nm EVP_CIPHER_meth_set_cleanup , 82.Nm EVP_CIPHER_meth_set_set_asn1_params , 83.Nm EVP_CIPHER_meth_set_get_asn1_params , 84.Nm EVP_CIPHER_meth_set_ctrl 85.Nd Routines to build up EVP_CIPHER methods 86.Sh SYNOPSIS 87.In openssl/evp.h 88.Ft EVP_CIPHER * 89.Fo EVP_CIPHER_meth_new 90.Fa "int cipher_type" 91.Fa "int block_size" 92.Fa "int key_len" 93.Fc 94.Ft EVP_CIPHER * 95.Fo EVP_CIPHER_meth_dup 96.Fa "const EVP_CIPHER *cipher" 97.Fc 98.Ft void 99.Fo EVP_CIPHER_meth_free 100.Fa "EVP_CIPHER *cipher" 101.Fc 102.Ft int 103.Fo EVP_CIPHER_meth_set_iv_length 104.Fa "EVP_CIPHER *cipher" 105.Fa "int iv_len" 106.Fc 107.Ft int 108.Fo EVP_CIPHER_meth_set_flags 109.Fa "EVP_CIPHER *cipher" 110.Fa "unsigned long flags" 111.Fc 112.Ft int 113.Fo EVP_CIPHER_meth_set_impl_ctx_size 114.Fa "EVP_CIPHER *cipher" 115.Fa "int ctx_size" 116.Fc 117.Ft int 118.Fo EVP_CIPHER_meth_set_init 119.Fa "EVP_CIPHER *cipher" 120.Fa "int (*init)(EVP_CIPHER_CTX *ctx, const unsigned char *key,\ 121 const unsigned char *iv, int enc)" 122.Fc 123.Ft int 124.Fo EVP_CIPHER_meth_set_do_cipher 125.Fa "EVP_CIPHER *cipher" 126.Fa "int (*do_cipher)(EVP_CIPHER_CTX *ctx, unsigned char *out,\ 127 const unsigned char *in, size_t inl)" 128.Fc 129.Ft int 130.Fo EVP_CIPHER_meth_set_cleanup 131.Fa "EVP_CIPHER *cipher" 132.Fa "int (*cleanup)(EVP_CIPHER_CTX *)" 133.Fc 134.Ft int 135.Fo EVP_CIPHER_meth_set_set_asn1_params 136.Fa "EVP_CIPHER *cipher" 137.Fa "int (*set_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)" 138.Fc 139.Ft int 140.Fo EVP_CIPHER_meth_set_get_asn1_params 141.Fa "EVP_CIPHER *cipher" 142.Fa "int (*get_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)" 143.Fc 144.Ft int 145.Fo EVP_CIPHER_meth_set_ctrl 146.Fa "EVP_CIPHER *cipher" 147.Fa "int (*ctrl)(EVP_CIPHER_CTX *, int type, int arg, void *ptr)" 148.Fc 149.Sh DESCRIPTION 150The 151.Vt EVP_CIPHER 152type is a structure holding function pointers for 153a symmetric cipher implementation. 154.Pp 155.Fn EVP_CIPHER_meth_new 156allocates a new 157.Vt EVP_CIPHER 158structure. 159The cipher's NID (see 160.Xr EVP_CIPHER_nid 3 ) 161is set to 162.Fa cipher_type , 163the block size and key length are set to 164.Fa block_size 165and 166.Fa key_len , 167respectively. 168.Pp 169.Fn EVP_CIPHER_meth_dup 170creates a copy of 171.Fa cipher . 172.Pp 173.Fn EVP_CIPHER_meth_free 174frees an 175.Vt EVP_CIPHER 176structure. 177.Pp 178.Fn EVP_CIPHER_meth_set_iv_length 179sets the length of the initialization vector. 180This is only needed when the implemented cipher mode requires it. 181.Pp 182.Fn EVP_CIPHER_meth_set_flags 183overwrites the flags to describe optional behaviours in 184.Fa cipher 185with 186.Fa flags . 187At most one of the following cipher modes can be set: 188.Dv EVP_CIPH_STREAM_CIPHER , 189.Dv EVP_CIPH_ECB_MODE , 190.Dv EVP_CIPH_CBC_MODE , 191.Dv EVP_CIPH_CFB_MODE , 192.Dv EVP_CIPH_OFB_MODE , 193.Dv EVP_CIPH_CTR_MODE , 194.Dv EVP_CIPH_GCM_MODE , 195.Dv EVP_CIPH_CCM_MODE , 196.Dv EVP_CIPH_XTS_MODE , 197and 198.Dv EVP_CIPH_WRAP_MODE . 199.Pp 200Zero or more of the following flags can be OR'ed into the 201.Fa flags 202argument: 203.Bl -tag -width Ds 204.It Dv EVP_CIPH_VARIABLE_LENGTH 205This cipher has a variable key length, and the function 206.Xr EVP_CIPHER_CTX_set_key_length 3 207can be used with it. 208.It Dv EVP_CIPH_CUSTOM_IV 209Instruct 210.Xr EVP_CipherInit_ex 3 211and similar initialization functions to leave storing and initialising 212the IV entirely to the implementation. 213If this flag is set, 214the implementation is typically expected to do that in its 215.Fa init 216function. 217.It Dv EVP_CIPH_ALWAYS_CALL_INIT 218Instruct 219.Xr EVP_CipherInit_ex 3 220and similar initialization functions to call the implementation's 221.Fa init 222function even if the 223.Fa key 224argument is 225.Dv NULL . 226.It Dv EVP_CIPH_CTRL_INIT 227Instruct 228.Xr EVP_CipherInit_ex 3 229and similar initialization functions to call the implementation's 230.Fa ctrl 231function with a command 232.Fa type 233of 234.Dv EVP_CTRL_INIT 235early during the setup. 236.It Dv EVP_CIPH_NO_PADDING 237Instruct 238.Xr EVP_CipherFinal_ex 3 239and similar finalization functions to not use standard block padding 240but instead report an error if the total amount of data 241to be encrypted or decrypted is not a multiple of the block size. 242.It Dv EVP_CIPH_RAND_KEY 243Instruct 244.Xr EVP_CIPHER_CTX_rand_key 3 245to not generate a random key using 246.Xr arc4random_buf 3 247but instead leave that to the implementation by calling the 248.Fa ctrl 249function with a command 250.Fa type 251of 252.Dv EVP_CTRL_RAND_KEY 253and the pointer to the key memory storage in 254.Fa ptr . 255.It Dv EVP_CIPH_CUSTOM_COPY 256Instruct 257.Xr EVP_CIPHER_CTX_copy 3 258to call the implementation's 259.Fa ctrl 260function with a command 261.Fa type 262of 263.Dv EVP_CTRL_COPY 264and the destination 265.Fa "EVP_CIPHER_CTX *out" 266in the 267.Fa ptr 268argument immediately before returning successfully. 269The intended use is for further things to deal with after the 270implementation specific data block has been copied. 271The implementation-specific data block is reached with 272.Xr EVP_CIPHER_CTX_get_cipher_data 3 . 273.It Dv EVP_CIPH_FLAG_DEFAULT_ASN1 274Instruct 275.Xr EVP_CIPHER_param_to_asn1 3 276to use 277.Xr ASN1_TYPE_set_octetstring 3 278if no 279.Fa set_asn1_parameters 280function is installed, and instruct 281.Xr EVP_CIPHER_asn1_to_param 3 282to use 283.Xr ASN1_TYPE_get_octetstring 3 284if no 285.Fa get_asn1_parameters 286function is installed. 287.It Dv EVP_CIPH_FLAG_LENGTH_BITS 288Signals that the length of the input buffer for encryption / decryption 289is to be understood as the number of bits instead of bytes for this 290implementation. 291This is only useful for CFB1 ciphers. 292.It Dv EVP_CIPH_FLAG_CUSTOM_CIPHER 293Instruct 294.Xr EVP_CipherUpdate 3 , 295.Xr EVP_CipherFinal_ex 3 , 296and similar encryption, decryption, and finalization functions 297that the implementation's 298.Fa do_cipher 299function takes care of everything, 300including padding, buffering and finalization. 301.It Dv EVP_CIPH_FLAG_AEAD_CIPHER 302This indicates that this is an AEAD cipher implementation. 303.El 304.Pp 305.Fn EVP_CIPHER_meth_set_impl_ctx_size 306sets the size of the EVP_CIPHER's implementation context so that it can 307be automatically allocated. 308.Pp 309.Fn EVP_CIPHER_meth_set_init 310sets the 311.Fa init 312function for 313.Fa cipher . 314The cipher init function is called by 315.Xr EVP_CipherInit 3 , 316.Xr EVP_CipherInit_ex 3 , 317.Xr EVP_EncryptInit 3 , 318.Xr EVP_EncryptInit_ex 3 , 319.Xr EVP_DecryptInit 3 , 320and 321.Xr EVP_DecryptInit_ex 3 . 322.Pp 323.Fn EVP_CIPHER_meth_set_do_cipher 324sets the cipher function for 325.Fa cipher . 326The cipher function is called by 327.Xr EVP_CipherUpdate 3 , 328.Xr EVP_EncryptUpdate 3 , 329.Xr EVP_DecryptUpdate 3 , 330.Xr EVP_CipherFinal 3 , 331.Xr EVP_EncryptFinal 3 , 332.Xr EVP_EncryptFinal_ex 3 , 333.Xr EVP_DecryptFinal 3 334and 335.Xr EVP_DecryptFinal_ex 3 . 336.Pp 337.Fn EVP_CIPHER_meth_set_cleanup 338sets the function for 339.Fa cipher 340to do extra cleanup before the method's private data structure is 341cleaned out and freed. 342Note that the cleanup function is passed a 343.Sy EVP_CIPHER_CTX * , 344the private data structure is then available with 345.Xr EVP_CIPHER_CTX_get_cipher_data 3 . 346This cleanup function is called by 347.Xr EVP_CIPHER_CTX_reset 3 348and 349.Xr EVP_CIPHER_CTX_free 3 . 350.Pp 351.Fn EVP_CIPHER_meth_set_set_asn1_params 352sets the function for 353.Fa cipher 354to set the AlgorithmIdentifier "parameter" based on the passed cipher. 355This function is called by 356.Xr EVP_CIPHER_param_to_asn1 3 . 357.Fn EVP_CIPHER_meth_set_get_asn1_params 358sets the function for 359.Fa cipher 360that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier 361"parameter". 362Both these functions are needed when there is a need for custom data 363(more or other than the cipher IV). They are called by 364.Xr EVP_CIPHER_param_to_asn1 3 365and 366.Xr EVP_CIPHER_asn1_to_param 3 367respectively if defined. 368.Pp 369.Fn EVP_CIPHER_meth_set_ctrl 370sets the control function for 371.Fa cipher . 372.Sh RETURN VALUES 373.Fn EVP_CIPHER_meth_new 374and 375.Fn EVP_CIPHER_meth_dup 376return a pointer to a newly created 377.Vt EVP_CIPHER , 378or NULL on failure. 379.Pp 380All 381.Fn EVP_CIPHER_meth_set_* 382functions return 1. 383.Sh SEE ALSO 384.Xr evp 3 , 385.Xr EVP_EncryptInit 3 386.Sh HISTORY 387These functions first appeared in OpenSSL 1.1.0 and have been available since 388.Ox 7.3 . 389