1.\" $OpenBSD: BIO_f_cipher.3,v 1.12 2019/06/06 01:06:58 schwarze Exp $ 2.\" OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700 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: June 6 2019 $ 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 encrypting, 137.Xr BIO_flush 3 138must be called to flush the final block through the BIO. 139If it is not, then the final block will fail a subsequent decrypt. 140.Pp 141When decrypting, an error on the final block is signalled 142by a zero return value from the read operation. 143A successful decrypt followed by EOF 144will also return zero for the final read. 145.Fn BIO_get_cipher_status 146should be called to determine if the decrypt was successful. 147.Pp 148As always, if 149.Xr BIO_gets 3 150or 151.Xr BIO_puts 3 152support is needed, then it can be achieved 153by preceding the cipher BIO with a buffering BIO. 154.Sh RETURN VALUES 155.Fn BIO_f_cipher 156returns the cipher BIO method. 157.Fn BIO_set_cipher 158returns 1 on success and 0 on error. 159.Pp 160.Fn BIO_get_cipher_status 161returns 1 for a successful decrypt and 0 for failure. 162.Pp 163.Fn BIO_get_cipher_ctx 164currently always returns 1. 165.Sh SEE ALSO 166.Xr BIO_new 3 , 167.Xr EVP_EncryptInit 3 168.Sh HISTORY 169.Fn BIO_f_cipher , 170.Fn BIO_set_cipher , 171and 172.Fn BIO_get_cipher_status 173first appeared in SSLeay 0.6.5 and have been available since 174.Ox 2.4 . 175.Pp 176.Fn BIO_get_cipher_ctx 177first appeared in SSLeay 0.9.1 and has been available since 178.Ox 2.6 . 179