.\"	$OpenBSD: EVP_BytesToKey.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $
.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
.\"
.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2001, 2011, 2013, 2014, 2015 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: March 27 2018 $
.Dt EVP_BYTESTOKEY 3
.Os
.Sh NAME
.Nm EVP_BytesToKey
.Nd password based encryption routine
.Sh SYNOPSIS
.In openssl/evp.h
.Ft int
.Fo EVP_BytesToKey
.Fa "const EVP_CIPHER *type"
.Fa "const EVP_MD *md"
.Fa "const unsigned char *salt"
.Fa "const unsigned char *data"
.Fa "int datal"
.Fa "int count"
.Fa "unsigned char *key"
.Fa "unsigned char *iv"
.Fc
.Sh DESCRIPTION
.Fn EVP_BytesToKey
derives a key and IV from various parameters.
.Fa type
is the cipher to derive the key and IV for.
.Fa md
is the message digest to use.
The
.Fa salt
parameter is used as a salt in the derivation:
it should point to an 8-byte buffer or
.Dv NULL
if no salt is used.
.Fa data
is a buffer containing
.Fa datal
bytes which is used to derive the keying data.
.Fa count
is the iteration count to use.
The derived key and IV will be written to
.Fa key
and
.Fa iv ,
respectively.
.Pp
A typical application of this function is to derive keying material for
an encryption algorithm from a password in the
.Fa data
parameter.
.Pp
Increasing the
.Fa count
parameter slows down the algorithm, which makes it harder for an attacker
to perform a brute force attack using a large number of candidate
passwords.
.Pp
If the total key and IV length is less than the digest length and MD5
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.
.Pp
Newer applications should use more standard algorithms such as PBKDF2 as
defined in PKCS#5v2.1 for key derivation.
.Sh KEY DERIVATION ALGORITHM
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 recursively as:
.Pp
.Dl D_i = HASH^count(D_(i-1) || data || salt)
.Pp
where || denotes concatenation, D_0 is empty, HASH is the digest
algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) is
HASH(HASH(data)) and so on.
.Pp
The initial bytes are used for the key and the subsequent bytes for the
IV.
.Sh RETURN VALUES
If
.Fa data
is
.Dv NULL ,
.Fn EVP_BytesToKey
returns the number of bytes needed to store the derived key.
Otherwise,
.Fn EVP_BytesToKey
returns the size of the derived key in bytes or 0 on error.
.Sh SEE ALSO
.Xr evp 3 ,
.Xr EVP_EncryptInit 3 ,
.Xr PKCS5_PBKDF2_HMAC 3 ,
.Xr RAND_bytes 3
.Sh HISTORY
.Fn EVP_BytesToKey
first appeared in SSLeay 0.5.1 and has been available since
.Ox 2.4 .