1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 DESCRIPTION 8*b077aed3SPierre Pronchery 9*b077aed3SPierre ProncherySupport for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF> 10*b077aed3SPierre ProncheryAPI. 11*b077aed3SPierre Pronchery 12*b077aed3SPierre ProncheryThe EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key 13*b077aed3SPierre Proncheryderivation function, as described in SP800-132; it derives a key from a password 14*b077aed3SPierre Proncheryusing a salt and iteration count. 15*b077aed3SPierre Pronchery 16*b077aed3SPierre Pronchery=head2 Identity 17*b077aed3SPierre Pronchery 18*b077aed3SPierre Pronchery"PBKDF2" is the name for this implementation; it 19*b077aed3SPierre Proncherycan be used with the EVP_KDF_fetch() function. 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery=head2 Supported parameters 22*b077aed3SPierre Pronchery 23*b077aed3SPierre ProncheryThe supported parameters are: 24*b077aed3SPierre Pronchery 25*b077aed3SPierre Pronchery=over 4 26*b077aed3SPierre Pronchery 27*b077aed3SPierre Pronchery=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> 28*b077aed3SPierre Pronchery 29*b077aed3SPierre Pronchery=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 30*b077aed3SPierre Pronchery 31*b077aed3SPierre Pronchery=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> 32*b077aed3SPierre Pronchery 33*b077aed3SPierre ProncheryThis parameter has a default value of 2048. 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 36*b077aed3SPierre Pronchery 37*b077aed3SPierre Pronchery=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 38*b077aed3SPierre Pronchery 39*b077aed3SPierre ProncheryThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 40*b077aed3SPierre Pronchery 41*b077aed3SPierre Pronchery=item "pkcs5" (B<OSSL_KDF_PARAM_PKCS5>) <integer> 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryThis parameter can be used to enable or disable SP800-132 compliance checks. 44*b077aed3SPierre ProncherySetting the mode to 0 enables the compliance checks. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryThe checks performed are: 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery=over 4 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Pronchery=item - the iteration count is at least 1000. 51*b077aed3SPierre Pronchery 52*b077aed3SPierre Pronchery=item - the salt length is at least 128 bits. 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=item - the derived key length is at least 112 bits. 55*b077aed3SPierre Pronchery 56*b077aed3SPierre Pronchery=back 57*b077aed3SPierre Pronchery 58*b077aed3SPierre ProncheryThe default provider uses a default mode of 1 for backwards compatibility, 59*b077aed3SPierre Proncheryand the FIPS provider uses a default mode of 0. 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryThe value string is expected to be a decimal number 0 or 1. 62*b077aed3SPierre Pronchery 63*b077aed3SPierre Pronchery=back 64*b077aed3SPierre Pronchery 65*b077aed3SPierre Pronchery=head1 NOTES 66*b077aed3SPierre Pronchery 67*b077aed3SPierre ProncheryA typical application of this algorithm is to derive keying material for an 68*b077aed3SPierre Proncheryencryption algorithm from a password in the "pass", a salt in "salt", 69*b077aed3SPierre Proncheryand an iteration count. 70*b077aed3SPierre Pronchery 71*b077aed3SPierre ProncheryIncreasing the "iter" parameter slows down the algorithm which makes it 72*b077aed3SPierre Proncheryharder for an attacker to perform a brute force attack using a large number 73*b077aed3SPierre Proncheryof candidate passwords. 74*b077aed3SPierre Pronchery 75*b077aed3SPierre ProncheryNo assumption is made regarding the given password; it is simply treated as a 76*b077aed3SPierre Proncherybyte sequence. 77*b077aed3SPierre Pronchery 78*b077aed3SPierre Pronchery=head1 CONFORMING TO 79*b077aed3SPierre Pronchery 80*b077aed3SPierre ProncherySP800-132 81*b077aed3SPierre Pronchery 82*b077aed3SPierre Pronchery=head1 SEE ALSO 83*b077aed3SPierre Pronchery 84*b077aed3SPierre ProncheryL<EVP_KDF(3)>, 85*b077aed3SPierre ProncheryL<EVP_KDF_CTX_new(3)>, 86*b077aed3SPierre ProncheryL<EVP_KDF_CTX_free(3)>, 87*b077aed3SPierre ProncheryL<EVP_KDF_CTX_set_params(3)>, 88*b077aed3SPierre ProncheryL<EVP_KDF_derive(3)>, 89*b077aed3SPierre ProncheryL<EVP_KDF(3)/PARAMETERS> 90*b077aed3SPierre Pronchery 91*b077aed3SPierre Pronchery=head1 HISTORY 92*b077aed3SPierre Pronchery 93*b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 94*b077aed3SPierre Pronchery 95*b077aed3SPierre Pronchery=head1 COPYRIGHT 96*b077aed3SPierre Pronchery 97*b077aed3SPierre ProncheryCopyright 2018-2022 The OpenSSL Project Authors. All Rights Reserved. 98*b077aed3SPierre Pronchery 99*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 100*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 101*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 102*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 103*b077aed3SPierre Pronchery 104*b077aed3SPierre Pronchery=cut 105