1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948EVP_BytesToKey - password based encryption routine 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/evp.h> 10*2175Sjp161948 11*2175Sjp161948 int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md, 12*2175Sjp161948 const unsigned char *salt, 13*2175Sjp161948 const unsigned char *data, int datal, int count, 14*2175Sjp161948 unsigned char *key,unsigned char *iv); 15*2175Sjp161948 16*2175Sjp161948=head1 DESCRIPTION 17*2175Sjp161948 18*2175Sjp161948EVP_BytesToKey() derives a key and IV from various parameters. B<type> is 19*2175Sjp161948the cipher to derive the key and IV for. B<md> is the message digest to use. 20*2175Sjp161948The B<salt> paramter is used as a salt in the derivation: it should point to 21*2175Sjp161948an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing 22*2175Sjp161948B<datal> bytes which is used to derive the keying data. B<count> is the 23*2175Sjp161948iteration count to use. The derived key and IV will be written to B<key> 24*2175Sjp161948and B<iv> respectively. 25*2175Sjp161948 26*2175Sjp161948=head1 NOTES 27*2175Sjp161948 28*2175Sjp161948A typical application of this function is to derive keying material for an 29*2175Sjp161948encryption algorithm from a password in the B<data> parameter. 30*2175Sjp161948 31*2175Sjp161948Increasing the B<count> parameter slows down the algorithm which makes it 32*2175Sjp161948harder for an attacker to peform a brute force attack using a large number 33*2175Sjp161948of candidate passwords. 34*2175Sjp161948 35*2175Sjp161948If the total key and IV length is less than the digest length and 36*2175Sjp161948B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 37*2175Sjp161948otherwise a non standard extension is used to derive the extra data. 38*2175Sjp161948 39*2175Sjp161948Newer applications should use more standard algorithms such as PKCS#5 40*2175Sjp161948v2.0 for key derivation. 41*2175Sjp161948 42*2175Sjp161948=head1 KEY DERIVATION ALGORITHM 43*2175Sjp161948 44*2175Sjp161948The key and IV is derived by concatenating D_1, D_2, etc until 45*2175Sjp161948enough data is available for the key and IV. D_i is defined as: 46*2175Sjp161948 47*2175Sjp161948 D_i = HASH^count(D_(i-1) || data || salt) 48*2175Sjp161948 49*2175Sjp161948where || denotes concatentaion, D_0 is empty, HASH is the digest 50*2175Sjp161948algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) 51*2175Sjp161948is HASH(HASH(data)) and so on. 52*2175Sjp161948 53*2175Sjp161948The initial bytes are used for the key and the subsequent bytes for 54*2175Sjp161948the IV. 55*2175Sjp161948 56*2175Sjp161948=head1 RETURN VALUES 57*2175Sjp161948 58*2175Sjp161948EVP_BytesToKey() returns the size of the derived key in bytes. 59*2175Sjp161948 60*2175Sjp161948=head1 SEE ALSO 61*2175Sjp161948 62*2175Sjp161948L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, 63*2175Sjp161948L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> 64*2175Sjp161948 65*2175Sjp161948=head1 HISTORY 66*2175Sjp161948 67*2175Sjp161948=cut 68