PHP Reference ยท Web and Security
PHP hash_hmac() and hash_equals() functions
Reference for PHP hash_hmac() and hash_equals(): sign messages with a secret key, verify signatures safely, and compare strings without leaking timing.
hash_hmac() computes a keyed hash (HMAC): a digest that can only be produced by someone who knows the secret key. Use it to sign data that travels through an untrusted place, such as a URL, a cookie or a webhook payload, so you can detect tampering later.
hash_equals() compares two strings in constant time. When you check a signature or token, a plain === stops at the first differing byte, and the tiny timing difference can in theory leak how much of a guess was right.
$signature = hash_hmac('sha256', $message, $secretKey); hash_equals($expected, $received);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
hash_hmac(string $algo, string $data, string $key, bool $binary = false, array $options = []): string hash_equals(string $known_string, string $user_string): bool
| Name | Description |
|---|---|
$algo |
A hash algorithm name from hash_hmac_algos(), for example sha256 or sha512. |
$data |
The message to authenticate. |
$key |
The secret key. Use at least 32 random bytes. |
$binary |
true returns raw bytes instead of lowercase hex. |
$known_string |
The trusted value you computed yourself. |
$user_string |
The value received from the user. |
Return value: hash_hmac() returns the hex or binary digest. hash_equals() returns true only when both strings are identical.
Errors: hash_hmac() throws a ValueError for an unknown or non-cryptographic algorithm (such as crc32). hash_equals() throws a TypeError when either argument is not a string.
Usage notes
- Put the known value first in
hash_equals(). Its running time depends on the length of the first argument. - Both inputs must be strings, so cast numbers before comparing, as the second example shows.
- HMAC is not encryption. The message stays readable; the signature only proves it was not changed and came from a key holder.
- Include everything that matters in the message, such as an expiry time, the user id and the purpose. Signing only an id lets a signature be reused elsewhere.
- Do not use
md5()orsha1()plus a key glued on (md5($key . $data)). Plain concatenation is vulnerable to length-extension attacks. HMAC is built to avoid them. - Store the key outside the code, in an environment variable or secrets store, and rotate it if it leaks.
- Webhooks: services usually send an HMAC of the raw request body. Compute it over the exact raw bytes, not over re-encoded JSON.
- For passwords use
password_hash(), not HMAC.