]>
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 | ||
aebb9aac RS |
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); | |
55e42c93 DSH |
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 | |
186bb907 | 32 | harder for an attacker to perform a brute force attack using a large number |
55e42c93 DSH |
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 | ||
82c4d793 JW |
39 | Newer applications should use a more modern algorithm such as PBKDF2 as |
40 | defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. | |
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 | ||
1bc74519 | 47 | D_i = HASH^count(D_(i-1) || data || salt) |
55e42c93 | 48 | |
186bb907 | 49 | where || denotes concatenation, D_0 is empty, HASH is the digest |
55e42c93 DSH |
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 | ||
5aed1693 RS |
58 | If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes |
59 | needed to store the derived key. | |
60 | Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes, | |
61 | or 0 on error. | |
55e42c93 DSH |
62 | |
63 | =head1 SEE ALSO | |
64 | ||
b97fdb57 | 65 | L<evp(7)>, L<RAND_bytes(3)>, |
9b86974e RS |
66 | L<PKCS5_PBKDF2_HMAC(3)>, |
67 | L<EVP_EncryptInit(3)> | |
55e42c93 | 68 | |
e2f92610 RS |
69 | =head1 COPYRIGHT |
70 | ||
71 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
72 | ||
4746f25a | 73 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
74 | this file except in compliance with the License. You can obtain a copy |
75 | in the file LICENSE in the source distribution or at | |
76 | L<https://www.openssl.org/source/license.html>. | |
77 | ||
78 | =cut |