reference/strings/functions/crypt.xml
60b29fbe11384d5233398d70fdc74e9078fe32ad
...
...
@@ -6,30 +6,34 @@
6
6
<refpurpose>One-way string hashing</refpurpose>
7
7
</refnamediv>
8
8
9
+
<refsynopsisdiv>
10
+
&note.not-bin-safe;
11
+
</refsynopsisdiv>
12
+
9
13
<refsect1 role="description">
10
14
&reftitle.description;
11
15
<methodsynopsis>
12
16
<type>string</type><methodname>crypt</methodname>
13
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>salt</parameter></methodparam>
17
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
18
+
<methodparam><type>string</type><parameter>salt</parameter></methodparam>
15
19
</methodsynopsis>
16
20
<para>
17
21
<function>crypt</function> will return a hashed string using the
18
22
standard Unix <abbrev>DES</abbrev>-based algorithm or
19
-
alternative algorithms that may be available on the system.
23
+
alternative algorithms. <function>password_verify</function> is
24
+
compatible with <function>crypt</function>. Therefore, password
25
+
hashes created by <function>crypt</function> can be used with
26
+
<function>password_verify</function>.
20
27
</para>
21
28
<para>
22
-
The <parameter>salt</parameter> parameter is optional. However, <function>crypt</function> creates a weak password without the <parameter>salt</parameter>. PHP 5.6 or later raise an E_NOTICE error without it. Make sure to specify a strong enough salt for better security.
29
+
Prior to PHP 8.0.0, the <parameter>salt</parameter> parameter was optional. However, <function>crypt</function> creates a weak hash without the <parameter>salt</parameter>, and raises an <constant>E_NOTICE</constant> error without it. Make sure to specify a strong enough salt for better security.
23
30
</para>
24
31
<para>
25
32
<function>password_hash</function> uses a strong hash, generates a strong salt, and applies proper rounds automatically. <function>password_hash</function> is a simple <function>crypt</function> wrapper and compatible with existing password hashes. Use of <function>password_hash</function> is encouraged.
26
33
</para>
27
34
<para>
28
-
Some operating systems support more than one type of hash. In
29
-
fact, sometimes the standard DES-based algorithm is replaced by an
30
-
MD5-based algorithm. The hash type is triggered by the salt argument.
31
-
Prior to 5.3, PHP would determine the available algorithms at install-time
32
-
based on the system's crypt(). If no salt is provided, PHP will
35
+
The hash type is triggered by the salt argument.
36
+
If no salt is provided, PHP will
33
37
auto-generate either a standard two character (DES) salt, or a twelve
34
38
character (MD5), depending on the availability of MD5 crypt(). PHP sets a
35
39
constant named <constant>CRYPT_SALT_LENGTH</constant> which indicates the
...
...
@@ -38,14 +42,12 @@
38
42
<para>
39
43
The standard DES-based <function>crypt</function> returns the
40
44
salt as the first two characters of the output. It also only uses the
41
-
first eight characters of <parameter>str</parameter>, so longer strings
45
+
first eight characters of <parameter>string</parameter>, so longer strings
42
46
that start with the same eight characters will generate the same result
43
47
(when the same salt is used).
44
48
</para>
45
49
<simpara>
46
-
On systems where the crypt() function supports multiple
47
-
hash types, the following constants are set to 0 or 1
48
-
depending on whether the given type is available:
50
+
The following hash types are supported:
49
51
</simpara>
50
52
<itemizedlist>
51
53
<listitem>
...
...
@@ -58,10 +60,10 @@
58
60
<listitem>
59
61
<simpara>
60
62
<constant>CRYPT_EXT_DES</constant> - Extended DES-based hash. The "salt" is a
61
-
9-character string consisting of an underscore followed by 4 bytes of iteration count and
62
-
4 bytes of salt. These are encoded as printable characters, 6 bits per character, least
63
-
significant character first. The values 0 to 63 are encoded as "./0-9A-Za-z". Using invalid
64
-
characters in the salt will cause crypt() to fail.
63
+
9-character string consisting of an underscore followed by 4 characters of iteration count
64
+
and 4 characters of salt. Each of these 4-character strings encode 24 bits, least significant
65
+
character first. The values <literal>0</literal> to <literal>63</literal> are encoded as
66
+
<literal>./0-9A-Za-z</literal>. Using invalid characters in the salt will cause crypt() to fail.
65
67
</simpara>
66
68
</listitem>
67
69
<listitem>
...
...
@@ -77,14 +79,10 @@
77
79
22 characters from the alphabet "./0-9A-Za-z". Using characters outside of
78
80
this range in the salt will cause crypt() to return a zero-length string.
79
81
The two digit cost parameter is the base-2 logarithm of the iteration
80
-
count for the underlying Blowfish-based hashing algorithmeter and must be
82
+
count for the underlying Blowfish-based hashing algorithm and must be
81
83
in range 04-31, values outside this range will cause crypt() to fail.
82
-
Versions of PHP before 5.3.7 only support "$2a$" as the salt prefix: PHP
83
-
5.3.7 introduced the new prefixes to fix a security weakness in the
84
-
Blowfish implementation. Please refer to
85
-
<link xlink:href="&url.crypt.blowfish;">this document</link> for full
86
-
details of the security fix, but to summarise, developers targeting only
87
-
PHP 5.3.7 and later should use "$2y$" in preference to "$2a$".
84
+
"$2x$" hashes are potentially weak; "$2a$" hashes are compatible and
85
+
mitigate this weakness. For new hashes, "$2y$" should be used.
88
86
</simpara>
89
87
</listitem>
90
88
<listitem>
...
...
@@ -108,12 +106,6 @@
108
106
</simpara>
109
107
</listitem>
110
108
</itemizedlist>
111
-
<note>
112
-
<para>
113
-
As of PHP 5.3.0, PHP contains its own implementation and will use that
114
-
if the system lacks of support for one or more of the algorithms.
115
-
</para>
116
-
</note>
117
109
</refsect1>
118
110
119
111
<refsect1 role="parameters">
...
...
@@ -121,7 +113,7 @@
121
113
<para>
122
114
<variablelist>
123
115
<varlistentry>
124
-
<term><parameter>str</parameter></term>
116
+
<term><parameter>string</parameter></term>
125
117
<listitem>
126
118
<para>
127
119
The string to be hashed.
...
...
@@ -129,8 +121,8 @@
129
121
<caution>
130
122
<para>
131
123
Using the <constant>CRYPT_BLOWFISH</constant> algorithm, will result
132
-
in the <parameter>str</parameter> parameter being truncated to a
133
-
maximum length of 72 characters.
124
+
in the <parameter>string</parameter> parameter being truncated to a
125
+
maximum length of 72 bytes.
134
126
</para>
135
127
</caution>
136
128
</listitem>
...
...
@@ -139,7 +131,7 @@
139
131
<term><parameter>salt</parameter></term>
140
132
<listitem>
141
133
<para>
142
-
An optional salt string to base the hashing on. If not provided, the
134
+
A salt string to base the hashing on. If not provided, the
143
135
behaviour is defined by the algorithm implementation and can lead to
144
136
unexpected results.
145
137
</para>
...
...
@@ -159,7 +151,7 @@
159
151
<simpara>
160
152
When validating passwords, a string comparison function that isn't
161
153
vulnerable to timing attacks should be used to compare the output of
162
-
<function>crypt</function> to the previously known hash. PHP 5.6 onwards
154
+
<function>crypt</function> to the previously known hash. PHP
163
155
provides <function>hash_equals</function> for this purpose.
164
156
</simpara>
165
157
</warning>
...
...
@@ -167,73 +159,24 @@
167
159
168
160
<refsect1 role="changelog">
169
161
&reftitle.changelog;
170
-
<para>
171
-
<informaltable>
172
-
<tgroup cols="2">
173
-
<thead>
174
-
<row>
175
-
<entry>&Version;</entry>
176
-
<entry>&Description;</entry>
177
-
</row>
178
-
</thead>
179
-
<tbody>
180
-
<row>
181
-
<entry>5.6.5</entry>
182
-
<entry>
183
-
When the failure string "*0" is given as the
184
-
<parameter>salt</parameter>, "*1" will now be returned for consistency
185
-
with other crypt implementations. Prior to this version, PHP 5.6 would
186
-
incorrectly return a DES hash.
187
-
</entry>
188
-
</row>
189
-
<row>
190
-
<entry>5.6.0</entry>
191
-
<entry>
192
-
Raise E_NOTICE security warning if <parameter>salt</parameter> is omitted.
193
-
</entry>
194
-
</row>
195
-
<row>
196
-
<entry>5.5.21</entry>
197
-
<entry>
198
-
When the failure string "*0" is given as the
199
-
<parameter>salt</parameter>, "*1" will now be returned for consistency
200
-
with other crypt implementations. Prior to this version, PHP 5.5 (and
201
-
earlier branches) would incorrectly return a DES hash.
202
-
</entry>
203
-
</row>
204
-
<row>
205
-
<entry>5.3.7</entry>
206
-
<entry>
207
-
Added <literal>$2x$</literal> and <literal>$2y$</literal> Blowfish
208
-
modes to deal with potential high-bit attacks.
209
-
</entry>
210
-
</row>
211
-
<row>
212
-
<entry>5.3.2</entry>
213
-
<entry>
214
-
Added SHA-256 and SHA-512 crypt based on Ulrich Drepper's
215
-
<link xlink:href="&url.crypt.sha;">implementation</link>.
216
-
</entry>
217
-
</row>
218
-
<row>
219
-
<entry>5.3.2</entry>
220
-
<entry>
221
-
Fixed Blowfish behaviour on invalid rounds to return "failure"
222
-
string ("*0" or "*1"), instead of falling back to DES.
223
-
</entry>
224
-
</row>
225
-
<row>
226
-
<entry>5.3.0</entry>
227
-
<entry>
228
-
PHP now contains its own implementation for the MD5 crypt, Standard DES,
229
-
Extended DES and the Blowfish algorithms and will use that if the system
230
-
lacks of support for one or more of the algorithms.
231
-
</entry>
232
-
</row>
233
-
</tbody>
234
-
</tgroup>
235
-
</informaltable>
236
-
</para>
162
+
<informaltable>
163
+
<tgroup cols="2">
164
+
<thead>
165
+
<row>
166
+
<entry>&Version;</entry>
167
+
<entry>&Description;</entry>
168
+
</row>
169
+
</thead>
170
+
<tbody>
171
+
<row>
172
+
<entry>8.0.0</entry>
173
+
<entry>
174
+
The <parameter>salt</parameter> is no longer optional.
175
+
</entry>
176
+
</row>
177
+
</tbody>
178
+
</tgroup>
179
+
</informaltable>
237
180
</refsect1>
238
181

