From a737565000dfdc71ee66db77760b556a705d53d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim=20D=C3=BCsterhus?= <tim@bastelstu.be>
Date: Sun, 9 Feb 2025 16:41:06 +0100
Subject: [PATCH 1/2] password_hash: Update for PHP 8.4

This updates the `password_hash()` documentation for the updated default cost
of bcrypt in PHP 8.4. It also performs some general cleanup.
---
 .../password/functions/password-hash.xml      | 35 ++++++++++---------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml
index b6a63da651f2..5bf115ce181d 100644
--- a/reference/password/functions/password-hash.xml
+++ b/reference/password/functions/password-hash.xml
@@ -34,9 +34,9 @@
     </listitem>
     <listitem>
      <simpara>
-      <constant>PASSWORD_BCRYPT</constant> - Use the <constant>CRYPT_BLOWFISH</constant> algorithm to
+      <constant>PASSWORD_BCRYPT</constant> - Use the bcrypt 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;.
+      the <literal>$2y$</literal> identifier. The result will always be a 60 character string, &return.falseforfailure;.
      </simpara>
     </listitem>
     <listitem>
@@ -81,8 +81,8 @@
       Examples of these values can be found on the <function>crypt</function> page.
      </para>
      <para>
-      If omitted, a default value of <literal>10</literal> will be used. This is a good
-      baseline cost, but you may want to consider increasing it depending on your hardware.
+      If omitted, a default value of <literal>12</literal> will be used. This is a good
+      baseline cost, but you may want to consider adjusting it depending on your hardware.
      </para>
     </listitem>
    </itemizedlist>
@@ -153,10 +153,6 @@
      <para>
       &password.parameter.options;
      </para>
-     <para>
-      If omitted, a random salt will be created and the default cost will be
-      used.
-     </para>
     </listitem>
    </varlistentry>
   </variablelist>
@@ -187,6 +183,14 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.4.0</entry>
+       <entry>
+        The default value of the <literal>cost</literal> option of the
+        <constant>PASSWORD_BCRYPT</constant> algorithm was increased from
+        <literal>10</literal> to <literal>12</literal>.
+       </entry>
+      </row>
       <row>
        <entry>8.3.0</entry>
        <entry>
@@ -265,7 +269,7 @@ echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
     &example.outputs.similar;
     <screen>
 <![CDATA[
-$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
+$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.
 ]]>
     </screen>
    </example>
@@ -277,11 +281,10 @@ $2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
 <![CDATA[
 <?php
 /**
- * In this case, we want to increase the default cost for BCRYPT to 12.
- * Note that we also switched to BCRYPT, which will always be 60 characters.
+ * In this case, we want to increase the cost for bcrypt to 13.
  */
 $options = [
-    'cost' => 12,
+    'cost' => 13,
 ];
 echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
 ?>
@@ -290,7 +293,7 @@ echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
     &example.outputs.similar;
     <screen>
 <![CDATA[
-$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
+$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi
 ]]>
     </screen>
    </example>
@@ -304,13 +307,13 @@ $2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
 /**
  * This code will benchmark your server to determine how high of a cost you can
  * afford. You want to set the highest cost that you can without slowing down
- * you server too much. 10 is a good baseline, and more is good if your servers
+ * you server too much. 11 is a good baseline, and more is good if your servers
  * are fast enough. The code below aims for ≤ 350 milliseconds stretching time,
  * which is an appropriate delay for systems handling interactive logins.
  */
 $timeTarget = 0.350; // 350 milliseconds
 
-$cost = 10;
+$cost = 11;
 do {
     $cost++;
     $start = microtime(true);
@@ -325,7 +328,7 @@ echo "Appropriate Cost Found: " . $cost;
     &example.outputs.similar;
     <screen>
 <![CDATA[
-Appropriate Cost Found: 12
+Appropriate Cost Found: 13
 ]]>
     </screen>
    </example>

From d379dd55e800fba6fcca8a22d850002d65eb92e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim=20D=C3=BCsterhus?= <tim@bastelstu.be>
Date: Sun, 9 Feb 2025 16:45:25 +0100
Subject: [PATCH 2/2] password_*(): Sync with `password_hash()`

---
 reference/password/functions/password-needs-rehash.xml | 4 ++--
 reference/password/functions/password-verify.xml       | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/password/functions/password-needs-rehash.xml b/reference/password/functions/password-needs-rehash.xml
index 21eaf033c2f1..c7e7d5ab9ac2 100644
--- a/reference/password/functions/password-needs-rehash.xml
+++ b/reference/password/functions/password-needs-rehash.xml
@@ -96,11 +96,11 @@
 <?php
 
 $password = 'rasmuslerdorf';
-$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';
+$hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';
 
 $algorithm = PASSWORD_BCRYPT;
 // bcrypt's cost parameter can change over time as hardware improves
-$options = ['cost' => 12];
+$options = ['cost' => 13];
 
 // Verify stored hash against plain-text password
 if (password_verify($password, $hash)) {
diff --git a/reference/password/functions/password-verify.xml b/reference/password/functions/password-verify.xml
index 44c898da9520..6d4165a10b25 100644
--- a/reference/password/functions/password-verify.xml
+++ b/reference/password/functions/password-verify.xml
@@ -72,7 +72,7 @@
 <![CDATA[
 <?php
 // See the password_hash() example to see where this came from.
-$hash = '$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a';
+$hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';
 
 if (password_verify('rasmuslerdorf', $hash)) {
     echo 'Password is valid!';