Node crypto, used right: KDFs, HMAC, signatures, and constant-time compares

Hashing vs HMAC: integrity, then authenticated integrity

A plain hash answers one question: did these bytes change? crypto.createHash('sha256') maps input to a fixed digest, so the same input always yields the same output and any tampering changes it. That is fine for a content checksum or a cache key — but it proves nothing about who produced it. Anyone can recompute the digest, so an attacker who alters a message can simply recompute its hash and you cannot tell.

HMAC closes that gap. It mixes a secret key into the hash, so only parties holding the key can produce or verify a valid tag. Use a plain hash for integrity against accidental corruption; use HMAC when you need authenticated integrity — proving a value came from someone who knows the key. Signed cookies, webhook signatures (Stripe, GitHub), and stateless tokens all rely on HMAC, not a bare hash.

const crypto = require('node:crypto');

// Plain hash — integrity only, anyone can recompute it
const digest = crypto.createHash('sha256').update(payload).digest('hex');

// HMAC — keyed, only key holders can produce/verify the tag
const key = process.env.WEBHOOK_SECRET;
const tag = crypto.createHmac('sha256', key).update(rawBody).digest('hex');
// later: compare `tag` to the header value with timingSafeEqual (see below)

Passwords need a KDF, never a fast hash

The hook’s bug is the most common crypto mistake in web apps: hashing passwords with a fast algorithm. SHA-256, SHA-512, and MD5 are designed to be fast, which is exactly what you do not want for passwords — speed helps the attacker brute-force offline. A leaked database of unsalted SHA-256 digests falls to GPUs doing billions of guesses per second, and identical passwords produce identical digests, so rainbow tables and “crack once, match many” attacks work.

Password storage needs a key derivation function (KDF): deliberately slow, memory-hard, and per-password salted. Node ships scrypt and pbkdf2 natively; argon2 and bcrypt are available via libraries. The salt (from a CSPRNG) makes every hash unique so identical passwords differ and rainbow tables die; the cost factor makes each guess expensive. Always use the async form so you don’t block the event loop while the KDF deliberately burns CPU.

const crypto = require('node:crypto');

function hashPassword(password) {
  return new Promise((resolve, reject) => {
    const salt = crypto.randomBytes(16);          // unique per password, from CSPRNG
    // N=2**15 cost, 64-byte output; store salt alongside the hash.
    // maxmem must be raised: scrypt needs 128*N*r bytes (here 32 MiB), and the
    // default maxmem cap is exactly 32 MiB, so any real cost throws without it.
    crypto.scrypt(password, salt, 64, { N: 2 ** 15, maxmem: 64 * 1024 * 1024 }, (err, hash) => {
      if (err) return reject(err);
      resolve(`${salt.toString('hex')}:${hash.toString('hex')}`);
    });
  });
}

function verifyPassword(password, stored) {
  return new Promise((resolve, reject) => {
    const [saltHex, hashHex] = stored.split(':');
    const salt = Buffer.from(saltHex, 'hex');
    const expected = Buffer.from(hashHex, 'hex');
    crypto.scrypt(password, salt, expected.length, { N: 2 ** 15, maxmem: 64 * 1024 * 1024 }, (err, actual) => {
      if (err) return reject(err);
      resolve(crypto.timingSafeEqual(actual, expected)); // constant-time, see below
    });
  });
}

// usage — hash on signup, verify on login (also a smoke test that the cost params run)
const stored = await hashPassword('correct horse battery staple');
console.log('verify correct:', await verifyPassword('correct horse battery staple', stored)); // true
console.log('verify wrong:  ', await verifyPassword('wrong', stored));                         // false

Asymmetric signatures: prove origin without sharing a secret

HMAC works when both sides share one secret. When they cannot — you want to publish something anyone can verify but only you can produce (a software release, a JWT signed by an auth server, a licence) — you need asymmetric signing. You sign with a private key and anyone verifies with the matching public key. The public key proves nothing about the holder’s ability to forge; only the private key can sign.

const crypto = require('node:crypto');

const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');

// Sign with the private key (Ed25519 takes null for the algorithm arg)
const signature = crypto.sign(null, Buffer.from(message), privateKey);

// Anyone with the public key verifies — returns true/false
const ok = crypto.verify(null, Buffer.from(message), publicKey, signature);

For streaming or large inputs use the crypto.createSign('SHA256') / crypto.createVerify('SHA256') object API with RSA or ECDSA keys: .update(chunk) repeatedly, then .sign(privateKey) / .verify(publicKey, sig). The key choice — HMAC vs signature — is about whether verifiers can be trusted with the signing power.

Randomness and constant-time comparison: the two silent footguns

Two more mistakes are subtle because the code runs fine. When you reach for Math.random() to generate a token, nothing breaks — until it does. First, randomness: Math.random() is a fast PRNG with no cryptographic guarantees — its output is predictable and must never generate tokens, salts, session IDs, or keys. Use crypto.randomBytes(n) (a CSPRNG) for raw bytes and crypto.randomUUID() for IDs. Second, comparison: comparing secrets with ===, ==, or Buffer.compare early-exits on the first differing byte, so the time it takes leaks how many leading bytes matched — and an attacker can recover a token byte by byte by measuring response times. Use crypto.timingSafeEqual(a, b), which compares in constant time. It requires two Buffers of equal length (it throws otherwise), so hash both sides to a fixed length first, or length-check before calling.

const crypto = require('node:crypto');

// WRONG — leaks how many leading bytes matched via timing
if (userToken === storedToken) grantAccess();

// RIGHT — constant-time; both Buffers must be the same length
const a = Buffer.from(userToken);
const b = Buffer.from(storedToken);
if (a.length === b.length && crypto.timingSafeEqual(a, b)) grantAccess();