TL;DR
Hash-based message authentication code (HMAC) is a dual-layer cryptographic technique that combines a secret key with a hash function to verify data integrity and authenticity. The sender attaches the resulting code to the message, and the recipient recalculates it with the same shared key. If the codes match, the message is genuine. It is widely used to sign API requests and webhooks, and developers should test thoroughly before deployment to avoid blocking legitimate users.
What is HMAC?
Hash-based message authentication code (or HMAC) is a cryptographic authentication technique that uses a hash function and a secret key.
With HMAC, you can achieve authentication and verify that data is correct and authentic with shared secrets, as opposed to approaches that use signatures and asymmetric cryptography.
How does HMAC work?
Two parties want to communicate, and they need to be sure that each message really came from the other party and wasn’t changed along the way. They also distrust the internet, and they need a way to verify that the packets they receive haven't been tampered with. HMAC is a valid solution.
How HMAC works: the sender generates a message authentication code (MAC) from the message and a shared secret key, then sends both. The recipient recalculates the MAC with the same key. If it matches, the message is authentic and unaltered.
| Component | Type | Description |
|---|---|---|
| Cryptographic keys | Secret key | A value known only to the sender and the recipient. HMAC mixes it into the hash, so only someone with the key can produce or verify a valid code. |
| Hash function | Algorithm | A hash function turns its input into a fixed-length digest. HMAC works with standard cryptographic hash functions, and SHA-256 is a common choice. Both parties must agree on the same one. |
| Secret keys (agreement) | Shared secret | Both parties must hold the same key before they start, and it must stay secret. Anyone who has it can create valid codes. |
The output is a fixed-length code, called a message authentication code (MAC), that is sent along with the message. HMAC doesn’t hide the message itself. It proves that the message came from someone with the shared key and wasn’t changed along the way. Even a one-character change produces a completely different code, so tampering is easy to detect.
HMAC tester tools can help demonstrate how something like this works. Imagine you're dealing with these inputs:
- Potential message: Hello neighbor!
- Secret key: 123
- Algorithm: SHA-256
The resulting message reads: " 056bc81c5ec3107ce2411f190dfd500b42c48351f6a3ede83601839dcdd0677d".
What does HMAC look like mathematically?
A dense layer of mathematics underlies what seems like an easy translation process. Understanding the math is critical for developers. If you're asked to explain your work and the protections you offer, a diagram can often showcase things better than your words ever can.
But the average computer user may never need to understand the math. To them, knowing that their messages are protected may be all they require.
How do you implement HMAC?
To use HMAC, either as an individual or a web developer, you'll need two important things. And you'll need an agreement about those items with your recipients, so you're all using the same tools at the same time.
These are the two items you'll need:
- A shared secret
- A hashing tool
Only your server should know all the items for all of your users. And that data should be fiercely protected. Anyone who knows the secret keys for your members can take over your server and/or send fraudulent data.
Every website and coding environment is different, but walking through an example might be helpful. Imagine that you'd like to use HMAC on traffic that comes to your website via dynamic ads from Google. You will:
- Build your token in Ad Manager. You'll specify details about the visit and the time. You'll use Google's authentication key to create your "secret key."
- Implement. You can put your new token within your authorization request header, or you can pass it as a query string or form data parameter.
Google makes this process quick and easy. Developers can access a simple tutorial and copy code within minutes.
Notice that you're not asking your Google Ads visitors to memorize a code or do any decoding. The user's server understands the coding requirements within your website, and all of the token setting and translation is invisible to the user.
Why testing your HMAC implementation matters
Even so, you should test this environment often before you deploy it. If you encounter a coding error, you could block people from accessing your site, as it will seem as though they're fraudulent actors. It pays to test any system like this on multiple devices before you set it loose on the wider world.
When should you use HMAC?
Nearly every company has sensitive information. If you take in payments of any sort, for example, you likely have credit card data at your fingertips. And if you have employees, you have Social Security numbers that could be stolen.
Which industries benefit most from HMAC?
But some companies have even deeper issues. If you're in a heavily regulated environment, such as health care, or you deal with trade secrets, such as munitions, it pays to move past traditional security measures.
HMAC, which verifies both who sent a message and that it wasn't changed, could be ideal for companies that need to do a little more to prove that they're protecting their assets as carefully as possible.
Help From Okta
At Okta, we help developers secure their APIs and applications. Learn how Okta API Access Management controls who and what can call your APIs, or see how Okta uses HMAC signature algorithms in Okta Workflows.
Frequently asked questions
What is HMAC and how is it different from other authentication methods?
HMAC (Hash-based message authentication code) combines a cryptographic hash function with a secret key to verify both the authenticity and integrity of a message. Unlike approaches that rely on asymmetric cryptography and digital signatures, HMAC uses shared secret keys, making it a symmetric authentication technique.
What two components does HMAC require to function?
HMAC requires a secret key that both parties share and a cryptographic hash function, such as SHA-256, that combines the message and key into a fixed-length code.
What does HMAC protect against?
HMAC protects a message’s integrity and authenticity. If the message is altered, or comes from someone without the shared key, the recipient’s recalculated code won’t match. Its strength also depends on keeping the secret key private and using a strong hash function.
What do both parties need to agree on before using HMAC?
Both communicating parties must agree on two things in advance: the shared secret key used to generate and verify the code. The specific hash algorithm that all messages will be processed through.
What are the risks of improperly securing HMAC secret keys?
If the secret key is exposed, an attacker can generate valid codes and send forged messages that look genuine, or tamper with messages without detection. Store keys securely, limit who can access them, and rotate them regularly.
Why is testing an HMAC implementation important before deployment?
A misconfigured HMAC setup can cause legitimate users to be incorrectly flagged as fraudulent actors and blocked from accessing the site. Thorough testing across multiple devices before going live helps prevent these access issues.
References
HMAC: Keyed-Hashing for Message Authentication. (February 1997). Network Working Group.
HMAC and Key Derivation. Practical Cryptography for Developers.
HMAC Generator/Tester Tool. FreeFormatter.
How API Request Signing Works (And How to Implement HMAC in NodeJS). (2016). Andrew Hoang.
