wp_hash_password()
云策文档标注
概述
wp_hash_password() 是 WordPress 中用于将明文密码哈希化的核心函数。它支持通过插件或全局变量 $wp_hasher 自定义哈希算法，默认使用 bcrypt 算法，并提供了过滤钩子以调整哈希选项。
关键要点
- 函数功能：将明文密码转换为哈希字符串，用于用户密码安全存储。
- 默认算法：从 WordPress 6.8.0 起，默认使用 bcrypt 算法替代旧版 phpass，通过 password_hash() 实现。
- 可扩展性：可通过设置全局 $wp_hasher 或使用插件覆盖函数，以集成其他密码哈希算法（如 Blowfish 或扩展 DES）。
- 过滤钩子：提供 wp_hash_password_algorithm 和 wp_hash_password_options 过滤器，允许开发者自定义哈希算法和选项。
- 安全处理：对超长密码（超过 4096 字符）返回 '*' 以防止攻击，并使用 SHA-384 和域分离密钥处理 bcrypt 算法的输入。
- 相关函数：被 wp_set_password()、wp_update_user() 和 wp_insert_user() 调用，用于用户密码更新和插入操作。
代码示例
// 使用 Blowfish 或扩展 DES 替代 MD5 进行哈希（需通过 $wp_hasher 设置）
$wp_hasher = new PasswordHash(16, FALSE);
$hashedPassword = wp_hash_password($password);
// 比较哈希密码与明文（使用 CheckPassword 函数，注意非 wp_hash_password 直接功能）
if (CheckPassword($plain_password, $password_hashed)) {
echo "YES, Matched";
} else {
echo "No, Wrong Password";
}注意事项
- 算法可用性：bcrypt 是唯一保证跨 PHP 安装可用的算法，使用其他算法（如 Argon2）需确保服务器支持。
- 版本变化：WordPress 6.8.0 将默认算法从 phpass 改为 bcrypt，影响向后兼容性，开发者需检查现有代码。
- 插件覆盖：如果插件重定义了此函数，将优先使用插件版本，否则使用核心实现。
原文内容
Creates a hash of a plain text password.
Description
For integration with other applications, this function can be overwritten to instead use the other package password hashing algorithm.
Parameters
$passwordstringrequired-
Plain text user password to hash.
Source
function wp_hash_password(
#[SensitiveParameter]
$password
) {
global $wp_hasher;
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 'wp_hash_password_options' filter.
*
* Other available constants include:
*
* - `PASSWORD_ARGON2I`
* - `PASSWORD_ARGON2ID`
* - `PASSWORD_DEFAULT`
*
* The values of the algorithm constants are strings in PHP 7.4+ and integers in PHP 7.3 and earlier.
*
* @since 6.8.0
*
* @param string|int $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 'wp_hash_password_algorithm'
* filter. You must ensure that the options are appropriate for the algorithm in use.
*
* The values of the algorithm constants are strings in PHP 7.4+ and integers in PHP 7.3 and earlier.
*
* @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|int $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 );
}
Hooks
- apply_filters( ‘wp_hash_password_algorithm’, string|int $algorithm )
-
Filters the hashing algorithm to use in the password_hash() and password_needs_rehash() functions.
- apply_filters( ‘wp_hash_password_options’, array $options, string|int $algorithm )
-
Filters the options passed to the password_hash() and password_needs_rehash() functions.
Skip to note 3 content
Codex
Use Blowfish or extended DES (if available) instead of MD5 to hash the password with 16 rounds of hashing:
$wp_hasher = new PasswordHash(16, FALSE); $hashedPassword = wp_hash_password($password);Skip to note 4 content
Codex
Compare an already hashed password with its plain-text string:
CheckPassword($plain_password, $password_hashed)) { echo "YES, Matched"; } else { echo "No, Wrong Password"; } ?>