1.\" $OpenBSD: BIO_f_cipher.3,v 1.13 2022/12/18 19:35:36 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: December 18 2022 $ 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.Nd cipher BIO filter 61.Sh SYNOPSIS 62.In openssl/bio.h 63.In openssl/evp.h 64.Ft const BIO_METHOD * 65.Fo BIO_f_cipher 66.Fa void 67.Fc 68.Ft int 69.Fo BIO_set_cipher 70.Fa "BIO *b" 71.Fa "const EVP_CIPHER *cipher" 72.Fa "unsigned char *key" 73.Fa "unsigned char *iv" 74.Fa "int enc" 75.Fc 76.Ft int 77.Fo BIO_get_cipher_status 78.Fa "BIO *b" 79.Fc 80.Ft int 81.Fo BIO_get_cipher_ctx 82.Fa "BIO *b" 83.Fa "EVP_CIPHER_CTX **pctx" 84.Fc 85.Sh DESCRIPTION 86.Fn BIO_f_cipher 87returns the cipher BIO method. 88This is a filter BIO that encrypts any data written through it, 89and decrypts any data read from it. 90It is a BIO wrapper for the cipher routines 91.Xr EVP_CipherInit 3 , 92.Xr EVP_CipherUpdate 3 , 93and 94.Xr EVP_CipherFinal 3 . 95.Pp 96Cipher BIOs do not support 97.Xr BIO_gets 3 98or 99.Xr BIO_puts 3 . 100.Pp 101.Xr BIO_flush 3 102on an encryption BIO that is being written through 103is used to signal that no more data is to be encrypted: 104this is used to flush and possibly pad the final block through the BIO. 105.Pp 106.Fn BIO_set_cipher 107sets the cipher of BIO 108.Fa b 109to 110.Fa cipher 111using key 112.Fa key 113and IV 114.Fa iv . 115.Fa enc 116should be set to 1 for encryption and zero for decryption. 117.Pp 118When reading from an encryption BIO, the final block is automatically 119decrypted and checked when EOF is detected. 120.Fn BIO_get_cipher_status 121is a 122.Xr BIO_ctrl 3 123macro which can be called to determine 124whether the decryption operation was successful. 125.Pp 126.Fn BIO_get_cipher_ctx 127is a 128.Xr BIO_ctrl 3 129macro which retrieves the internal BIO cipher context. 130The retrieved context can be used in conjunction 131with the standard cipher routines to set it up. 132This is useful when 133.Fn BIO_set_cipher 134is not flexible enough for the applications needs. 135.Pp 136When a chain containing a cipher BIO is copied with 137.Xr BIO_dup_chain 3 , 138the cipher context is automatically copied from the existing BIO object 139to the new one and the init flag that can be retrieved with 140.Xr BIO_get_init 3 141is set to 1. 142.Pp 143When encrypting, 144.Xr BIO_flush 3 145must be called to flush the final block through the BIO. 146If it is not, then the final block will fail a subsequent decrypt. 147.Pp 148When decrypting, an error on the final block is signalled 149by a zero return value from the read operation. 150A successful decrypt followed by EOF 151will also return zero for the final read. 152.Fn BIO_get_cipher_status 153should be called to determine if the decrypt was successful. 154.Pp 155As always, if 156.Xr BIO_gets 3 157or 158.Xr BIO_puts 3 159support is needed, then it can be achieved 160by preceding the cipher BIO with a buffering BIO. 161.Sh RETURN VALUES 162.Fn BIO_f_cipher 163returns the cipher BIO method. 164.Fn BIO_set_cipher 165returns 1 on success and 0 on error. 166.Pp 167.Fn BIO_get_cipher_status 168returns 1 for a successful decrypt and 0 for failure. 169.Pp 170.Fn BIO_get_cipher_ctx 171currently always returns 1. 172.Sh SEE ALSO 173.Xr BIO_new 3 , 174.Xr EVP_EncryptInit 3 175.Sh HISTORY 176.Fn BIO_f_cipher , 177.Fn BIO_set_cipher , 178and 179.Fn BIO_get_cipher_status 180first appeared in SSLeay 0.6.5 and have been available since 181.Ox 2.4 . 182.Pp 183.Fn BIO_get_cipher_ctx 184first appeared in SSLeay 0.9.1 and has been available since 185.Ox 2.6 . 186