113d40330Schristos=pod 213d40330Schristos 313d40330Schristos=head1 NAME 413d40330Schristos 513d40330SchristosEVP_BytesToKey - password based encryption routine 613d40330Schristos 713d40330Schristos=head1 SYNOPSIS 813d40330Schristos 913d40330Schristos #include <openssl/evp.h> 1013d40330Schristos 1113d40330Schristos int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, 1213d40330Schristos const unsigned char *salt, 1313d40330Schristos const unsigned char *data, int datal, int count, 1413d40330Schristos unsigned char *key, unsigned char *iv); 1513d40330Schristos 1613d40330Schristos=head1 DESCRIPTION 1713d40330Schristos 1813d40330SchristosEVP_BytesToKey() derives a key and IV from various parameters. B<type> is 1913d40330Schristosthe cipher to derive the key and IV for. B<md> is the message digest to use. 2013d40330SchristosThe B<salt> parameter is used as a salt in the derivation: it should point to 2113d40330Schristosan 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing 2213d40330SchristosB<datal> bytes which is used to derive the keying data. B<count> is the 2313d40330Schristositeration count to use. The derived key and IV will be written to B<key> 2413d40330Schristosand B<iv> respectively. 2513d40330Schristos 2613d40330Schristos=head1 NOTES 2713d40330Schristos 2813d40330SchristosA typical application of this function is to derive keying material for an 2913d40330Schristosencryption algorithm from a password in the B<data> parameter. 3013d40330Schristos 3113d40330SchristosIncreasing the B<count> parameter slows down the algorithm which makes it 3213d40330Schristosharder for an attacker to perform a brute force attack using a large number 3313d40330Schristosof candidate passwords. 3413d40330Schristos 3513d40330SchristosIf the total key and IV length is less than the digest length and 3613d40330SchristosB<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 3713d40330Schristosotherwise a non standard extension is used to derive the extra data. 3813d40330Schristos 3913d40330SchristosNewer applications should use a more modern algorithm such as PBKDF2 as 4013d40330Schristosdefined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. 4113d40330Schristos 4213d40330Schristos=head1 KEY DERIVATION ALGORITHM 4313d40330Schristos 4413d40330SchristosThe key and IV is derived by concatenating D_1, D_2, etc until 4513d40330Schristosenough data is available for the key and IV. D_i is defined as: 4613d40330Schristos 4713d40330Schristos D_i = HASH^count(D_(i-1) || data || salt) 4813d40330Schristos 4913d40330Schristoswhere || denotes concatenation, D_0 is empty, HASH is the digest 5013d40330Schristosalgorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) 5113d40330Schristosis HASH(HASH(data)) and so on. 5213d40330Schristos 5313d40330SchristosThe initial bytes are used for the key and the subsequent bytes for 5413d40330Schristosthe IV. 5513d40330Schristos 5613d40330Schristos=head1 RETURN VALUES 5713d40330Schristos 5813d40330SchristosIf B<data> is NULL, then EVP_BytesToKey() returns the number of bytes 5913d40330Schristosneeded to store the derived key. 6013d40330SchristosOtherwise, EVP_BytesToKey() returns the size of the derived key in bytes, 6113d40330Schristosor 0 on error. 6213d40330Schristos 6313d40330Schristos=head1 SEE ALSO 6413d40330Schristos 6513d40330SchristosL<evp(7)>, L<RAND_bytes(3)>, 6613d40330SchristosL<PKCS5_PBKDF2_HMAC(3)>, 6713d40330SchristosL<EVP_EncryptInit(3)> 6813d40330Schristos 6913d40330Schristos=head1 COPYRIGHT 7013d40330Schristos 7113d40330SchristosCopyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. 7213d40330Schristos 73*b0d17251SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 7413d40330Schristosthis file except in compliance with the License. You can obtain a copy 7513d40330Schristosin the file LICENSE in the source distribution or at 7613d40330SchristosL<https://www.openssl.org/source/license.html>. 7713d40330Schristos 7813d40330Schristos=cut 79