Constant-time comparison and secrets in memory
Compare secrets without leaking them through timing, in TypeScript, Python and Go, and hold secrets in memory in a way that limits where copies end up: buffers you can wipe, wrappers that refuse to print, and no secrets in core dumps or logs.
01Understand the problem
- Explain how an early-exit comparison leaks a secret byte by byte
- Use the right primitive in each language:
timingSafeEqual,hmac.compare_digest,subtle.ConstantTimeCompare - Handle unequal lengths without throwing or leaking the secret length
- Keep secrets in wipeable buffers behind a wrapper that will not print itself
What they probe: why === is a problem for tokens, what timingSafeEqual does with different lengths, whether hashing before comparing is sound, and what you can and cannot guarantee about wiping memory in a garbage-collected language. Where candidates slip: calling timingSafeEqual on strings of different lengths (it throws), comparing hex strings with a loop that returns early, promising that memory is fully erased in JavaScript or Go.
A normal string comparison stops at the first differing byte. If an attacker can submit guesses for an API key or MAC and measure response times precisely enough (statistics over many requests make even microsecond differences measurable on a quiet network), they learn how many leading bytes were right and can recover the secret one byte at a time: about 256 guesses per byte instead of 256 to the power of the length. A constant-time comparison touches every byte regardless of where the first difference is.
| Language | Primitive | Behaviour on different lengths |
|---|---|---|
| Node.js | crypto.timingSafeEqual(a, b) | Throws RangeError; compare equal-length digests instead |
| Python | hmac.compare_digest(a, b) | Returns False; may leak the lengths, not the contents |
| Go | subtle.ConstantTimeCompare(x, y) | Returns 0 immediately; the length is not treated as secret |
| Java | MessageDigest.isEqual(a, b) | Returns false; constant time (proportional to the first array) since Java 6u17 |
02Interfaces first
/** Constant-time equality for secrets of any length. Never throws on a length mismatch. */
export interface SecretComparer {
equals(given: string | Buffer, expected: string | Buffer): boolean;
}
/** A secret value that cannot be logged, stringified or serialised by accident. */
export interface SecretBox {
/** Runs fn with the raw bytes; the buffer must not be kept after fn returns. */
use<T>(fn: (bytes: Buffer) => T): T;
/** Overwrites the bytes with zeros. Later use() calls throw. */
wipe(): void;
}A comparer that accepts (given, expected) can hash both to the same length before comparing. That removes the length mismatch problem and means the time depends only on the attacker's own input length, which they already know.
03Comparing safely in three languages
import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
/** HMAC both values under a per-process random key: equal-length 32-byte outputs, and nothing to precompute. */
const COMPARE_KEY = randomBytes(32);
const digest = (v: string | Buffer) => createHmac("sha256", COMPARE_KEY).update(v).digest();
export const comparer: SecretComparer = {
equals(given, expected) {
return timingSafeEqual(digest(given), digest(expected));
},
};
// What not to do:
// given === expected early exit at the first differing character
// timingSafeEqual(Buffer.from(given), Buffer.from(expected)) throws RangeError when lengths differ,
// and the try/catch around it becomes a length oracleimport hmac, hashlib
def verify_webhook(secret: bytes, body: bytes, signature_hex: str) -> bool:
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
# compare_digest accepts two str (ASCII only) or two bytes-like objects; never mix types.
return hmac.compare_digest(expected, signature_hex.lower())package apikey
import (
"crypto/sha256"
"crypto/subtle"
)
// Equal hashes both sides so the lengths always match and the comparison is constant time in 32 bytes.
func Equal(given, expected []byte) bool {
g := sha256.Sum256(given)
e := sha256.Sum256(expected)
return subtle.ConstantTimeCompare(g[:], e[:]) == 1
}Storing API keys well removes most comparisons altogether. Issue keys as prefix_id_secret, store the id in clear and a SHA-256 of the full key (a fast hash is fine because the secret has 256 bits of entropy, unlike a password), look up by id, then compare the stored hash to the hash of what was presented in constant time. A leaked database row is then not a usable key.
import { inspect } from "node:util";
export class Secret implements SecretBox {
#bytes: Buffer | undefined;
constructor(value: Buffer) {
const b = Buffer.alloc(value.length); // alloc, not allocUnsafe: never share a pooled slab with other data
value.copy(b);
this.#bytes = b;
}
static fromEnv(name: string): Secret {
const v = process.env[name];
if (!v) throw new Error("missing secret " + name);
delete process.env[name]; // child processes no longer inherit it
return new Secret(Buffer.from(v, "utf8"));
}
use<T>(fn: (bytes: Buffer) => T): T {
if (!this.#bytes) throw new Error("secret already wiped");
return fn(this.#bytes);
}
wipe(): void {
this.#bytes?.fill(0);
this.#bytes = undefined;
}
toString(): string { return "[REDACTED]"; }
toJSON(): string { return "[REDACTED]"; }
[inspect.custom](): string { return "Secret([REDACTED])"; }
}04What memory hygiene can and cannot promise
| Risk | Where copies come from | Mitigation |
|---|---|---|
| Immutable strings | Every +, template or decode makes a new copy you cannot erase | Keep secrets as Buffer or []byte from the moment they are read |
| Garbage collection | Moving collectors (V8, Go's stack growth) copy objects and leave old bytes | Accept it; reduce lifetime and number of copies instead of promising erasure |
| Core dumps | A crash writes the whole heap to disk | Disable dumps for secret-holding processes (ulimit -c 0, prctl(PR_SET_DUMPABLE, 0)) |
| Swap | Pages with secrets are written to disk | mlock in native code, encrypted swap, or no swap on those hosts |
| Logs and errors | An exception message or debug dump includes the value | Secret wrapper; never put secrets into error messages |
| Environment variables | Visible in /proc/<pid>/environ and inherited by children | Read once, remove from process.env, prefer a secrets manager or mounted file |
fill(0) really overwrites that buffer, but V8, the JVM and Go may already have copied the bytes elsewhere. Say this plainly in a review. For keys that must never be exposed to process memory at all, use an HSM or KMS that performs the operation for you.
import { describe, it, expect } from "vitest";
import { inspect } from "node:util";
describe("comparer", () => {
it("compares equal and unequal values of any length without throwing", () => {
expect(comparer.equals("abc", "abc")).toBe(true);
expect(comparer.equals("abc", "abcd")).toBe(false);
expect(comparer.equals("", "x")).toBe(false);
});
});
describe("Secret", () => {
it("never prints its value", () => {
const s = new Secret(Buffer.from("hunter2"));
expect(String(s)).toBe("[REDACTED]");
expect(JSON.stringify({ s })).toBe('{"s":"[REDACTED]"}');
expect(inspect(s)).not.toContain("hunter2");
});
it("zeros its bytes and refuses use after wipe", () => {
const s = new Secret(Buffer.from("k"));
let seen: Buffer | undefined;
s.use((b) => { seen = b; });
s.wipe();
expect(seen?.every((x) => x === 0)).toBe(true);
expect(() => s.use(() => 1)).toThrow(/wiped/);
});
});05Extensions, follow-ups, how to say it
- Beyond comparison: branches and table lookups indexed by secret data leak too; that is why crypto libraries use constant-time implementations and why you should not write your own.
- Go helpers:
subtle.ConstantTimeSelectandsubtle.ConstantTimeByteEqexist for building constant-time code;crypto/subtle.XORBytes(Go 1.20) for XOR. - Remote timing in practice: jitter makes it harder, not impossible; statistical attacks average it out, so do not rely on network noise.
- Rust and C: crates such as
subtleandzeroize, orexplicit_bzeroandsodium_memzeroin C, stop the compiler removing the wipe as a dead store.
Q1Is it safe to hash both values with SHA-256 and compare with `===`?+
Much safer than comparing the raw values, because an attacker cannot choose inputs that control hash prefixes. Still use a constant-time comparison: it costs nothing and removes the argument.
Q2timingSafeEqual threw RangeError in production. What happened?+
The two buffers had different lengths, typically a truncated or malformed token. Hash both to fixed length first, or check the format strictly (exact length regex) before comparing.
Q3Why does Go's ConstantTimeCompare return immediately on different lengths?+
It treats length as public. For tokens with a fixed format that is fine; for variable-length secrets, hash first.
"For any secret comparison I bring both sides to equal-length digests, an HMAC under a random key or a SHA-256, then use the language's constant-time primitive: timingSafeEqual, compare_digest or ConstantTimeCompare. API keys are stored as an id plus a hash, so the database never holds a usable key. In memory I keep secrets as buffers behind a wrapper that redacts itself in logs and JSON, wipe them after use, keep them out of the environment and core dumps, and I am explicit that wiping is best effort in a garbage-collected runtime."
Which comparison is safe for checking a user-supplied HMAC signature in Node.js against the expected one?
Related lessons
- Design a secrets managerHLD · Design problems: Infrastructure & dataPro
- Design a password hashing module with upgradesLLD · Problems: crypto & protocol componentsFree
- Design an envelope encryption libraryLLD · Problems: policy and crypto enginesPro
- Post-quantum migrationSecEng · Applied cryptography engineeringFree