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