Changeset 59828 for trunk/src/wp-includes/pluggable.php

Timestamp:

02/17/2025 11:22:33 AM (3 months ago)

Author:

johnbillion

Message:

Security: Switch to using bcrypt for hashing user passwords and BLAKE2b for hashing application passwords and security keys.

Passwords and security keys that were saved in prior versions of WordPress will continue to work. Each user's password will be opportunistically rehashed and resaved when they next subsequently log in using a valid password.

The following new functions have been introduced:

• wp_password_needs_rehash()
• wp_fast_hash()
• wp_verify_fast_hash()

The following new filters have been introduced:

• password_needs_rehash
• wp_hash_password_algorithm
• wp_hash_password_options

Props ayeshrajans, bgermann, dd32, deadduck169, desrosj, haozi, harrym, iandunn, jammycakes, joehoyle, johnbillion, mbijon, mojorob, mslavco, my1xt, nacin, otto42, paragoninitiativeenterprises, paulkevan, rmccue, ryanhellyer, scribu, swalkinshaw, synchro, th23, timothyblynjacobs, tomdxw, westi, xknown.

Additional thanks go to the Roots team, Soatok, Calvin Alkan, and Raphael Ahrens.

Fixes #21022, #44628

File:

• trunk/src/wp-includes/pluggable.php (modified) (9 diffs)

trunk/src/wp-includes/pluggable.php

@@ -694 +694 @@
      * @param string $cookie Optional. If used, will validate contents instead of cookie's.
      * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
+     *                       Note: This does *not* default to 'auth' like other cookie functions.
      * @return int|false User ID if valid cookie, false if invalid.
      */
@@ -769 +770 @@
         }
 
-        $pass_frag = substr( $user->user_pass, 8, 4 );
+        if ( str_starts_with( $user->user_pass, '$P$' ) || str_starts_with( $user->user_pass, '$2y$' ) ) {
+            // Retain previous behaviour of phpass or vanilla bcrypt hashed passwords.
+            $pass_frag = substr( $user->user_pass, 8, 4 );
+        } else {
+            // Otherwise, use a substring from the end of the hash to avoid dealing with potentially long hash prefixes.
+            $pass_frag = substr( $user->user_pass, -4 );
+        }
 
         $key = wp_hash( $username . '|' . $pass_frag . '|' . $expiration . '|' . $token, $scheme );
@@ -870 +877 @@
         }
 
-        $pass_frag = substr( $user->user_pass, 8, 4 );
+        if ( str_starts_with( $user->user_pass, '$P$' ) || str_starts_with( $user->user_pass, '$2y$' ) ) {
+            // Retain previous behaviour of phpass or vanilla bcrypt hashed passwords.
+            $pass_frag = substr( $user->user_pass, 8, 4 );
+        } else {
+            // Otherwise, use a substring from the end of the hash to avoid dealing with potentially long hash prefixes.
+            $pass_frag = substr( $user->user_pass, -4 );
+        }
 
         $key = wp_hash( $user->user_login . '|' . $pass_frag . '|' . $expiration . '|' . $token, $scheme );
@@ -2626 +2639 @@
      *
      * @since 2.5.0
-     *
-     * @global PasswordHash $wp_hasher PHPass object.
+     * @since 6.8.0 The password is now hashed using bcrypt by default instead of phpass.
+     *
+     * @global PasswordHash $wp_hasher phpass object.
      *
      * @param string $password Plain text user password to hash.
@@ -2638 +2652 @@
         global $wp_hasher;
 
