1.\" $OpenBSD: EVP_CIPHER_CTX_set_flags.3,v 1.2 2023/09/06 16:26:49 schwarze Exp $ 2.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019 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 Dr. Stephen Henson <steve@openssl.org> 22.\" and Patrick Steuer <patrick.steuer@de.ibm.com>. 23.\" Copyright (c) 2000, 2017 The OpenSSL Project. 24.\" All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: September 6 2023 $ 71.Dt EVP_CIPHER_CTX_SET_FLAGS 3 72.Os 73.Sh NAME 74.Nm EVP_CIPHER_CTX_set_flags , 75.Nm EVP_CIPHER_CTX_clear_flags , 76.Nm EVP_CIPHER_CTX_test_flags , 77.Nm EVP_CIPHER_CTX_rand_key , 78.Nm EVP_CIPHER_param_to_asn1 , 79.Nm EVP_CIPHER_asn1_to_param , 80.\" .Nm EVP_CIPHER_set_asn1_iv and 81.\" .Nm EVP_CIPHER_get_asn1_iv are intentionally undocumented 82.\" because they are unused according to codesearch.debian.net 83.\" and should probably not be public: they seem hardly useful 84.\" even for implementing custom EVP_CIPHER algorithms. 85.Nm EVP_CIPHER_CTX_get_app_data , 86.Nm EVP_CIPHER_CTX_set_app_data 87.Nd unusual EVP cipher context configuration 88.Sh SYNOPSIS 89.In openssl/evp.h 90.Ft void 91.Fo EVP_CIPHER_CTX_set_flags 92.Fa "EVP_CIPHER_CTX *ctx" 93.Fa "int flags" 94.Fc 95.Ft void 96.Fo EVP_CIPHER_CTX_clear_flags 97.Fa "EVP_CIPHER_CTX *ctx" 98.Fa "int flags" 99.Fc 100.Ft int 101.Fo EVP_CIPHER_CTX_test_flags 102.Fa "EVP_CIPHER_CTX *ctx" 103.Fa "int flags" 104.Fc 105.Ft int 106.Fo EVP_CIPHER_CTX_rand_key 107.Fa "EVP_CIPHER_CTX *ctx" 108.Fa "unsigned char *key" 109.Fc 110.Ft int 111.Fo EVP_CIPHER_param_to_asn1 112.Fa "EVP_CIPHER_CTX *c" 113.Fa "ASN1_TYPE *type" 114.Fc 115.Ft int 116.Fo EVP_CIPHER_asn1_to_param 117.Fa "EVP_CIPHER_CTX *c" 118.Fa "ASN1_TYPE *type" 119.Fc 120.Ft void * 121.Fo EVP_CIPHER_CTX_get_app_data 122.Fa "const EVP_CIPHER_CTX *ctx" 123.Fc 124.Ft void 125.Fo EVP_CIPHER_CTX_set_app_data 126.Fa "const EVP_CIPHER_CTX *ctx" 127.Fa "void *data" 128.Fc 129.Sh DESCRIPTION 130.Fn EVP_CIPHER_CTX_set_flags 131enables the given 132.Fa flags 133in 134.Fa ctx . 135.Fn EVP_CIPHER_CTX_clear_flags 136disables the given 137.Fa flags 138in 139.Fa ctx . 140.Fn EVP_CIPHER_CTX_test_flags 141checks whether any of the given 142.Fa flags 143are currently set in 144.Fa ctx , 145returning the subset of the 146.Fa flags 147that are set, or 0 if none of them are set. 148Currently, the only supported cipher context flag is 149.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW ; 150see 151.Xr EVP_aes_128_wrap 3 152for details. 153.Pp 154.Fn EVP_CIPHER_CTX_rand_key 155generates a random key of the appropriate length based on the cipher 156context. 157The 158.Vt EVP_CIPHER 159can provide its own random key generation routine to support keys 160of a specific form. 161The 162.Fa key 163argument must point to a buffer at least as big as the value returned by 164.Xr EVP_CIPHER_CTX_key_length 3 . 165.Pp 166.Fn EVP_CIPHER_param_to_asn1 167sets the ASN.1 168.Vt AlgorithmIdentifier 169parameter based on the passed cipher. 170This will typically include any parameters and an IV. 171The cipher IV (if any) must be set when this call is made. 172This call should be made before the cipher is actually "used" (before any 173.Xr EVP_EncryptUpdate 3 174or 175.Xr EVP_DecryptUpdate 3 176calls, for example). 177This function may fail if the cipher does not have any ASN.1 support. 178.Pp 179.Fn EVP_CIPHER_asn1_to_param 180sets the cipher parameters based on an ASN.1 181.Vt AlgorithmIdentifier 182parameter. 183The precise effect depends on the cipher. 184In the case of RC2, for example, it will set the IV and effective 185key length. 186This function should be called after the base cipher type is set but 187before the key is set. 188For example 189.Xr EVP_CipherInit 3 190will be called with the IV and key set to 191.Dv NULL , 192.Fn EVP_CIPHER_asn1_to_param 193will be called and finally 194.Xr EVP_CipherInit 3 195again with all parameters except the key set to 196.Dv NULL . 197It is possible for this function to fail if the cipher does not 198have any ASN.1 support or the parameters cannot be set (for example 199the RC2 effective key length is not supported). 200.Sh RETURN VALUES 201.Fn EVP_CIPHER_CTX_rand_key 202return 1 for success or 0 for failure. 203.Pp 204.Fn EVP_CIPHER_param_to_asn1 205and 206.Fn EVP_CIPHER_asn1_to_param 207return greater than zero for success and zero or a negative number 208for failure. 209.Sh SEE ALSO 210.Xr evp 3 , 211.Xr EVP_CIPHER_CTX_ctrl 3 , 212.Xr EVP_CIPHER_CTX_get_cipher_data 3 , 213.Xr EVP_CIPHER_nid 3 , 214.Xr EVP_EncryptInit 3 215.Sh HISTORY 216.Fn EVP_CIPHER_CTX_set_app_data 217and 218.Fn EVP_CIPHER_CTX_get_app_data 219first appeared in SSLeay 0.8.0. 220.Fn EVP_CIPHER_param_to_asn1 221and 222.Fn EVP_CIPHER_asn1_to_param 223first appeared in SSLeay 0.9.0. 224These functions have been available since 225.Ox 2.4 . 226.Pp 227.Fn EVP_CIPHER_CTX_rand_key 228first appeared in OpenSSL 0.9.8 and has been available since 229.Ox 4.5 . 230.Sh BUGS 231The ASN.1 code is incomplete (and sometimes inaccurate). 232It has only been tested for certain common S/MIME ciphers 233(RC2, DES, triple DES) in CBC mode. 234