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