reference/hash/functions/hash-pbkdf2.xml
7b68fb17124ccf73ed0c98974d90977a69ea0425
...
...
@@ -1,7 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
-
<refentry xml:id="function.hash-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3
+
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="function.hash-pbkdf2">
5
4
<refnamediv>
6
5
<refname>hash_pbkdf2</refname>
7
6
<refpurpose>Generate a PBKDF2 key derivation of a supplied password</refpurpose>
...
...
@@ -9,14 +8,14 @@
9
8

10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
-
<methodsynopsis role="procedural">
11
+
<methodsynopsis>
13
12
<type>string</type><methodname>hash_pbkdf2</methodname>
14
13
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
15
14
<methodparam><type>string</type><parameter>password</parameter></methodparam>
16
15
<methodparam><type>string</type><parameter>salt</parameter></methodparam>
17
16
<methodparam><type>int</type><parameter>iterations</parameter></methodparam>
18
17
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>0</initializer></methodparam>
19
-
<methodparam choice="opt"><type>bool</type><parameter>raw_output</parameter><initializer>&false;</initializer></methodparam>
18
+
<methodparam choice="opt"><type>bool</type><parameter>binary</parameter><initializer>&false;</initializer></methodparam>
20
19
</methodsynopsis>
21
20
</refsect1>
22
21

...
...
@@ -62,9 +61,9 @@
62
61
<term><parameter>length</parameter></term>
63
62
<listitem>
64
63
<para>
65
-
The length of the output string. If <parameter>raw_output</parameter>
64
+
The length of the output string. If <parameter>binary</parameter>
66
65
is &true; this corresponds to the byte-length of the derived key, if
67
-
<parameter>raw_output</parameter> is &false; this corresponds to twice the
66
+
<parameter>binary</parameter> is &false; this corresponds to twice the
68
67
byte-length of the derived key (as every byte of the key is returned as
69
68
two hexits).
70
69
</para>
...
...
@@ -75,7 +74,7 @@
75
74
</listitem>
76
75
</varlistentry>
77
76
<varlistentry>
78
-
<term><parameter>raw_output</parameter></term>
77
+
<term><parameter>binary</parameter></term>
79
78
<listitem>
80
79
<para>
81
80
When set to &true;, outputs raw binary data. &false; outputs lowercase
...
...
@@ -91,7 +90,7 @@
91
90
&reftitle.returnvalues;
92
91
<para>
93
92
Returns a string containing the derived key as lowercase hexits unless
94
-
<parameter>raw_output</parameter> is set to &true; in which case the raw
93
+
<parameter>binary</parameter> is set to &true; in which case the raw
95
94
binary representation of the derived key is returned.
96
95
</para>
97
96
</refsect1><!-- }}} -->
...
...
@@ -99,7 +98,7 @@
99
98
<refsect1 role="errors"><!-- {{{ -->
100
99
&reftitle.errors;
101
100
<para>
102
-
An <constant>E_WARNING</constant> will be raised if the algorithm is
101
+
Throws a <classname>ValueError</classname> exception if the algorithm is
103
102
unknown, the <parameter>iterations</parameter> parameter is less than or
104
103
equal to <literal>0</literal>, the <parameter>length</parameter> is less
105
104
than <literal>0</literal> or the <parameter>salt</parameter> is too long
...
...
@@ -120,6 +119,14 @@
120
119
</thead>
121
120
<tbody>
122
121
<row>
122
+
<entry>8.0.0</entry>
123
+
<entry>
124
+
Now throws a <classname>ValueError</classname> exception on error.
125
+
Previously, &false; was returned and an <constant>E_WARNING</constant>
126
+
message was emitted.
127
+
</entry>
128
+
</row>
129
+
<row>
123
130
<entry>7.2.0</entry>
124
131
<entry>Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.</entry>
125
132
</row>
...
...
@@ -138,21 +145,24 @@
138
145
<![CDATA[
139
146
<?php
140
147
$password = "password";
141
-
$iterations = 1000;
148
+
$iterations = 600000;
142
149

143
-
// Generate a random IV using openssl_random_pseudo_bytes()
144
-
// random_bytes() or another suitable source of randomness
145
-
$salt = openssl_random_pseudo_bytes(16);
150
+
// Generate a cryptographically secure random salt using random_bytes()
151
+
$salt = random_bytes(16);
146
152

147
153
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
148
-
echo $hash;
149
-
?>
154
+
var_dump($hash);
155
+

156
+
// for raw binary, the $length needs to be halved for equivalent results
157
+
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
158
+
var_dump(bin2hex($hash));?>
150
159
]]>
151
160
</programlisting>
152
161
&example.outputs.similar;
153
162
<screen>
154
163
<![CDATA[
155
-
120fb6cffcf8b32c43e7
164
+
string(20) "120fb6cffcf8b32c43e7"
165
+
string(20) "120fb6cffcf8b32c43e7"
156
166
]]>
157
167
</screen>
158
168
</example>
...
...
@@ -175,20 +185,14 @@ echo $hash;
175
185
&reftitle.seealso;
176
186
<para>
177
187
<simplelist>
178
-
<member><function>crypt</function></member>
179
188
<member><function>password_hash</function></member>
180
-
<member><function>hash</function></member>
181
-
<member><function>hash_algos</function></member>
182
-
<member><function>hash_init</function></member>
183
-
<member><function>hash_hmac</function></member>
184
-
<member><function>hash_hmac_file</function></member>
185
-
<member><function>openssl_pbkdf2</function></member>
189
+
<member><function>hash_hkdf</function></member>
190
+
<member><function>sodium_crypto_pwhash</function></member>
186
191
</simplelist>
187
192
</para>
188
193
</refsect1>
189
194

190
195
</refentry>
191
-

192
196
<!-- Keep this comment at the end of the file
193
197
Local variables:
194
198
mode: sgml
195
199