]>
Commit | Line | Data |
---|---|---|
b7466c13 P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-PKCS12KDF - The PKCS#12 EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | Support for computing the B<PKCS#12> password-based KDF through the B<EVP_KDF> | |
10 | API. | |
11 | ||
12 | The EVP_KDF-PKCS12KDF algorithm implements the PKCS#12 password-based key | |
13 | derivation function, as described in appendix B of RFC 7292 (PKCS #12: | |
14 | Personal Information Exchange Syntax); it derives a key from a password | |
15 | using a salt, iteration count and the intended usage. | |
16 | ||
17 | =head2 Identity | |
18 | ||
19 | "PKCS12KDF" is the name for this implementation; it | |
20 | can be used with the EVP_KDF_fetch() function. | |
21 | ||
22 | =head2 Supported parameters | |
23 | ||
24 | The supported parameters are: | |
25 | ||
26 | =over 4 | |
27 | ||
28 | =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> | |
29 | ||
30 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> | |
31 | ||
32 | =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> | |
33 | ||
34 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> | |
35 | ||
36 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> | |
37 | ||
38 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. | |
39 | ||
40 | =item "id" (B<OSSL_KDF_PARAM_PKCS12_ID>) <integer> | |
41 | ||
42 | This parameter is used to specify the intended usage of the output bits, as per | |
43 | RFC 7292 section B.3. | |
44 | ||
45 | =back | |
46 | ||
47 | =head1 NOTES | |
48 | ||
49 | A typical application of this algorithm is to derive keying material for an | |
50 | encryption algorithm from a password in the "pass", a salt in "salt", | |
51 | and an iteration count. | |
52 | ||
53 | Increasing the "iter" parameter slows down the algorithm which makes it | |
54 | harder for an attacker to perform a brute force attack using a large number | |
55 | of candidate passwords. | |
56 | ||
57 | No assumption is made regarding the given password; it is simply treated as a | |
58 | byte sequence. | |
59 | ||
60 | =head1 CONFORMING TO | |
61 | ||
62 | RFC7292 | |
63 | ||
64 | =head1 SEE ALSO | |
65 | ||
66 | L<EVP_KDF(3)>, | |
67 | L<EVP_KDF_CTX_new(3)>, | |
68 | L<EVP_KDF_CTX_free(3)>, | |
69 | L<EVP_KDF_CTX_set_params(3)>, | |
70 | L<EVP_KDF_derive(3)>, | |
71 | L<EVP_KDF(3)/PARAMETERS> | |
72 | ||
73 | =head1 HISTORY | |
74 | ||
4741c80c | 75 | This functionality was added in OpenSSL 3.0. |
b7466c13 P |
76 | |
77 | =head1 COPYRIGHT | |
78 | ||
79 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
80 | ||
81 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
82 | this file except in compliance with the License. You can obtain a copy | |
83 | in the file LICENSE in the source distribution or at | |
84 | L<https://www.openssl.org/source/license.html>. | |
85 | ||
86 | =cut |