Skip to content
Tutorials Center
My learning

Topics

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.

PHP
$signature = hash_hmac('sha256', $message, $secretKey);
hash_equals($expected, $received);

Try it

PHP Signing and verifying a message

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.

PHP Keys, binary output and errors

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

PHP
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() or sha1() 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.