1.Dd $Mdocdate: September 9 2015 $ 2.Dt BIO_F_CIPHER 3 3.Os 4.Sh NAME 5.Nm BIO_f_cipher , 6.Nm BIO_set_cipher , 7.Nm BIO_get_cipher_status , 8.Nm BIO_get_cipher_ctx 9.Nd cipher BIO filter 10.Sh SYNOPSIS 11.In openssl/bio.h 12.In openssl/evp.h 13.Ft BIO_METHOD * 14.Fo BIO_f_cipher 15.Fa void 16.Fc 17.Ft void 18.Fo BIO_set_cipher 19.Fa "BIO *b" 20.Fa "const EVP_CIPHER *cipher" 21.Fa "unsigned char *key" 22.Fa "unsigned char *iv" 23.Fa "int enc" 24.Fc 25.Ft int 26.Fo BIO_get_cipher_status 27.Fa "BIO *b" 28.Fc 29.Ft int 30.Fo BIO_get_cipher_ctx 31.Fa "BIO *b" 32.Fa "EVP_CIPHER_CTX **pctx" 33.Fc 34.Sh DESCRIPTION 35.Fn BIO_f_cipher 36returns the cipher BIO method. 37This is a filter BIO that encrypts any data written through it, 38and decrypts any data read from it. 39It is a BIO wrapper for the cipher routines 40.Xr EVP_CipherInit 3 , 41.Xr EVP_CipherUpdate 3 , 42and 43.Xr EVP_CipherFinal 3 . 44.Pp 45Cipher BIOs do not support 46.Xr BIO_gets 3 47or 48.Xr BIO_puts 3 . 49.Pp 50.Xr BIO_flush 3 51on an encryption BIO that is being written through 52is used to signal that no more data is to be encrypted: 53this is used to flush and possibly pad the final block through the BIO. 54.Pp 55.Fn BIO_set_cipher 56sets the cipher of BIO 57.Fa b 58to 59.Fa cipher 60using key 61.Fa key 62and IV 63.Fa iv . 64.Fa enc 65should be set to 1 for encryption and zero for decryption. 66.Pp 67When reading from an encryption BIO, the final block is automatically 68decrypted and checked when EOF is detected. 69.Fn BIO_get_cipher_status 70is a 71.Xr BIO_ctrl 3 72macro which can be called to determine 73whether the decryption operation was successful. 74.Pp 75.Fn BIO_get_cipher_ctx 76is a 77.Xr BIO_ctrl 3 78macro which retrieves the internal BIO cipher context. 79The retrieved context can be used in conjunction 80with the standard cipher routines to set it up. 81This is useful when 82.Fn BIO_set_cipher 83is not flexible enough for the applications needs. 84.Sh NOTES 85When encrypting, 86.Xr BIO_flush 3 87must be called to flush the final block through the BIO. 88If it is not, then the final block will fail a subsequent decrypt. 89.Pp 90When decrypting, an error on the final block is signalled 91by a zero return value from the read operation. 92A successful decrypt followed by EOF 93will also return zero for the final read. 94.Fn BIO_get_cipher_status 95should be called to determine if the decrypt was successful. 96.Pp 97As always, if 98.Xr BIO_gets 3 99or 100.Xr BIO_puts 3 101support is needed, then it can be achieved 102by preceding the cipher BIO with a buffering BIO. 103.Sh RETURN VALUES 104.Fn BIO_f_cipher 105returns the cipher BIO method. 106.Pp 107.Fn BIO_set_cipher 108does not return a value. 109.Pp 110.Fn BIO_get_cipher_status 111returns 1 for a successful decrypt and 0 for failure. 112.Pp 113.Fn BIO_get_cipher_ctx 114currently always returns 1. 115