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

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

<h1>EVP_BytesToKey(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="#KEY_DERIVATION_ALGORITHM">KEY DERIVATION ALGORITHM</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
EVP_BytesToKey - password based encryption routine

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/evp.h&gt;
</PRE>
<PRE> int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md,
                       const unsigned char *salt,
                       const unsigned char *data, int datal, int count,
                       unsigned char *key,unsigned char *iv);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>EVP_BytesToKey()</CODE> derives a key and IV from various parameters. <STRONG>type</STRONG> is the cipher to derive the key and IV for. <STRONG>md</STRONG> is the message digest to use. The <STRONG>salt</STRONG> paramter is used as a salt in the derivation: it should point to an 8 byte
buffer or NULL if no salt is used. <STRONG>data</STRONG> is a buffer containing
<STRONG>datal</STRONG> bytes which is used to derive the keying data. <STRONG>count</STRONG> is the iteration count to use. The derived key and IV will be written to <STRONG>key</STRONG>
and <STRONG>iv</STRONG> respectively.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
A typical application of this function is to derive keying material for an
encryption algorithm from a password in the <STRONG>data</STRONG> parameter.

</P>
<P>
Increasing the <STRONG>count</STRONG> parameter slows down the algorithm which makes it harder for an attacker to
peform a brute force attack using a large number of candidate passwords.

</P>
<P>
If the total key and IV length is less than the digest length and
<STRONG>MD5</STRONG> is used then the derivation algorithm is compatible with PKCS#5 v1.5
otherwise a non standard extension is used to derive the extra data.

</P>
<P>
Newer applications should use more standard algorithms such as PKCS#5 v2.0
for key derivation.

</P>
<P>
<HR>
<H1><A NAME="KEY_DERIVATION_ALGORITHM">KEY DERIVATION ALGORITHM</A></H1>
<P>
The key and IV is derived by concatenating D_1, D_2, etc until enough data
is available for the key and IV. D_i is defined as:

</P>
<PRE>        D_i = HASH^count(D_(i-1) || data || salt)
</PRE>
<P>
where || denotes concatentaion, D_0 is empty, HASH is the digest algorithm
in use, HASH^1(data) is simply <CODE>HASH(data),</CODE> HASH^2(data) is
<CODE>HASH(HASH(data))</CODE> and so on.

</P>
<P>
The initial bytes are used for the key and the subsequent bytes for the IV.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>EVP_BytesToKey()</CODE> returns the size of the derived key in bytes,
or 0 on error.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/evp.html#">evp(3)</A>, <A HREF="../crypto/rand.html#">rand(3)</A>,
<A HREF="../crypto/EVP_EncryptInit.html#">EVP_EncryptInit(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
:}