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 2013-06-20 20:27:59 +00:00
parent 190186c998
commit a2a1394d23

View file

@ -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">