mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Update password hash documentation to better describe the salt and cost parameters, improve the examples and describe the algorithm processes.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330566 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Anthony Ferrara
parent
190186c998
commit
a2a1394d23
1 changed files with 139 additions and 1 deletions
|
|
@ -16,7 +16,31 @@
|
|||
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
<function>password_hash</function> creates a new password hash.
|
||||
<function>password_hash</function> creates a new password hash using a strong one-way hashing
|
||||
algorithm.
|
||||
</para>
|
||||
<simpara>
|
||||
The following algorithms are currently supported:
|
||||
</simpara>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<constant>PASSWORD_DEFAULT</constant> - Use the bcrypt algorithm (default as of PHP 5.5.0).
|
||||
Note that this constant is designed to change over time as new and stronger algorithms are added
|
||||
to PHP. For that reason, the length of the result from using this identifier can change over
|
||||
time. Therefore, it is recommended to store the result in a database column that can expand
|
||||
beyond 60 characters (255 characters would be a good choice).
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<constant>PASSWORD_BCRYPT</constant> - Use the <constant>CRYPT_BLOWFISH</constant> algorithm to
|
||||
create the hash. This will produce a standard <function>crypt</function> compatible hash using
|
||||
the "$2y$" identifier. The result will always be a 60 character string, &return.falseforfailure;.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -88,6 +112,120 @@ $2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq
|
|||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title><function>password_hash</function> example setting cost manually</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$options = [
|
||||
'cost' => 12,
|
||||
];
|
||||
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options)."\n";
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>password_hash</function> example setting salt manually</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$options = [
|
||||
'cost' => 11,
|
||||
'salt' => mcrypt_create_iv(22, MCRYPT_DEV_URANDOM),
|
||||
];
|
||||
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options)."\n";
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title><function>password_hash</function> example finding a good cost</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// The number of seconds to target as a minumum
|
||||
$timeTarget = 0.2;
|
||||
|
||||
$cost = 9;
|
||||
do {
|
||||
$cost++;
|
||||
$start = microtime(true);
|
||||
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
|
||||
$end = microtime(true);
|
||||
} while (($end - $start) < 0.2);
|
||||
|
||||
echo "Appropriate Cost Found: " . $cost . "\n";
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
Appropriate Cost Found: 11
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="notes">
|
||||
&reftitle.notes;
|
||||
<caution>
|
||||
<para>
|
||||
It is strongly recommended that you do not generate your own salt for this function.
|
||||
It will create a secure salt automatically for you if you do not specify one.
|
||||
</para>
|
||||
</caution>
|
||||
<note>
|
||||
<para>
|
||||
It is recommended that you should test this function on your servers, and adjust the cost
|
||||
parameter so that execution of the function takes approximately 0.1 to 0.5 seconds. The script
|
||||
in the above example will help you choose a good cost value for your hardware.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<simpara>
|
||||
Updates to supported algorithms by this function (or changes to the default one) must follow
|
||||
the follwoing rules:
|
||||
</simpara>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<simpara>Any new algorithm must be in core for at least 1 full release of PHP prior to becoming
|
||||
default. So if, for example, a new algorithm is added in 5.5.5, it would not be eligible for
|
||||
default until 5.7 (since 5.6 would be the first full release). But if a different algorithm was
|
||||
added in 5.6.0, it would also be eligible for default at 5.7.0.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
The default should only change on a full release (5.6.0, 6.0.0, etc) and not on a revision release.
|
||||
The only exception to this is in an emergency when a critical security flaw is found in the current
|
||||
default.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
|
|
|
|||
Loading…
Reference in a new issue