1.\" $OpenBSD: BIO_f_cipher.3,v 1.16 2023/04/29 12:01:53 schwarze Exp $ 2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2000, 2003, 2015, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: April 29 2023 $ 53.Dt BIO_F_CIPHER 3 54.Os 55.Sh NAME 56.Nm BIO_f_cipher , 57.Nm BIO_set_cipher , 58.Nm BIO_get_cipher_status , 59.Nm BIO_get_cipher_ctx 60.\" .Nm BIO_CTRL_SET is intentionally undocumented because it has no effect. 61.Nd cipher BIO filter 62.Sh SYNOPSIS 63.In openssl/bio.h 64.In openssl/evp.h 65.Ft const BIO_METHOD * 66.Fo BIO_f_cipher 67.Fa void 68.Fc 69.Ft int 70.Fo BIO_set_cipher 71.Fa "BIO *b" 72.Fa "const EVP_CIPHER *cipher" 73.Fa "unsigned char *key" 74.Fa "unsigned char *iv" 75.Fa "int enc" 76.Fc 77.Ft long 78.Fo BIO_get_cipher_status 79.Fa "BIO *b" 80.Fc 81.Ft long 82.Fo BIO_get_cipher_ctx 83.Fa "BIO *b" 84.Fa "EVP_CIPHER_CTX **pctx" 85.Fc 86.Sh DESCRIPTION 87.Fn BIO_f_cipher 88returns the cipher BIO method. 89This is a filter BIO that encrypts any data written through it, 90and decrypts any data read from it. 91It is a BIO wrapper for the cipher routines 92.Xr EVP_CipherInit 3 , 93.Xr EVP_CipherUpdate 3 , 94and 95.Xr EVP_CipherFinal 3 . 96.Pp 97Cipher BIOs do not support 98.Xr BIO_gets 3 99or 100.Xr BIO_puts 3 . 101.Pp 102.Xr BIO_flush 3 103on an encryption BIO that is being written through 104is used to signal that no more data is to be encrypted: 105this is used to flush and possibly pad the final block through the BIO. 106.Pp 107.Fn BIO_set_cipher 108sets the cipher of BIO 109.Fa b 110to 111.Fa cipher 112using key 113.Fa key 114and IV 115.Fa iv . 116.Fa enc 117should be set to 1 for encryption and zero for decryption. 118.Pp 119When reading from an encryption BIO, the final block is automatically 120decrypted and checked when EOF is detected. 121.Fn BIO_get_cipher_status 122is a 123.Xr BIO_ctrl 3 124macro which can be called to determine 125whether the decryption operation was successful. 126.Pp 127.Fn BIO_get_cipher_ctx 128is a 129.Xr BIO_ctrl 3 130macro which retrieves the internal BIO cipher context. 131The retrieved context can be used in conjunction 132with the standard cipher routines to set it up. 133This is useful when 134.Fn BIO_set_cipher 135is not flexible enough for the applications needs. 136.Pp 137When a chain containing a cipher BIO is copied with 138.Xr BIO_dup_chain 3 , 139the cipher context is automatically copied from the existing BIO object 140to the new one and the init flag that can be retrieved with 141.Xr BIO_get_init 3 142is set to 1. 143.Pp 144When encrypting, 145.Xr BIO_flush 3 146must be called to flush the final block through the BIO. 147If it is not, then the final block will fail a subsequent decrypt. 148.Pp 149When decrypting, an error on the final block is signalled 150by a zero return value from the read operation. 151A successful decrypt followed by EOF 152will also return zero for the final read. 153.Fn BIO_get_cipher_status 154should be called to determine if the decrypt was successful. 155.Pp 156As always, if 157.Xr BIO_gets 3 158or 159.Xr BIO_puts 3 160support is needed, then it can be achieved 161by preceding the cipher BIO with a buffering BIO. 162.Pp 163.Xr BIO_ctrl 3 164.Fa cmd 165arguments correspond to macros as follows: 166.Bl -column BIO_C_GET_CIPHER_STATUS BIO_get_cipher_status() -offset 3n 167.It Fa cmd No constant Ta corresponding macro 168.It Dv BIO_C_GET_CIPHER_CTX Ta Fn BIO_get_cipher_ctx 169.It Dv BIO_C_GET_CIPHER_STATUS Ta Fn BIO_get_cipher_status 170.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 171.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 172.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 173.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 174.El 175.Sh RETURN VALUES 176.Fn BIO_f_cipher 177returns the cipher BIO method. 178.Pp 179When called on a cipher BIO object, 180.Xr BIO_method_type 3 181returns the constant 182.Dv BIO_TYPE_CIPHER 183and 184.Xr BIO_method_name 3 185returns a pointer to the static string 186.Qq cipher . 187.Pp 188.Fn BIO_set_cipher 189returns 1 on success and 0 on error. 190.Pp 191.Fn BIO_get_cipher_status 192returns 1 for a successful decrypt and 0 for failure. 193.Pp 194.Fn BIO_get_cipher_ctx 195currently always returns 1. 196.Sh SEE ALSO 197.Xr BIO_new 3 , 198.Xr EVP_EncryptInit 3 199.Sh HISTORY 200.Fn BIO_f_cipher , 201.Fn BIO_set_cipher , 202and 203.Fn BIO_get_cipher_status 204first appeared in SSLeay 0.6.5 and have been available since 205.Ox 2.4 . 206.Pp 207.Fn BIO_get_cipher_ctx 208first appeared in SSLeay 0.9.1 and has been available since 209.Ox 2.6 . 210