hash_equals()¶
hash_equals() is a built-in PHP function that compares two strings in constant time, regardless of where they differ.
It is specifically designed to prevent timing attacks: a regular == or === comparison short-circuits as soon as it finds a differing byte, leaking information about the compared value through the response time. hash_equals() always takes the same amount of time, making it safe for security-sensitive comparisons such as comparing password hashes, HMAC signatures, CSRF tokens, or API keys.
The function returns true if both strings are equal, false otherwise. If the two arguments are not strings, a TypeError is raised.
A common mistake is to compare hashes with ===, which is semantically correct but vulnerable to timing attacks. hash_equals() should be used whenever the compared value could be guessed by an attacker through repeated requests.
<?php
$expected = hash_hmac('sha256', $message, $secret);
$received = $_POST['signature'];
// Vulnerable: === leaks timing information
if ($expected === $received) {
// ...
}
// Safe: constant-time comparison
if (hash_equals($expected, $received)) {
// ...
}
?>
See also Timing attacks explained.
Related : Timing Attack, Hash Comparisons, Cryptographic Hash, Authentication, Cross Site Request Forgery (CSRF), Security, HMAC
Added in PHP 5.6
