From a2a1394d23f50e2a2a2e9302bd444e38d51ee195 Mon Sep 17 00:00:00 2001
From: Anthony Ferrara <ircmaxell@php.net>
Date: Thu, 20 Jun 2013 20:27:59 +0000
Subject: [PATCH] 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
---
 .../password/functions/password-hash.xml      | 140 +++++++++++++++++-
 1 file changed, 139 insertions(+), 1 deletion(-)

diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml
index 24bd7678d3..44ebb5f58e 100644
--- a/reference/password/functions/password-hash.xml
+++ b/reference/password/functions/password-hash.xml
@@ -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">