239
182
<refsect1 role="examples">
...
...
@@ -244,12 +187,10 @@
244
187
<programlisting role="php">
245
188
<![CDATA[
246
189
<?php
247
-
$hashed_password = crypt('mypassword'); // let the salt be automatically generated
190
+
$user_input = 'rasmuslerdorf';
191
+
$hashed_password = '$6$rounds=1000000$NJy4rIPjpOaU$0ACEYGg/aKCY3v8O8AfyiO7CTfZQ8/W231Qfh2tRLmfdvFD6XfHk12u6hMr9cYIA4hnpjLNSTRtUwYr9km9Ij/';
248
192

249
-
/* You should pass the entire results of crypt() as the salt for comparing a
250
-
password, to avoid problems when different hashing algorithms are used. (As
251
-
it says above, standard DES-based password hashing uses a 2-character salt,
252
-
but MD5-based hashing uses 12.) */
193
+
// Validate an existing crypt() hash in a way that is compatible with non-PHP software.
253
194
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
254
195
echo "Password verified!";
255
196
}
...
...
@@ -258,70 +199,6 @@ if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
258
199
</programlisting>
259
200
</example>
260
201
</para>
261
-
<para>
262
-
<example>
263
-
<title>Using <function>crypt</function> with htpasswd</title>
264
-
<programlisting role="php">
265
-
<![CDATA[
266
-
<?php
267
-
// Set the password
268
-
$password = 'mypassword';
269
-

270
-
// Get the hash, letting the salt be automatically generated
271
-
$hash = crypt($password);
272
-
?>
273
-
]]>
274
-
</programlisting>
275
-
</example>
276
-
</para>
277
-
<para>
278
-
<example>
279
-
<title>Using <function>crypt</function> with different hash types</title>
280
-
<programlisting role="php">
281
-
<![CDATA[
282
-
<?php
283
-
/* These salts are examples only, and should not be used verbatim in your code.
284
-
You should generate a distinct, correctly-formatted salt for each password.
285
-
*/
286
-
if (CRYPT_STD_DES == 1) {
287
-
echo 'Standard DES: ' . crypt('rasmuslerdorf', 'rl') . "\n";
288
-
}
289
-

290
-
if (CRYPT_EXT_DES == 1) {
291
-
echo 'Extended DES: ' . crypt('rasmuslerdorf', '_J9..rasm') . "\n";
292
-
}
293
-

294
-
if (CRYPT_MD5 == 1) {
295
-
echo 'MD5: ' . crypt('rasmuslerdorf', '$1$rasmusle$') . "\n";
296
-
}
297
-

298
-
if (CRYPT_BLOWFISH == 1) {
299
-
echo 'Blowfish: ' . crypt('rasmuslerdorf', '$2a$07$usesomesillystringforsalt$') . "\n";
300
-
}
301
-

302
-
if (CRYPT_SHA256 == 1) {
303
-
echo 'SHA-256: ' . crypt('rasmuslerdorf', '$5$rounds=5000$usesomesillystringforsalt$') . "\n";
304
-
}
305
-

306
-
if (CRYPT_SHA512 == 1) {
307
-
echo 'SHA-512: ' . crypt('rasmuslerdorf', '$6$rounds=5000$usesomesillystringforsalt$') . "\n";
308
-
}
309
-
?>
310
-
]]>
311
-
</programlisting>
312
-
&example.outputs.similar;
313
-
<screen>
314
-
<![CDATA[
315
-
Standard DES: rl.3StKT.4T8M
316
-
Extended DES: _J9..rasmBYk8r9AiWNc
317
-
MD5: $1$rasmusle$rISCgZzpwk3UhDidwXvin0
318
-
Blowfish: $2a$07$usesomesillystringfore2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi
319
-
SHA-256: $5$rounds=5000$usesomesillystri$KqJWpanXZHKq2BOB43TSaYhEWsQ1Lr5QNyPCDH/Tp.6
320
-
SHA-512: $6$rounds=5000$usesomesillystri$D4IrlXatmP7rx3P3InaxBeoomnAihCKRVQP22JZ6EY47Wc6BkroIuUUBOov1i.S5KPgErtP/EN5mcO.ChWQW21
321
-
]]>
322
-
</screen>
323
-
</example>
324
-
</para>
325
202
</refsect1>
326
203
327
204
<refsect1 role="notes">
...
...
@@ -340,15 +217,12 @@ SHA-512: $6$rounds=5000$usesomesillystri$D4IrlXatmP7rx3P3InaxBeoomnAihCKRVQ
340
217
<simplelist>
341
218
<member><function>hash_equals</function></member>
342
219
<member><function>password_hash</function></member>
343
-
<member><function>md5</function></member>
344
-
<member>The <link linkend="ref.mcrypt">Mcrypt</link> extension</member>
345
220
<member>The Unix man page for your crypt function for more information</member>
346
221
</simplelist>
347
222
</para>
348
223
</refsect1>
349
224
350
225
</refentry>
351
-

352
226
<!-- Keep this comment at the end of the file
353
227
Local variables:
354
228
mode: sgml
355
229



Tools (Spanish Manual)