wp_check_password( string $password, string $hash, string|int $user_id = '' ): bool

Checks a plaintext password against a hashed password.

Description

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 instead use the other package password hashing algorithm.

Parameters

$passwordstringrequired
Plaintext password.
$hashstringrequired
Hash of the password to check against.
$user_idstring|intoptional
ID of a user associated with the password.

Default:''

Return

bool False, if the $password does not match the hashed password.

More Information

This function can be replaced via plugins. If plugins do not redefine these functions, then this will be used instead.

Source

function wp_check_password(
	#[\SensitiveParameter]
	$password,
	$hash,
	$user_id = ''
) {
	global $wp_hasher;

	if ( strlen( $hash ) <= 32 ) {
		// Check the hash using md5 regardless of the current hashing mechanism.
		$check = hash_equals( $hash, md5( $password ) );
	} elseif ( ! empty( $wp_hasher ) ) {
		// Check the password using the overridden hasher.
		$check = $wp_hasher->CheckPassword( $password, $hash );
	} elseif ( strlen( $password ) > 4096 ) {
		// Passwords longer than 4096 characters are not supported.
		$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';
		$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 );
	}

	/**
	 * 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 or md5.
	 *
	 * @param bool       $check    Whether the passwords match.
	 * @param string     $password The plaintext password.
	 * @param string     $hash     The hashed password.
	 * @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 );
}

Hooks

apply_filters( ‘check_password’, bool $check, string $password, string $hash, string|int $user_id )

Filters whether the plaintext password matches the hashed password.

Changelog

VersionDescription
6.8.0Passwords in WordPress are now hashed with bcrypt by default. A password that wasn’t hashed with bcrypt will be checked with phpass.
2.5.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.