Changeset 59828 for trunk/src/wp-includes/functions.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/functions.php (modified) (1 diff)

trunk/src/wp-includes/functions.php

@@ -9115 +9115 @@
     return in_array( $mime_type, $heic_mime_types, true );
 }
+
+/**
+ * Returns a cryptographically secure hash of a message using a fast generic hash function.
+ *
+ * Use the wp_verify_fast_hash() function to verify the hash.
+ *
+ * This function does not salt the value prior to being hashed, therefore input to this function must originate from
+ * a random generator with sufficiently high entropy, preferably greater than 128 bits. This function is used internally
+ * in WordPress to hash security keys and application passwords which are generated with high entropy.
+ *
+ * Important:
+ *
+ *  - This function must not be used for hashing user-generated passwords. Use wp_hash_password() for that.
+ *  - This function must not be used for hashing other low-entropy input. Use wp_hash() for that.
+ *
+ * The BLAKE2b algorithm is used by Sodium to hash the message.
+ *
+ * @since 6.8.0
+ *
+ * @throws TypeError Thrown by Sodium if the message is not a string.
+ *
+ * @param string $message The message to hash.
+ * @return string The hash of the message.
+ */
+function wp_fast_hash(
+    #[\SensitiveParameter]
+    string $message
+): string {
+    return '$generic$' . sodium_bin2hex( sodium_crypto_generichash( $message ) );
+}
+
+/**
+ * Checks whether a plaintext message matches the hashed value. Used to verify values hashed via wp_fast_hash().
+ *
+ * The function uses Sodium to hash the message and compare it to the hashed value. If the hash is not a generic hash,
+ * the hash is treated as a phpass portable hash in order to provide backward compatibility for application passwords
+ * which were hashed using phpass prior to WordPress 6.8.0.
+ *
+ * @since 6.8.0
+ *
+ * @throws TypeError Thrown by Sodium if the message is not a string.
+ *
+ * @param string $message The plaintext message.
+ * @param string $hash    Hash of the message to check against.
+ * @return bool Whether the message matches the hashed message.
+ */
+function wp_verify_fast_hash(
+    #[\SensitiveParameter]
+    string $message,
+    string $hash
+): bool {
+    if ( ! str_starts_with( $hash, '$generic$' ) ) {
+        // Back-compat for old phpass hashes.
+        require_once ABSPATH . WPINC . '/class-phpass.php';
+        return ( new PasswordHash( 8, true ) )->CheckPassword( $message, $hash );
+    }
+
+    return hash_equals( $hash, wp_fast_hash( $message ) );
+}