reference/password/functions/password-hash.xml
c6b95280cf10b6b252683ee7d86416c4c27deb4e
...
...
@@ -12,14 +12,12 @@
12
12
<methodsynopsis>
13
13
<type>string</type><methodname>password_hash</methodname>
14
14
<methodparam><type>string</type><parameter>password</parameter></methodparam>
15
-
<methodparam><type>int</type><parameter>algo</parameter></methodparam>
16
-
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
15
+
<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
<function>password_hash</function> creates a new password hash using a strong one-way hashing
20
-
algorithm. <function>password_hash</function> is compatible with <function>crypt</function>.
21
-
Therefore, password hashes created by <function>crypt</function> can be used with
22
-
<function>password_hash</function>.
20
+
algorithm.
23
21
</para>
24
22
<simpara>
25
23
The following algorithms are currently supported:
...
...
@@ -44,7 +42,14 @@
44
42
</listitem>
45
43
<listitem>
46
44
<simpara>
47
-
<constant>PASSWORD_ARGON2I</constant> - Use the Argon2 hashing algorithm to create the hash.
45
+
<constant>PASSWORD_ARGON2I</constant> - Use the Argon2i hashing algorithm to create the hash.
46
+
This algorithm is only available if PHP has been compiled with Argon2 support.
47
+
</simpara>
48
+
</listitem>
49
+
<listitem>
50
+
<simpara>
51
+
<constant>PASSWORD_ARGON2ID</constant> - Use the Argon2id hashing algorithm to create the hash.
52
+
This algorithm is only available if PHP has been compiled with Argon2 support.
48
53
</simpara>
49
54
</listitem>
50
55
</itemizedlist>
...
...
@@ -65,14 +70,15 @@
65
70
</para>
66
71
<warning>
67
72
<para>
68
-
The salt option has been deprecated as of PHP 7.0.0. It is now
73
+
The salt option is deprecated. It is now
69
74
preferred to simply use the salt that is generated by default.
75
+
As of PHP 8.0.0, an explicitly given salt is ignored.
70
76
</para>
71
77
</warning>
72
78
</listitem>
73
79
<listitem>
74
80
<para>
75
-
<literal>cost</literal> (<type>integer</type>) - which denotes the algorithmic cost that should be used.
81
+
<literal>cost</literal> (<type>int</type>) - which denotes the algorithmic cost that should be used.
76
82
Examples of these values can be found on the <function>crypt</function> page.
77
83
</para>
78
84
<para>
...
...
@@ -83,27 +89,33 @@
83
89
</itemizedlist>
84
90
</para>
85
91
<simpara>
86
-
Supported options for <constant>PASSWORD_ARGON2I</constant>:
92
+
Supported options for <constant>PASSWORD_ARGON2I</constant>
93
+
and <constant>PASSWORD_ARGON2ID</constant>:
87
94
</simpara>
88
95
<para>
89
96
<itemizedlist>
90
97
<listitem>
91
98
<para>
92
-
<literal>memory_cost</literal> (<type>integer</type>) - Maximum memory (in bytes) that may
99
+
<literal>memory_cost</literal> (<type>int</type>) - Maximum memory (in kibibytes) that may
93
100
be used to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.
94
101
</para>
95
102
</listitem>
96
103
<listitem>
97
104
<para>
98
-
<literal>time_cost</literal> (<type>integer</type>) - Maximum amount of time it may
105
+
<literal>time_cost</literal> (<type>int</type>) - Maximum amount of time it may
99
106
take to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
100
107
</para>
101
108
</listitem>
102
109
<listitem>
103
110
<para>
104
-
<literal>threads</literal> (<type>integer</type>) - Number of threads to use for computing
111
+
<literal>threads</literal> (<type>int</type>) - Number of threads to use for computing
105
112
the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.
106
113
</para>
114
+
<warning>
115
+
<para>
116
+
Only available when PHP uses libargon2, not with libsodium implementation.
117
+
</para>
118
+
</warning>
107
119
</listitem>
108
120
</itemizedlist>
109
121
</para>
...
...
@@ -123,7 +135,7 @@
123
135
Using the <constant>PASSWORD_BCRYPT</constant> as the
124
136
algorithm, will result
125
137
in the <parameter>password</parameter> parameter being truncated to a
126
-
maximum length of 72 characters.
138
+
maximum length of 72 bytes.
127
139
</para>
128
140
</caution>
129
141
</listitem>
...
...
@@ -154,7 +166,7 @@
154
166
<refsect1 role="returnvalues">
155
167
&reftitle.returnvalues;
156
168
<para>
157
-
Returns the hashed password, &return.falseforfailure;.
169
+
Returns the hashed password.
158
170
</para>
159
171
<para>
160
172
The used algorithm, cost and salt are returned as part of the hash. Therefore,
...
...
@@ -164,6 +176,64 @@
164
176
</para>
165
177
</refsect1>
166
178

