diff options
author | Pauli <paul.dale@oracle.com> | 2019-09-02 13:58:22 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2019-09-06 19:27:57 +1000 |
commit | ccd7115a4158a34008975ae83c3a733ba0be9911 (patch) | |
tree | b1dc5c6e85c84e6ad7a1784213836795be5444d4 /doc/man7/EVP_KDF-PBKDF2.pod | |
parent | 53598b22987faead115463bf8bd027cd8f794cf3 (diff) |
Update KDF documentation (section 7)
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9662)
Diffstat (limited to 'doc/man7/EVP_KDF-PBKDF2.pod')
-rw-r--r-- | doc/man7/EVP_KDF-PBKDF2.pod | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod new file mode 100644 index 0000000000..311e0a3769 --- /dev/null +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -0,0 +1,104 @@ +=pod + +=head1 NAME + +EVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF> +API. + +The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key +derivation function, as described in SP800-132; it derives a key from a password +using a salt and iteration count. + +=head2 Identity + +"PBKDF2" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> + +=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> + +=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned int> + +This parameter has a default value of 2048. + +=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> + +=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> + +These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. + +=item B<OSSL_KDF_PARAM_PKCS5> ("pkcs5") <int> + +This parameter can be used to enable or disable SP800-132 compliance checks. +Setting the mode to 0 enables the compliance checks. + +The checks performed are: + +=over 4 + +=item - the iteration count is at least 1000. + +=item - the salt length is at least 128 bits. + +=item - the derived key length is at least 112 bits. + +=back + +The default provider uses a default mode of 1 for backwards compatibility, +and the fips provider uses a default mode of 0. + +The value string is expected to be a decimal number 0 or 1. + +=back + +=head1 NOTES + +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the B<pass>, a salt in B<salt>, +and an iteration count. + +Increasing the B<iter> parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. + +No assumption is made regarding the given password; it is simply treated as a +byte sequence. + +=head1 CONFORMING TO + +SP800-132 + +=head1 SEE ALSO + +L<EVP_KDF>, +L<EVP_KDF-CTX_new_id(3)>, +L<EVP_KDF-CTX_free(3)>, +L<EVP_KDF-ctrl(3)>, +L<EVP_KDF-derive(3)>, +L<EVP_KDF-CTX(3)/PARAMETERS> + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |