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