179
+
<refsect1 role="changelog">
180
+
&reftitle.changelog;
181
+
<para>
182
+
<informaltable>
183
+
<tgroup cols="2">
184
+
<thead>
185
+
<row>
186
+
<entry>&Version;</entry>
187
+
<entry>&Description;</entry>
188
+
</row>
189
+
</thead>
190
+
<tbody>
191
+
<row>
192
+
<entry>8.0.0</entry>
193
+
<entry>
194
+
<function>password_hash</function> no longer returns &false; on failure, instead a
195
+
<classname>ValueError</classname> will be thrown if the password hashing algorithm
196
+
is not valid, or an <classname>Error</classname> if the password hashing failed
197
+
for an unknown error.
198
+
</entry>
199
+
</row>
200
+
<row>
201
+
<entry>8.0.0</entry>
202
+
<entry>
203
+
The <parameter>algo</parameter> parameter is nullable now.
204
+
</entry>
205
+
</row>
206
+
<row>
207
+
<entry>7.4.0</entry>
208
+
<entry>
209
+
The <parameter>algo</parameter> parameter expects a &string; now, but still accepts
210
+
&integer;s for backward compatibility.
211
+
</entry>
212
+
</row>
213
+
<row>
214
+
<entry>7.4.0</entry>
215
+
<entry>
216
+
The sodium extension provides an alternative implementation for Argon2 passwords.
217
+
</entry>
218
+
</row>
219
+
<row>
220
+
<entry>7.3.0</entry>
221
+
<entry>
222
+
Support for Argon2id passwords using <constant>PASSWORD_ARGON2ID</constant> was added.
223
+
</entry>
224
+
</row>
225
+
<row>
226
+
<entry>7.2.0</entry>
227
+
<entry>
228
+
Support for Argon2i passwords using <constant>PASSWORD_ARGON2I</constant> was added.
229
+
</entry>
230
+
</row>
231
+
</tbody>
232
+
</tgroup>
233
+
</informaltable>
234
+
</para>
235
+
</refsect1>
236
+

167
237
<refsect1 role="examples">
168
238
&reftitle.examples;
169
239
<para>
...
...
@@ -216,35 +286,6 @@ $2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
216
286
</screen>
217
287
</example>
218
288
</para>
219
-
220
-
<para>
221
-
<example>
222
-
<title><function>password_hash</function> example setting salt manually</title>
223
-
<programlisting role="php">
224
-
<![CDATA[
225
-
<?php
226
-
/**
227
-
* Note that the salt here is randomly generated.
228
-
* Never use a static salt or one that is not randomly generated.
229
-
*
230
-
* For the VAST majority of use-cases, let password_hash generate the salt randomly for you
231
-
*/
232
-
$options = [
233
-
'cost' => 11,
234
-
'salt' => mcrypt_create_iv(22, MCRYPT_DEV_URANDOM),
235
-
];
236
-
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
237
-
?>
238
-
]]>
239
-
</programlisting>
240
-
&example.outputs.similar;
241
-
<screen>
242
-
<![CDATA[
243
-
$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
244
-
]]>
245
-
</screen>
246
-
</example>
247
-
</para>
248
289
<para>
249
290
<example>
250
291
<title><function>password_hash</function> example finding a good cost</title>
...
...
@@ -254,13 +295,13 @@ $2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
254
295
/**
255
296
* This code will benchmark your server to determine how high of a cost you can
256
297
* afford. You want to set the highest cost that you can without slowing down
257
-
* you server too much. 8-10 is a good baseline, and more is good if your servers
258
-
* are fast enough. The code below aims for ≤ 50 milliseconds stretching time,
259
-
* which is a good baseline for systems handling interactive logins.
298
+
* you server too much. 10 is a good baseline, and more is good if your servers
299
+
* are fast enough. The code below aims for ≤ 350 milliseconds stretching time,
300
+
* which is an appropriate delay for systems handling interactive logins.
260
301
*/
261
-
$timeTarget = 0.05; // 50 milliseconds
302
+
$timeTarget = 0.350; // 350 milliseconds
262
303