-        if ( empty( $wp_hasher ) ) {
-            require_once ABSPATH . WPINC . '/class-phpass.php';
-            // By default, use the portable hash from phpass.
-            $wp_hasher = new PasswordHash( 8, true );
-        }
-
-        return $wp_hasher->HashPassword( trim( $password ) );
+        if ( ! empty( $wp_hasher ) ) {
+            return $wp_hasher->HashPassword( trim( $password ) );
+        }
+
+        if ( strlen( $password ) > 4096 ) {
+            return '*';
+        }
+
+        /**
+         * Filters the hashing algorithm to use in the password_hash() and password_needs_rehash() functions.
+         *
+         * The default is the value of the `PASSWORD_BCRYPT` constant which means bcrypt is used.
+         *
+         * **Important:** The only password hashing algorithm that is guaranteed to be available across PHP
+         * installations is bcrypt. If you use any other algorithm you must make sure that it is available on
+         * the server. The `password_algos()` function can be used to check which hashing algorithms are available.
+         *
+         * The hashing options can be controlled via the {@see 'wp_hash_password_options'} filter.
+         *
+         * Other available constants include:
+         *
+         * - `PASSWORD_ARGON2I`
+         * - `PASSWORD_ARGON2ID`
+         * - `PASSWORD_DEFAULT`
+         *
+         * @since 6.8.0
+         *
+         * @param string $algorithm The hashing algorithm. Default is the value of the `PASSWORD_BCRYPT` constant.
+         */
+        $algorithm = apply_filters( 'wp_hash_password_algorithm', PASSWORD_BCRYPT );
+
+        /**
+         * Filters the options passed to the password_hash() and password_needs_rehash() functions.
+         *
+         * The default hashing algorithm is bcrypt, but this can be changed via the {@see 'wp_hash_password_algorithm'}
+         * filter. You must ensure that the options are appropriate for the algorithm in use.
+         *
+         * @since 6.8.0
+         *
+         * @param array $options    Array of options to pass to the password hashing functions.
+         *                          By default this is an empty array which means the default
+         *                          options will be used.
+         * @param string $algorithm The hashing algorithm in use.
+         */
+        $options = apply_filters( 'wp_hash_password_options', array(), $algorithm );
+
+        // Algorithms other than bcrypt don't need to use pre-hashing.
+        if ( PASSWORD_BCRYPT !== $algorithm ) {
+            return password_hash( $password, $algorithm, $options );
+        }
+
+        // Use SHA-384 to retain entropy from a password that's longer than 72 bytes, and a `wp-sha384` key for domain separation.
+        $password_to_hash = base64_encode( hash_hmac( 'sha384', trim( $password ), 'wp-sha384', true ) );
+
+        // Add a prefix to facilitate distinguishing vanilla bcrypt hashes.
+        return '$wp' . password_hash( $password_to_hash, $algorithm, $options );
     }
 endif;
@@ -2652 +2715 @@
      * Checks a plaintext password against a hashed password.
      *
-     * Maintains compatibility between old version and the new cookie authentication
-     * protocol using PHPass library. The $hash parameter is the encrypted password
-     * and the function compares the plain text password when encrypted similarly
-     * against the already encrypted password to see if they match.
+     * Note that this function may be used to check a value that is not a user password.
+     * A plugin may use this function to check a password of a different type, and there
+     * may not always be a user ID associated with the password.
      *
      * For integration with other applications, this function can be overwritten to
@@ -2661 +2723 @@
      *
      * @since 2.5.0
-     *
-     * @global PasswordHash $wp_hasher PHPass object used for checking the password
-     *                                 against the $hash + $password.
-     * @uses PasswordHash::CheckPassword
-     *
-     * @param string     $password Plaintext user's password.
-     * @param string     $hash     Hash of the user's password to check against.
-     * @param string|int $user_id  Optional. User ID.
+     * @since 6.8.0 Passwords in WordPress are now hashed with bcrypt by default. A
+     *              password that wasn't hashed with bcrypt will be checked with phpass.
+     *              Passwords hashed with md5 are no longer supported.
+     *
+     * @global PasswordHash $wp_hasher phpass object. Used as a fallback for verifying
+     *                                 passwords that were hashed with phpass.
+     *
+     * @param string     $password Plaintext password.
+     * @param string     $hash     Hash of the password to check against.
+     * @param string|int $user_id  Optional. ID of a user associated with the password.
      * @return bool False, if the $password does not match the hashed password.
      */
@@ -2679 +2743 @@
         global $wp_hasher;
 
-        // If the hash is still md5...
+        $check = false;
+
+        // If the hash is still md5 or otherwise truncated then invalidate it.
         if ( strlen( $hash ) <= 32 ) {
-            $check = hash_equals( $hash, md5( $password ) );
-            if ( $check && $user_id ) {
-                // Rehash using new hash.
-                wp_set_password( $password, $user_id );
-                $hash = wp_hash_password( $password );
-            }
-
             /**
-             * Filters whether the plaintext password matches the encrypted password.
+             * Filters whether the plaintext password matches the hashed password.
              *
              * @since 2.5.0
+             * @since 6.8.0 Passwords are now hashed with bcrypt by default.
+             *              Old passwords may still be hashed with phpass.
              *
              * @param bool       $check    Whether the passwords match.
              * @param string     $password The plaintext password.
              * @param string     $hash     The hashed password.
-             * @param string|int $user_id  User ID. Can be empty.
+             * @param string|int $user_id  Optional ID of a user associated with the password.
+             *                             Can be empty.
              */
             return apply_filters( 'check_password', $check, $password, $hash, $user_id );
         }
 
