Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.createHmac() method

Reference for crypto.createHmac() in Node.js: sign data with a secret key, verify webhook-style signatures safely, key types and common mistakes.

crypto.createHmac(algorithm, key) creates an Hmac object, which works like a Hash but mixes a secret key into the computation. The result, an HMAC (hash-based message authentication code), proves two things: the data was not changed, and whoever produced it knew the key.

HMACs are used for webhook signatures, signed cookies and tokens, API request signing and as building blocks in key derivation. Both sides share the secret; neither can be tricked by someone who only sees the data and the code.

NODE
import { createHmac } from 'node:crypto';
const mac = createHmac('sha256', 'secret').update('message').digest('hex');

Try it

Node.js Signing and verifying a payload

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 node:readline or process.stdin), it gets the next line from this box.

Node.js Keys matter and streaming input

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 node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
crypto.createHmac(algorithm, key[, options])   // Hmac
hmac.update(data[, inputEncoding])             // Hmac
hmac.digest([encoding])                        // Buffer | string
Name Description
algorithm A hash name such as 'sha256' or 'sha512'.
key A string, Buffer, typed array, DataView or KeyObject (secret key).
data The message: string, Buffer, typed array or DataView.
inputEncoding Encoding for a string data, default 'utf8'.
encoding 'hex', 'base64', 'base64url', 'latin1'; omitted returns a Buffer.

Returns: the MAC as a Buffer or encoded string. An Hmac is also a stream.

Errors: an unknown algorithm throws an Error ("Invalid digest"). A key of the wrong type throws ERR_INVALID_ARG_TYPE. Calling digest() a second time returns an empty Buffer (or empty string) instead of the MAC; do not rely on that, just compute it once.

Usage notes

  • Compare MACs in constant time. Use timingSafeEqual() on buffers of equal length, not === on strings, so an attacker cannot learn the signature byte by byte from response timing.
  • Use a random key of at least 32 bytes from randomBytes(), not a human-chosen phrase. Keys shorter than the hash block size are padded; longer ones are hashed first.
  • Sign exactly what the verifier will see. Verify the raw request body, not a re-serialized copy: whitespace or key order changes the MAC.
  • Include context in the message. Add a timestamp or an ID so an old valid message cannot be replayed, and check it on the other side.
  • An HMAC is not encryption. The message stays readable; only tampering becomes detectable.
  • Prefer SHA-256 or stronger. HMAC-SHA1 and HMAC-MD5 are still unbroken as MACs but are discouraged for new designs.
  • A hash is not a MAC. sha256(secret + data) is vulnerable to length-extension attacks; always use createHmac().