168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/bio.h> 1068651Skris #include <openssl/evp.h> 1168651Skris 1268651Skris BIO_METHOD * BIO_f_cipher(void); 1368651Skris void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher, 1468651Skris unsigned char *key, unsigned char *iv, int enc); 1568651Skris int BIO_get_cipher_status(BIO *b) 1668651Skris int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx) 1768651Skris 1868651Skris=head1 DESCRIPTION 1968651Skris 2068651SkrisBIO_f_cipher() returns the cipher BIO method. This is a filter 2168651SkrisBIO that encrypts any data written through it, and decrypts any data 2268651Skrisread from it. It is a BIO wrapper for the cipher routines 2368651SkrisEVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal(). 2468651Skris 2568651SkrisCipher BIOs do not support BIO_gets() or BIO_puts(). 2668651Skris 2768651SkrisBIO_flush() on an encryption BIO that is being written through is 2868651Skrisused to signal that no more data is to be encrypted: this is used 2968651Skristo flush and possibly pad the final block through the BIO. 3068651Skris 31120631SnectarBIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key> 3268651Skrisand IV B<iv>. B<enc> should be set to 1 for encryption and zero for 3368651Skrisdecryption. 3468651Skris 3568651SkrisWhen reading from an encryption BIO the final block is automatically 3668651Skrisdecrypted and checked when EOF is detected. BIO_get_cipher_status() 3768651Skrisis a BIO_ctrl() macro which can be called to determine whether the 3868651Skrisdecryption operation was successful. 3968651Skris 4068651SkrisBIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal 4168651SkrisBIO cipher context. The retrieved context can be used in conjunction 4268651Skriswith the standard cipher routines to set it up. This is useful when 4368651SkrisBIO_set_cipher() is not flexible enough for the applications needs. 4468651Skris 4568651Skris=head1 NOTES 4668651Skris 4768651SkrisWhen encrypting BIO_flush() B<must> be called to flush the final block 4868651Skristhrough the BIO. If it is not then the final block will fail a subsequent 4968651Skrisdecrypt. 5068651Skris 5168651SkrisWhen decrypting an error on the final block is signalled by a zero 5268651Skrisreturn value from the read operation. A successful decrypt followed 5368651Skrisby EOF will also return zero for the final read. BIO_get_cipher_status() 5468651Skrisshould be called to determine if the decrypt was successful. 5568651Skris 5668651SkrisAs always, if BIO_gets() or BIO_puts() support is needed then it can 5768651Skrisbe achieved by preceding the cipher BIO with a buffering BIO. 5868651Skris 5968651Skris=head1 RETURN VALUES 6068651Skris 6168651SkrisBIO_f_cipher() returns the cipher BIO method. 6268651Skris 6368651SkrisBIO_set_cipher() does not return a value. 6468651Skris 6568651SkrisBIO_get_cipher_status() returns 1 for a successful decrypt and 0 6668651Skrisfor failure. 6768651Skris 6868651SkrisBIO_get_cipher_ctx() currently always returns 1. 6968651Skris 7068651Skris=head1 EXAMPLES 7168651Skris 7268651SkrisTBA 7368651Skris 7468651Skris=head1 SEE ALSO 7568651Skris 7668651SkrisTBA 77