Understanding HMAC signatures and how they work

HMAC, short for Hash-based Message Authentication Code, is a method used to check that a message is both authentic and unmodified. It's a common tool in webhooks, APIs, and any place where secure communication between systems matters. The idea behind HMAC is to use a shared secret key along with a hashing algorithm to create a unique signature for a message. This signature acts like a stamp of trust, if anything changes in the message or if the wrong key is used, the signature won't match.

How HMAC works internally

At a technical level, HMAC combines a secret key with the message content, processes them using a cryptographic hash function, and produces a fixed-size signature. The process isn't just a basic hash of both values; it follows a structured approach to make the output more secure against known attacks.

1. The key is adjusted to fit the block size of the hashing algorithm (like SHA-256), either by trimming or padding it.

2. Two versions of the key are created using XOR with fixed byte values.

3. The inner key is hashed together with the message.

4. The result of that is then hashed again with the outer key.

This two-layer hashing structure adds an extra layer of protection and makes it extremely difficult to reverse-engineer the key or forge messages without knowing the original secret.

Creating HMAC signatures in PHP

PHP makes it easy to generate HMAC signatures using the built-in hash_hmac function. This function requires three things: the hash algorithm, the message, and the secret key.

Here's a basic example:

<?php

$message = 'This is the message';
$secretKey = 'my_secret_key';

$signature = hash_hmac('sha256', $message, $secretKey);
echo $signature;

This will output a hexadecimal string representing the HMAC of the message. You can also set the fourth parameter of hash_hmac to true if you want the raw binary output instead of hex.

Protecting query parameters with HMAC

HMAC is also useful for protecting data in URLs, such as when creating time-limited or user-specific links. You can generate a signature for the query string and include it in the URL.

Here's an example:

<?php

$params = [
    'user_id' => 42,
    'expires' => 17545676399,
];
$secretKey = 'my_secret_key';

$signature = hash_hmac('sha256', http_build_query($params), $secretKey);

$url = sprintf('https://hibit.dev/resource?%s&signature=%s', http_build_query($params), $signature);
echo $url;

When the request arrives, the server extracts the parameters and the signature, regenerates the HMAC using the shared secret, and compares the result. If the values don't match, the request is rejected.

Verifying HMAC signatures

Suppose a message and its signature arrive from an external service, and the goal is to verify their authenticity. This involves recreating the signature using the shared secret key and comparing it to the one that was received.

Here's how that would look in PHP:

<?php

$receivedMessage = $_POST['message'];
$receivedSignature = $_POST['signature'];
$secretKey = 'my_secret_key';

$expectedSignature = hash_hmac('sha256', $receivedMessage, $secretKey);

if (hash_equals($expectedSignature, $receivedSignature)) {
    echo 'Signature is valid';
} else {
    echo 'Signature is invalid';
}

When the request comes in, you extract the parameters and the signature, regenerate the HMAC on your side, and check if it matches. If it doesn't, you reject the request.

Conclusion

HMAC is a solid choice when you need to make sure that messages or data haven't been changed and come from a source you trust. It's simple to use, widely supported, and effective without adding too much complexity to your application. As long as the secret key stays private, HMAC can help you build safer and more reliable systems.