reference/hash/functions/hash-pbkdf2.xml
db22a7cfcbc3af221f67e228336ac3e2d62aaf2c
db22a7cfcbc3af221f67e228336ac3e2d62aaf2c
...
...
@@ -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
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>
19
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
20
20
</methodsynopsis>
21
21
</refsect1>
22
22
...
...
@@ -62,9 +62,9 @@
62
62
<term><parameter>length</parameter></term>
63
63
<listitem>
64
64
<para>
65
-
The length of the output string. If <parameter>raw_output</parameter>
65
+
The length of the output string. If <parameter>binary</parameter>
66
66
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
67
+
<parameter>binary</parameter> is &false; this corresponds to twice the
68
68
byte-length of the derived key (as every byte of the key is returned as
69
69
two hexits).
70
70
</para>
...
...
@@ -75,7 +75,7 @@
75
75
</listitem>
76
76
</varlistentry>
77
77
<varlistentry>
78
-
<term><parameter>raw_output</parameter></term>
78
+
<term><parameter>binary</parameter></term>
79
79
<listitem>
80
80
<para>
81
81
When set to &true;, outputs raw binary data. &false; outputs lowercase
...
...
@@ -83,6 +83,16 @@
83
83
</para>
84
84
</listitem>
85
85
</varlistentry>
86
+
<varlistentry>
87
+
<term><parameter>options</parameter></term>
88
+
<listitem>
89
+
<para>
90
+
An array of options for the various hashing algorithms.
91
+
Currently, only the <literal>"seed"</literal> key is
92
+
supported by the MurmurHash variants.
93
+
</para>
94
+
</listitem>
95
+
</varlistentry>
86
96
</variablelist>
87
97
</para>
88
98
</refsect1>
...
...
@@ -91,7 +101,7 @@
91
101
&reftitle.returnvalues;
92
102
<para>
93
103
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
104
+
<parameter>binary</parameter> is set to &true; in which case the raw
95
105
binary representation of the derived key is returned.
96
106
</para>
97
107
</refsect1><!-- }}} -->
...
...
@@ -99,7 +109,7 @@
99
109
<refsect1 role="errors"><!-- {{{ -->
100
110
&reftitle.errors;
101
111
<para>
102
-
An <constant>E_WARNING</constant> will be raised if the algorithm is
112
+
Throws a <classname>ValueError</classname> exception if the algorithm is
103
113
unknown, the <parameter>iterations</parameter> parameter is less than or
104
114
equal to <literal>0</literal>, the <parameter>length</parameter> is less
105
115
than <literal>0</literal> or the <parameter>salt</parameter> is too long
...
...
@@ -107,6 +117,36 @@
107
117
</para>
108
118
</refsect1><!-- }}} -->
109
119
120
+
<refsect1 role="changelog">
121
+
&reftitle.changelog;
122
+
<para>
123
+
<informaltable>
124
+
<tgroup cols="2">
125
+
<thead>
126
+
<row>
127
+
<entry>&Version;</entry>
128
+
<entry>&Description;</entry>
129
+
</row>
130
+
</thead>
131
+
<tbody>
132
+
<row>
133
+
<entry>8.0.0</entry>
134
+
<entry>
135
+
Now throws a <classname>ValueError</classname> exception on error.
136
+
Previously, &false; was returned and an <constant>E_WARNING</constant>
137
+
message was emitted.
138
+
</entry>
139
+
</row>
140
+
<row>
141
+
<entry>7.2.0</entry>
142
+
<entry>Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.</entry>
143
+
</row>
144
+
</tbody>
145
+
</tgroup>
146
+
</informaltable>
147
+
</para>
148
+
</refsect1>
149
+
110
150
<refsect1 role="examples">
111
151
&reftitle.examples;
112
152
<para>
...
...
@@ -116,21 +156,24 @@
116
156
<![CDATA[
117
157
<?php
118
158
$password = "password";
119
-
$iterations = 1000;
159
+
$iterations = 600000;
120
160
121
-
// Generate a random IV using mcrypt_create_iv(),
122
-
// openssl_random_pseudo_bytes() or another suitable source of randomness
123
-
$salt = mcrypt_create_iv(16, MCRYPT_DEV_URANDOM);
161
+
// Generate a cryptographically secure random salt using random_bytes()
162
+
$salt = random_bytes(16);
124
163
125
164
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
126
-
echo $hash;
127
-
?>
165
+
var_dump($hash);
166
+
167
+
// for raw binary, the $length needs to be halved for equivalent results
168
+
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
169
+
var_dump(bin2hex($hash));?>
128
170
]]>
129
171
</programlisting>
130
172
&example.outputs.similar;
131
173
<screen>
132
174
<![CDATA[
133
-
120fb6cffcf8b32c43e7
175
+
string(20) "120fb6cffcf8b32c43e7"
176
+
string(20) "120fb6cffcf8b32c43e7"
134
177
]]>
135
178
</screen>
136
179
</example>
...
...
@@ -153,19 +196,14 @@ echo $hash;
153
196
&reftitle.seealso;
154
197
<para>
155
198
<simplelist>
156
-
<member><function>crypt</function></member>
157
199
<member><function>password_hash</function></member>
158
-
<member><function>hash</function></member>
159
-
<member><function>hash_algos</function></member>
160
-
<member><function>hash_init</function></member>
161
-
<member><function>hash_hmac</function></member>
162
-
<member><function>hash_hmac_file</function></member>
200
+
<member><function>hash_hkdf</function></member>
201
+
<member><function>sodium_crypto_pwhash</function></member>
163
202
</simplelist>
164
203
</para>
165
204
</refsect1>
166
205
167
206
</refentry>
168
-
169
207
<!-- Keep this comment at the end of the file
170
208
Local variables:
171
209
mode: sgml
172
210