Remove -WX option from debug-VC-WIN32
[openssl.git] / doc / crypto / EVP_BytesToKey.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_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
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.
20 The B<salt> parameter is used as a salt in the derivation: it should point to
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
39 Newer applications should use more standard algorithms such as PBKDF2 as
40 defined in PKCS#5v2.1 for key derivation.
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
58 EVP_BytesToKey() returns the size of the derived key in bytes, or 0 on error.
59
60 =head1 SEE ALSO
61
62 L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
63 L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
64
65 =head1 HISTORY
66
67 =cut