1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosEVP_BytesToKey - password based encryption routine 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/evp.h> 10*4724848cSchristos 11*4724848cSchristos int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, 12*4724848cSchristos const unsigned char *salt, 13*4724848cSchristos const unsigned char *data, int datal, int count, 14*4724848cSchristos unsigned char *key, unsigned char *iv); 15*4724848cSchristos 16*4724848cSchristos=head1 DESCRIPTION 17*4724848cSchristos 18*4724848cSchristosEVP_BytesToKey() derives a key and IV from various parameters. B<type> is 19*4724848cSchristosthe cipher to derive the key and IV for. B<md> is the message digest to use. 20*4724848cSchristosThe B<salt> parameter is used as a salt in the derivation: it should point to 21*4724848cSchristosan 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing 22*4724848cSchristosB<datal> bytes which is used to derive the keying data. B<count> is the 23*4724848cSchristositeration count to use. The derived key and IV will be written to B<key> 24*4724848cSchristosand B<iv> respectively. 25*4724848cSchristos 26*4724848cSchristos=head1 NOTES 27*4724848cSchristos 28*4724848cSchristosA typical application of this function is to derive keying material for an 29*4724848cSchristosencryption algorithm from a password in the B<data> parameter. 30*4724848cSchristos 31*4724848cSchristosIncreasing the B<count> parameter slows down the algorithm which makes it 32*4724848cSchristosharder for an attacker to perform a brute force attack using a large number 33*4724848cSchristosof candidate passwords. 34*4724848cSchristos 35*4724848cSchristosIf the total key and IV length is less than the digest length and 36*4724848cSchristosB<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 37*4724848cSchristosotherwise a non standard extension is used to derive the extra data. 38*4724848cSchristos 39*4724848cSchristosNewer applications should use a more modern algorithm such as PBKDF2 as 40*4724848cSchristosdefined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. 41*4724848cSchristos 42*4724848cSchristos=head1 KEY DERIVATION ALGORITHM 43*4724848cSchristos 44*4724848cSchristosThe key and IV is derived by concatenating D_1, D_2, etc until 45*4724848cSchristosenough data is available for the key and IV. D_i is defined as: 46*4724848cSchristos 47*4724848cSchristos D_i = HASH^count(D_(i-1) || data || salt) 48*4724848cSchristos 49*4724848cSchristoswhere || denotes concatenation, D_0 is empty, HASH is the digest 50*4724848cSchristosalgorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) 51*4724848cSchristosis HASH(HASH(data)) and so on. 52*4724848cSchristos 53*4724848cSchristosThe initial bytes are used for the key and the subsequent bytes for 54*4724848cSchristosthe IV. 55*4724848cSchristos 56*4724848cSchristos=head1 RETURN VALUES 57*4724848cSchristos 58*4724848cSchristosIf B<data> is NULL, then EVP_BytesToKey() returns the number of bytes 59*4724848cSchristosneeded to store the derived key. 60*4724848cSchristosOtherwise, EVP_BytesToKey() returns the size of the derived key in bytes, 61*4724848cSchristosor 0 on error. 62*4724848cSchristos 63*4724848cSchristos=head1 SEE ALSO 64*4724848cSchristos 65*4724848cSchristosL<evp(7)>, L<RAND_bytes(3)>, 66*4724848cSchristosL<PKCS5_PBKDF2_HMAC(3)>, 67*4724848cSchristosL<EVP_EncryptInit(3)> 68*4724848cSchristos 69*4724848cSchristos=head1 COPYRIGHT 70*4724848cSchristos 71*4724848cSchristosCopyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. 72*4724848cSchristos 73*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 74*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 75*4724848cSchristosin the file LICENSE in the source distribution or at 76*4724848cSchristosL<https://www.openssl.org/source/license.html>. 77*4724848cSchristos 78*4724848cSchristos=cut 79