#use wml::openssl-macros area=docs page=BIO_f_cipher

<title>Documents, BIO_f_cipher(3)</title>

<h1>BIO_f_cipher(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#EXAMPLES">EXAMPLES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx -
cipher BIO filter

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bio.h&gt;
 \#include &lt;openssl/evp.h&gt;
</PRE>
<PRE> BIO_METHOD *   BIO_f_cipher(void);
 void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
                unsigned char *key, unsigned char *iv, int enc);
 int BIO_get_cipher_status(BIO *b)
 int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BIO_f_cipher()</CODE> returns the cipher BIO method. This is a filter
BIO that encrypts any data written through it, and decrypts any data read
from it. It is a BIO wrapper for the cipher routines
<CODE>EVP_CipherInit(),</CODE> <CODE>EVP_CipherUpdate()</CODE> and
<CODE>EVP_CipherFinal().</CODE>

</P>
<P>
Cipher BIOs do not support <CODE>BIO_gets()</CODE> or
<CODE>BIO_puts().</CODE> 

</P>
<P>
<CODE>BIO_flush()</CODE> on an encryption BIO that is being written through
is used to signal that no more data is to be encrypted: this is used to
flush and possibly pad the final block through the BIO.

</P>
<P>
<CODE>BIO_set_cipher()</CODE> sets the cipher of BIO <STRONG>b</STRONG> to <STRONG>cipher</STRONG> using key <STRONG>key</STRONG>
and IV <STRONG>iv</STRONG>. <STRONG>enc</STRONG> should be set to 1 for encryption and zero for decryption.

</P>
<P>
When reading from an encryption BIO the final block is automatically
decrypted and checked when EOF is detected.
<CODE>BIO_get_cipher_status()</CODE> is a <CODE>BIO_ctrl()</CODE> macro
which can be called to determine whether the decryption operation was
successful.

</P>
<P>
<CODE>BIO_get_cipher_ctx()</CODE> is a <CODE>BIO_ctrl()</CODE> macro which
retrieves the internal BIO cipher context. The retrieved context can be
used in conjunction with the standard cipher routines to set it up. This is
useful when <CODE>BIO_set_cipher()</CODE> is not flexible enough for the
applications needs.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
When encrypting <CODE>BIO_flush()</CODE> <STRONG>must</STRONG> be called to flush the final block through the BIO. If it is not then the
final block will fail a subsequent decrypt.

</P>
<P>
When decrypting an error on the final block is signalled by a zero return
value from the read operation. A successful decrypt followed by EOF will
also return zero for the final read. <CODE>BIO_get_cipher_status()</CODE>
should be called to determine if the decrypt was successful.

</P>
<P>
As always, if <CODE>BIO_gets()</CODE> or <CODE>BIO_puts()</CODE> support is
needed then it can be achieved by preceding the cipher BIO with a buffering
BIO.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BIO_f_cipher()</CODE> returns the cipher BIO method.

</P>
<P>
<CODE>BIO_set_cipher()</CODE> does not return a value.

</P>
<P>
<CODE>BIO_get_cipher_status()</CODE> returns 1 for a successful decrypt and
0 for failure.

</P>
<P>
<CODE>BIO_get_cipher_ctx()</CODE> currently always returns 1.

</P>
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
TBA

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
TBA
</P>
:}