wp_generate_auth_cookie()
云策文档标注
概述
wp_generate_auth_cookie() 函数用于生成 WordPress 用户身份验证的 Cookie 内容。它基于用户 ID、过期时间、Cookie 方案和会话令牌等参数，通过哈希计算生成安全的认证字符串。
关键要点
- 函数返回身份验证 Cookie 内容字符串，若用户不存在则返回空字符串。
- 参数包括：$user_id（用户 ID，必填）、$expiration（过期时间戳，必填）、$scheme（Cookie 方案，可选，默认为 'auth'）、$token（会话令牌，可选）。
- 内部逻辑涉及获取用户数据、处理密码片段、生成密钥和哈希值，最终组合成 Cookie 字符串。
- 通过 apply_filters('auth_cookie', ...) 钩子允许过滤生成的 Cookie。
代码示例
function wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $token = '' ) {
$user = get_userdata( $user_id );
if ( ! $user ) {
return '';
}
if ( ! $token ) {
$manager = WP_Session_Tokens::get_instance( $user_id );
$token = $manager->create( $expiration );
}
if ( str_starts_with( $user->user_pass, '$P$' ) || str_starts_with( $user->user_pass, '$2y$' ) ) {
$pass_frag = substr( $user->user_pass, 8, 4 );
} else {
$pass_frag = substr( $user->user_pass, -4 );
}
$key = wp_hash( $user->user_login . '|' . $pass_frag . '|' . $expiration . '|' . $token, $scheme );
$hash = hash_hmac( 'sha256', $user->user_login . '|' . $expiration . '|' . $token, $key );
$cookie = $user->user_login . '|' . $expiration . '|' . $token . '|' . $hash;
return apply_filters( 'auth_cookie', $cookie, $user_id, $expiration, $scheme, $token );
}注意事项
- Cookie 方案 $scheme 可选值为 'auth'、'secure_auth' 或 'logged_in'，影响密钥生成。
- 从版本 4.0.0 开始，新增 $token 参数以支持会话令牌管理。
- 函数依赖 WP_Session_Tokens、wp_hash() 等核心组件，确保环境兼容性。
原文内容
Generates authentication cookie contents.
Parameters
$user_idintrequired-
User ID.
$expirationintrequired-
The time the cookie expires as a UNIX timestamp.
$schemestringoptional-
The cookie scheme to use:
'auth','secure_auth', or'logged_in'.
Default'auth'. $tokenstringoptional-
User’s session token to use for this cookie.
Source
function wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $token = '' ) {
$user = get_userdata( $user_id );
if ( ! $user ) {
return '';
}
if ( ! $token ) {
$manager = WP_Session_Tokens::get_instance( $user_id );
$token = $manager->create( $expiration );
}
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 );
$hash = hash_hmac( 'sha256', $user->user_login . '|' . $expiration . '|' . $token, $key );
$cookie = $user->user_login . '|' . $expiration . '|' . $token . '|' . $hash;
/**
* Filters the authentication cookie.
*
* @since 2.5.0
* @since 4.0.0 The `$token` parameter was added.
*
* @param string $cookie Authentication cookie.
* @param int $user_id User ID.
* @param int $expiration The time the cookie expires as a UNIX timestamp.
* @param string $scheme Cookie scheme used. Accepts 'auth', 'secure_auth', or 'logged_in'.
* @param string $token User's session token used.
*/
return apply_filters( 'auth_cookie', $cookie, $user_id, $expiration, $scheme, $token );
}
Hooks
- apply_filters( ‘auth_cookie’, string $cookie, int $user_id, int $expiration, string $scheme, string $token )
-
Filters the authentication cookie.