263
-
$cost = 8;
304
+
$cost = 10;
264
305
do {
265
306
$cost++;
266
307
$start = microtime(true);
...
...
@@ -275,25 +316,25 @@ echo "Appropriate Cost Found: " . $cost;
275
316
&example.outputs.similar;
276
317
<screen>
277
318
<![CDATA[
278
-
Appropriate Cost Found: 10
319
+
Appropriate Cost Found: 12
279
320
]]>
280
321
</screen>
281
322
</example>
282
323
</para>
283
324
<para>
284
325
<example>
285
-
<title><function>password_hash</function> example using Argon2</title>
326
+
<title><function>password_hash</function> example using Argon2i</title>
286
327
<programlisting role="php">
287
328
<![CDATA[
288
329
<?php
289
-
echo 'Argon2 hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
330
+
echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
290
331
?>
291
332
]]>
292
333
</programlisting>
293
334
&example.outputs.similar;
294
335
<screen>
295
336
<![CDATA[
296
-
Argon2 hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0
337
+
Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0
297
338
]]>
298
339
</screen>
299
340
</example>
...
...
@@ -311,13 +352,13 @@ Argon2 hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4
311
352
<para>
312
353
As noted above, providing the <literal>salt</literal> option in PHP 7.0
313
354
will generate a deprecation warning. Support for providing a salt manually
314
-
may be removed in a future PHP release.
355
+
has been removed in PHP 8.0.
315
356
</para>
316
357
</caution>
317
358
<note>
318
359
<para>
319
360
It is recommended that you test this function on your servers, and adjust the cost parameter
320
-
so that execution of the function takes less than 100 milliseconds on interactive systems.
361
+
so that execution of the function takes less than 350 milliseconds on interactive systems.
321
362
The script in the above example will help you choose a good cost value for your hardware.
322
363
</para>
323
364
</note>
...
...
@@ -350,37 +391,14 @@ Argon2 hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4
350
391
</note>
351
392
</refsect1>
352
393

353
-
<refsect1 role="changelog">
354
-
&reftitle.changelog;
355
-
<para>
356
-
<informaltable>
357
-
<tgroup cols="2">
358
-
<thead>
359
-
<row>
360
-
<entry>&Version;</entry>
361
-
<entry>&Description;</entry>
362
-
</row>
363
-
</thead>
364
-
<tbody>
365
-
<row>
366
-
<entry>7.2.0</entry>
367
-
<entry>
368
-
Support for Argon2 passwords using <constant>PASSWORD_ARGON2I</constant> was added.
369
-
</entry>
370
-
</row>
371
-
</tbody>
372
-
</tgroup>
373
-
</informaltable>
374
-
</para>
375
-
</refsect1>
376
-

377
394
<refsect1 role="seealso">
378
395
&reftitle.seealso;
379
396
<para>
380
397
<simplelist>
381
398
<member><function>password_verify</function></member>
399
+
<member><function>password_needs_rehash</function></member>
382
400
<member><function>crypt</function></member>
383
-
<member><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.password.compat;">userland implementation</link></member>
401
+
<member><function>sodium_crypto_pwhash_str</function></member>
384
402
</simplelist>
385
403
</para>
386
404
</refsect1>
387
405



Tools (Brazilian Portuguese Manual)