]>
Commit | Line | Data |
---|---|---|
55e42c93 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d90e74c5 | 5 | EVP_BytesToKey - password based encryption routine |
55e42c93 DSH |
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 | ||
18 | EVP_BytesToKey() derives a key and IV from various parameters. B<type> is | |
19 | the cipher to derive the key and IV for. B<md> is the message digest to use. | |
2b4ffc65 | 20 | The B<salt> parameter is used as a salt in the derivation: it should point to |
55e42c93 DSH |
21 | an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing |
22 | B<datal> bytes which is used to derive the keying data. B<count> is the | |
23 | iteration count to use. The derived key and IV will be written to B<key> | |
24 | and B<iv> respectively. | |
25 | ||
26 | =head1 NOTES | |
27 | ||
28 | A typical application of this function is to derive keying material for an | |
29 | encryption algorithm from a password in the B<data> parameter. | |
30 | ||
31 | Increasing the B<count> parameter slows down the algorithm which makes it | |
32 | harder for an attacker to peform a brute force attack using a large number | |
33 | of candidate passwords. | |
34 | ||
35 | If the total key and IV length is less than the digest length and | |
36 | B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 | |
37 | otherwise a non standard extension is used to derive the extra data. | |
38 | ||
aafbe1cc MC |
39 | Newer applications should use more standard algorithms such as PBKDF2 as |
40 | defined in PKCS#5v2.1 for key derivation. | |
55e42c93 DSH |
41 | |
42 | =head1 KEY DERIVATION ALGORITHM | |
43 | ||
44 | The key and IV is derived by concatenating D_1, D_2, etc until | |
45 | enough 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 | ||
49 | where || denotes concatentaion, D_0 is empty, HASH is the digest | |
50 | algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) | |
51 | is HASH(HASH(data)) and so on. | |
52 | ||
53 | The initial bytes are used for the key and the subsequent bytes for | |
54 | the IV. | |
55 | ||
56 | =head1 RETURN VALUES | |
57 | ||
ae551760 | 58 | EVP_BytesToKey() returns the size of the derived key in bytes, or 0 on error. |
55e42c93 DSH |
59 | |
60 | =head1 SEE ALSO | |
61 | ||
62 | L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, | |
401ee37a | 63 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> |
55e42c93 DSH |
64 | |
65 | =head1 HISTORY | |
66 | ||
67 | =cut |