reference/openssl/functions/openssl-pbkdf2.xml
5136ca8abac85850155a0ae7375124a52917b240
5136ca8abac85850155a0ae7375124a52917b240
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
4
3
<refentry xml:id="function.openssl-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>openssl_pbkdf2</refname>
...
...
@@ -10,12 +9,12 @@
10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
11
<methodsynopsis>
13
-
<type>string</type><methodname>openssl_pbkdf2</methodname>
14
-
<methodparam><type>string</type><parameter>password</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>openssl_pbkdf2</methodname>
13
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>
15
14
<methodparam><type>string</type><parameter>salt</parameter></methodparam>
16
15
<methodparam><type>int</type><parameter>key_length</parameter></methodparam>
17
16
<methodparam><type>int</type><parameter>iterations</parameter></methodparam>
18
-
<methodparam choice="opt"><type>string</type><parameter>digest_algorithm</parameter><initializer>"sha1"</initializer></methodparam>
17
+
<methodparam choice="opt"><type>string</type><parameter>digest_algo</parameter><initializer>"sha1"</initializer></methodparam>
19
18
</methodsynopsis>
20
19
<para>
21
20
<function>openssl_pbkdf2</function> computes PBKDF2 (Password-Based Key Derivation Function 2),
...
...
@@ -39,7 +38,7 @@
39
38
<term><parameter>salt</parameter></term>
40
39
<listitem>
41
40
<para>
42
-
PBKDF2 recommends a crytographic salt of at least 64 bits (8 bytes).
41
+
PBKDF2 recommends a crytographic salt of at least 128 bits (16 bytes).
43
42
</para>
44
43
</listitem>
45
44
</varlistentry>
...
...
@@ -55,17 +54,19 @@
55
54
<term><parameter>iterations</parameter></term>
56
55
<listitem>
57
56
<para>
58
-
The number of iterations desired. <link
59
-
xlink:href="https://pages.nist.gov/800-63-3/sp800-63b.html#sec5">NIST
60
-
recommends at least 10,000</link>.
57
+
The number of iterations desired.
58
+
<link xlink:href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST
59
+
recommends at least 1,000</link>. As of 2023, OWASP recommends 600,000 iterations for
60
+
PBKDF2-HMAC-SHA256 and 210,000 for PBKDF2-HMAC-SHA512.
61
61
</para>
62
62
</listitem>
63
63
</varlistentry>
64
64
<varlistentry>
65
-
<term><parameter>digest_algorithm</parameter></term>
65
+
<term><parameter>digest_algo</parameter></term>
66
66
<listitem>
67
67
<para>
68
-
Optional hash or digest algorithm from <function>openssl_get_md_methods</function>. Defaults to SHA-1.
68
+
Optional hash or digest algorithm from <function>openssl_get_md_methods</function>. Defaults
69
+
to SHA-1. It is recommended to set it to SHA-256 or SHA-512.
69
70
</para>
70
71
</listitem>
71
72
</varlistentry>
...
...
@@ -87,10 +88,10 @@
87
88
<programlisting role="php">
88
89
<![CDATA[
89
90
<?php
90
-
$password = 'yOuR-pAs5w0rd-hERe';
91
-
$salt = openssl_random_pseudo_bytes(12);
92
-
$keyLength = 40;
93
-
$iterations = 10000;
91
+
$password = 'password';
92
+
$salt = openssl_random_pseudo_bytes(16);
93
+
$keyLength = 20;
94
+
$iterations = 600000;
94
95
$generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
95
96
echo bin2hex($generated_key)."\n";
96
97
echo base64_encode($generated_key)."\n";
...
...
@@ -113,7 +114,6 @@ echo base64_encode($generated_key)."\n";
113
114
</refsect1>
114
115
115
116
</refentry>
116
-
117
117
<!-- Keep this comment at the end of the file
118
118
Local variables:
119
119
mode: sgml
120
120