1.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.4 2024/12/06 15:01:01 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL EVP_EncryptInit.pod 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, 2019, 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.\" and Richard Levitte <levitte@openssl.org>. 24.\" Copyright (c) 2000-2001, 2015 The OpenSSL Project. 25.\" All rights reserved. 26.\" 27.\" Redistribution and use in source and binary forms, with or without 28.\" modification, are permitted provided that the following conditions 29.\" are met: 30.\" 31.\" 1. Redistributions of source code must retain the above copyright 32.\" notice, this list of conditions and the following disclaimer. 33.\" 34.\" 2. Redistributions in binary form must reproduce the above copyright 35.\" notice, this list of conditions and the following disclaimer in 36.\" the documentation and/or other materials provided with the 37.\" distribution. 38.\" 39.\" 3. All advertising materials mentioning features or use of this 40.\" software must display the following acknowledgment: 41.\" "This product includes software developed by the OpenSSL Project 42.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 43.\" 44.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 45.\" endorse or promote products derived from this software without 46.\" prior written permission. For written permission, please contact 47.\" openssl-core@openssl.org. 48.\" 49.\" 5. Products derived from this software may not be called "OpenSSL" 50.\" nor may "OpenSSL" appear in their names without prior written 51.\" permission of the OpenSSL Project. 52.\" 53.\" 6. Redistributions of any form whatsoever must retain the following 54.\" acknowledgment: 55.\" "This product includes software developed by the OpenSSL Project 56.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 57.\" 58.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 59.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 60.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 61.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 62.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 63.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 64.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 65.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 66.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 67.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 68.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 69.\" OF THE POSSIBILITY OF SUCH DAMAGE. 70.\" 71.Dd $Mdocdate: December 6 2024 $ 72.Dt EVP_CIPHER_CTX_INIT 3 73.Os 74.Sh NAME 75.Nm EVP_CIPHER_CTX_init , 76.Nm EVP_CIPHER_CTX_cleanup , 77.Nm EVP_Cipher 78.Nd obsolete EVP cipher functions 79.Sh SYNOPSIS 80.In openssl/evp.h 81.Ft int 82.Fo EVP_CIPHER_CTX_init 83.Fa "EVP_CIPHER_CTX *ctx" 84.Fc 85.Ft int 86.Fo EVP_CIPHER_CTX_cleanup 87.Fa "EVP_CIPHER_CTX *ctx" 88.Fc 89.Ft int 90.Fo EVP_Cipher 91.Fa "EVP_CIPHER_CTX *ctx" 92.Fa "unsigned char *out" 93.Fa "const unsigned char *in" 94.Fa "unsigned int in_len" 95.Fc 96.Sh DESCRIPTION 97.Fn EVP_CIPHER_CTX_init 98is a deprecated function that could be used to clear a cipher context 99on the stack before 100.Vt EVP_CIPHER_CTX 101was made opaque. 102Calling it on a cipher context just returned from 103.Xr EVP_CIPHER_CTX_new 3 104has no effect. 105Calling it on a cipher context that was already used may leak memory 106with older versions of the library. 107Instead, use 108.Xr EVP_CIPHER_CTX_reset 3 109or 110.Xr EVP_CIPHER_CTX_free 3 . 111.Pp 112.Fn EVP_CIPHER_CTX_cleanup 113is a deprecated alias for 114.Xr EVP_CIPHER_CTX_reset 3 . 115It clears all information from 116.Fa ctx 117and frees all allocated memory associated with it, except the 118.Fa ctx 119object itself. 120.Pp 121.Fn EVP_Cipher 122exposes implementation details of the functions 123.Xr EVP_CipherUpdate 3 124and 125.Xr EVP_CipherFinal 3 126that should never have become part of the public API. 127.Pp 128If the flag 129.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER 130is set for the cipher used by 131.Fa ctx , 132behaviour depends on 133.Fa in . 134If that argument is 135.Dv NULL 136and 137.Fa in_len 138is 0, behaviour is similar to 139.Xr EVP_CipherFinal 3 ; 140if 141.Fa in_len 142is not 0, behaviour is undefined. 143If 144.Fa in 145is not 146.Dv NULL , 147behaviour is similar to 148.Xr EVP_CipherUpdate 3 . 149In both cases, the exceptions to the similarity are that arguments 150and return values differ. 151.Pp 152If the flag 153.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER 154is not set for the cipher used by 155.Fa ctx , 156it encrypts or decrypts aligned blocks of data 157whose lengths match the cipher block size. 158It requires that the previous encryption or decryption operation 159using the same 160.Fa ctx , 161if there was any, ended exactly on a block boundary and that 162.Fa in_len 163is an integer multiple of the cipher block size. 164If either of these conditions is violated, 165.Fn EVP_Cipher 166silently produces incorrect results. 167For that reason, using the function 168.Xr EVP_CipherUpdate 3 169instead is strongly recommended. 170The latter can safely handle partial blocks, and even if 171.Fa in_len 172actually is a multiple of the cipher block size for all calls, 173the overhead incurred by using 174.Xr EVP_CipherUpdate 3 175is minimal. 176.Sh RETURN VALUES 177.Fn EVP_CIPHER_CTX_init 178always returns 1. 179.Pp 180.Fn EVP_CIPHER_CTX_cleanup 181returns 1 for success or 0 for failure. 182.Pp 183With 184.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER , 185.Fn EVP_Cipher 186returns the number of bytes written to 187.Fa out 188for success or \-1 for failure. 189Without 190.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER , 191it returns 1 for success or 0 for failure. 192.Sh SEE ALSO 193.Xr evp 3 , 194.Xr EVP_EncryptInit 3 195.Sh HISTORY 196.Fn EVP_Cipher 197first appeared in SSLeay 0.6.5. 198.Fn EVP_CIPHER_CTX_cleanup 199first appeared in SSLeay 0.8.0. 200.Fn EVP_CIPHER_CTX_init 201first appeared in SSLeay 0.9.0. 202All these functions have been available since 203.Ox 2.4 . 204.Sh CAVEATS 205Checking the return value of 206.Fn EVP_Cipher 207requires unusual caution: zero signals success if 208.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER 209is set or failure otherwise. 210