-        /*
-         * If the stored hash is longer than an MD5,
-         * presume the new style phpass portable hash.
-         */
-        if ( empty( $wp_hasher ) ) {
+        if ( ! empty( $wp_hasher ) ) {
+            // Check the password using the overridden hasher.
+            $check = $wp_hasher->CheckPassword( $password, $hash );
+        } elseif ( strlen( $password ) > 4096 ) {
+            $check = false;
+        } elseif ( str_starts_with( $hash, '$wp' ) ) {
+            // Check the password using the current prefixed hash.
+            $password_to_verify = base64_encode( hash_hmac( 'sha384', $password, 'wp-sha384', true ) );
+            $check              = password_verify( $password_to_verify, substr( $hash, 3 ) );
+        } elseif ( str_starts_with( $hash, '$P$' ) ) {
+            // Check the password using phpass.
             require_once ABSPATH . WPINC . '/class-phpass.php';
-            // By default, use the portable hash from phpass.
-            $wp_hasher = new PasswordHash( 8, true );
-        }
-
-        $check = $wp_hasher->CheckPassword( $password, $hash );
+            $check = ( new PasswordHash( 8, true ) )->CheckPassword( $password, $hash );
+        } else {
+            // Check the password using compat support for any non-prefixed hash.
+            $check = password_verify( $password, $hash );
+        }
 
         /** This filter is documented in wp-includes/pluggable.php */
         return apply_filters( 'check_password', $check, $password, $hash, $user_id );
+    }
+endif;
+
+if ( ! function_exists( 'wp_password_needs_rehash' ) ) :
+    /**
+     * Checks whether a password hash needs to be rehashed.
+     *
+     * Passwords are hashed with bcrypt using the default cost. A password hashed in a prior version
+     * of WordPress may still be hashed with phpass and will need to be rehashed. If the default cost
+     * or algorithm is changed in PHP or WordPress then a password hashed in a previous version will
+     * need to be rehashed.
+     *
+     * Note that, just like wp_check_password(), this function may be used to check a value that is
+     * not a user password. A plugin may use this function to check a password of a different type,
+     * and there may not always be a user ID associated with the password.
+     *
+     * @since 6.8.0
+     *
+     * @global PasswordHash $wp_hasher phpass object.
+     *
+     * @param string     $hash    Hash of a password to check.
+     * @param string|int $user_id Optional. ID of a user associated with the password.
+     * @return bool Whether the hash needs to be rehashed.
+     */
+    function wp_password_needs_rehash( $hash, $user_id = '' ) {
+        global $wp_hasher;
+
+        if ( ! empty( $wp_hasher ) ) {
+            return false;
+        }
+
+        /** This filter is documented in wp-includes/pluggable.php */
+        $algorithm = apply_filters( 'wp_hash_password_algorithm', PASSWORD_BCRYPT );
+
+        /** This filter is documented in wp-includes/pluggable.php */
+        $options = apply_filters( 'wp_hash_password_options', array(), $algorithm );
+
+        $prefixed = str_starts_with( $hash, '$wp' );
+
+        if ( ( PASSWORD_BCRYPT === $algorithm ) && ! $prefixed ) {
+            // If bcrypt is in use and the hash is not prefixed then it needs to be rehashed.
+            $needs_rehash = true;
+        } else {
+            // Otherwise check the hash minus its prefix if necessary.
+            $hash_to_check = $prefixed ? substr( $hash, 3 ) : $hash;
+            $needs_rehash  = password_needs_rehash( $hash_to_check, $algorithm, $options );
+        }
+
+        /**
+         * Filters whether the password hash needs to be rehashed.
+         *
+         * @since 6.8.0
+         *
+         * @param bool       $needs_rehash Whether the password hash needs to be rehashed.
+         * @param string     $hash         The password hash.
+         * @param string|int $user_id      Optional. ID of a user associated with the password.
+         */
+        return apply_filters( 'password_needs_rehash', $needs_rehash, $hash, $user_id );
     }
 endif;
@@ -2866 +2992 @@
      *
      * @since 2.5.0
+     * @since 6.8.0 The password is now hashed using bcrypt by default instead of phpass.
      *
      * @global wpdb $wpdb WordPress database abstraction object.