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

4
3
<refentry xml:id="function.hash-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>hash_pbkdf2</refname>
...
...
@@ -9,14 +8,15 @@
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
-
<methodparam><type>string</type><parameter>password</parameter></methodparam>
14
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><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>
19
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
20
20
</methodsynopsis>
21
21
</refsect1>
22
22

...
...
@@ -28,9 +28,13 @@
28
28
<term><parameter>algo</parameter></term>
29
29
<listitem>
30
30
<para>
31
-
Name of selected hashing algorithm (i.e. <literal>md5</literal>,
32
-
<literal>sha256</literal>, <literal>haval160,4</literal>, etc..) See
33
-
<function>hash_algos</function> for a list of supported algorithms.
31
+
Name of selected hashing algorithm (e.g. <literal>"sha256"</literal>).
32
+
For a list of supported algorithms see <function>hash_hmac_algos</function>.
33
+
<note>
34
+
<para>
35
+
Non-cryptographic hash functions are not allowed.
36
+
</para>
37
+
</note>
34
38
</para>
35
39
</listitem>
36
40
</varlistentry>
...
...
@@ -62,9 +66,9 @@
62
66
<term><parameter>length</parameter></term>
63
67
<listitem>
64
68
<para>
65
-
The length of the output string. If <parameter>raw_output</parameter>
69
+
The length of the output string. If <parameter>binary</parameter>
66
70
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
71
+
<parameter>binary</parameter> is &false; this corresponds to twice the
68
72
byte-length of the derived key (as every byte of the key is returned as
69
73
two hexits).
70
74
</para>
...
...
@@ -75,7 +79,7 @@
75
79
</listitem>
76
80
</varlistentry>
77
81
<varlistentry>
78
-
<term><parameter>raw_output</parameter></term>
82
+
<term><parameter>binary</parameter></term>
79
83
<listitem>
80
84
<para>
81
85
When set to &true;, outputs raw binary data. &false; outputs lowercase
...
...
@@ -83,6 +87,16 @@
83
87
</para>
84
88
</listitem>
85
89
</varlistentry>
90
+
<varlistentry>
91
+
<term><parameter>options</parameter></term>
92
+
<listitem>
93
+
<para>
94
+
An array of options for the various hashing algorithms.
95
+
Currently, only the <literal>"seed"</literal> key is
96
+
supported by the MurmurHash variants.
97
+
</para>
98
+
</listitem>
99
+
</varlistentry>
86
100
</variablelist>
87
101
</para>
88
102
</refsect1>
...
...
@@ -91,7 +105,7 @@
91
105
&reftitle.returnvalues;
92
106
<para>
93
107
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
108
+
<parameter>binary</parameter> is set to &true; in which case the raw
95
109
binary representation of the derived key is returned.
96
110
</para>
97
111
</refsect1><!-- }}} -->
...
...
@@ -99,7 +113,7 @@
99
113
<refsect1 role="errors"><!-- {{{ -->
100
114
&reftitle.errors;
101
115
<para>
102
-
An <constant>E_WARNING</constant> will be raised if the algorithm is
116
+
Throws a <classname>ValueError</classname> exception if the algorithm is
103
117
unknown, the <parameter>iterations</parameter> parameter is less than or
104
118
equal to <literal>0</literal>, the <parameter>length</parameter> is less
105
119
than <literal>0</literal> or the <parameter>salt</parameter> is too long
...
...
@@ -119,6 +133,14 @@
119
133
</row>
120
134
</thead>
121
135
<tbody>
136
+
<row>
137
+
<entry>8.0.0</entry>
138
+
<entry>
139
+
Now throws a <classname>ValueError</classname> exception on error.
140
+
Previously, &false; was returned and an <constant>E_WARNING</constant>
141
+
message was emitted.
142
+
</entry>
143
+
</row>
122
144
<row>
123
145
<entry>7.2.0</entry>
124
146
<entry>Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.</entry>
...
...
@@ -138,21 +160,24 @@
138
160
<![CDATA[
139
161
<?php
140
162
$password = "password";
141
-
$iterations = 1000;
163
+
$iterations = 600000;
142
164

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);
165
+
// Generate a cryptographically secure random salt using random_bytes()
166
+
$salt = random_bytes(16);
146
167

147
168
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
148
-
echo $hash;
149
-
?>
169
+
var_dump($hash);
170
+

171
+
// for raw binary, the $length needs to be halved for equivalent results
172
+
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
173
+
var_dump(bin2hex($hash));?>
150
174
]]>
151
175
</programlisting>
152
176
&example.outputs.similar;
153
177
<screen>
154
178
<![CDATA[
155
-
120fb6cffcf8b32c43e7
179
+
string(20) "120fb6cffcf8b32c43e7"
180
+
string(20) "120fb6cffcf8b32c43e7"
156
181
]]>
157
182
</screen>
158
183
</example>
...
...
@@ -175,20 +200,14 @@ echo $hash;
175
200
&reftitle.seealso;
176
201
<para>
177
202
<simplelist>
178
-
<member><function>crypt</function></member>
179
203
<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>
204
+
<member><function>hash_hkdf</function></member>
205
+
<member><function>sodium_crypto_pwhash</function></member>
186
206
</simplelist>
187
207
</para>
188
208
</refsect1>
189
209

190
210
</refentry>
191
-

192
211
<!-- Keep this comment at the end of the file
193
212
Local variables:
194
213
mode: sgml
195
214



Translation status