xref: /openssl/doc/man7/EVP_KDF-PKCS12KDF.pod (revision 556009c5)
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
49This algorithm is not available in the FIPS provider as it is not FIPS
50approvable.
51
52A typical application of this algorithm is to derive keying material for an
53encryption algorithm from a password in the "pass", a salt in "salt",
54and an iteration count.
55
56Increasing the "iter" parameter slows down the algorithm which makes it
57harder for an attacker to perform a brute force attack using a large number
58of candidate passwords.
59
60No assumption is made regarding the given password; it is simply treated as a
61byte sequence.
62
63=head1 CONFORMING TO
64
65RFC7292
66
67=head1 SEE ALSO
68
69L<EVP_KDF(3)>,
70L<EVP_KDF_CTX_new(3)>,
71L<EVP_KDF_CTX_free(3)>,
72L<EVP_KDF_CTX_set_params(3)>,
73L<EVP_KDF_derive(3)>,
74L<EVP_KDF(3)/PARAMETERS>,
75L<OSSL_PROVIDER-FIPS(7)>
76
77=head1 HISTORY
78
79This functionality was added in OpenSSL 3.0.
80
81=head1 COPYRIGHT
82
83Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
84
85Licensed under the Apache License 2.0 (the "License").  You may not use
86this file except in compliance with the License.  You can obtain a copy
87in the file LICENSE in the source distribution or at
88L<https://www.openssl.org/source/license.html>.
89
90=cut
91