Why does `hmac.compare_digest` exist when `==` already compares two bytes objects?

### What ordinary equality actually does `a == b` for two `bytes` objects in CPython first compares their lengths — different lengths mean not equal, immediately — and then compares the buffers byte by byte, returning as soon as it finds a difference. That is exactly the right implementation for a general-purpose equality operator: it is correct, and it is fast because it does the least work it can get away with. Doing the least work possible is the problem. If the value on one side is a secret and the value on the other side was supplied by whoever is calling you, the *duration* of the comparison is a signal that leaks out of the process. A comparison that stops at the first differing byte takes measurably longer when the first byte happens to be right than when it is wrong. An attacker who can submit many guesses and measure the responses can recover the secret one byte at a time instead of guessing the whole thing at once — turning an impossible search into a linear one. ### What compare_digest does instead `hmac.compare_digest(a, b)` returns the same boolean that `a == b` would, but it is implemented so that the work it performs does not depend on the contents of the arguments. Instead of returning at the first mismatch it walks a fixed number of positions, accumulating the bit-differences it finds, and reports at the end whether the accumulator is still zero. The accelerated implementation is written in C with volatile declarations precisely so the compiler cannot 'optimise' the loop back into an early exit. Nothing about the operation is fast — it is *uniform*, which is the property being bought. `secrets.compare_digest` is not a second implementation; the `secrets` module imports the name straight from `hmac`, so the two names are the same object. Use whichever reads better in the module you are writing. ### Where to use it The rule of thumb: use it whenever one side is a secret, the other side is attacker-controlled, and the attacker can observe the outcome or the latency of the check repeatedly. In practice that means authentication tags on incoming webhooks, request signatures, bearer tokens and API keys, session and CSRF identifiers, password-reset and email-confirmation tokens, and one-time codes. It is not a general-purpose replacement for `==`. Comparing two values an attacker already knows leaks nothing. Comparing configuration constants leaks nothing. Sprinkling it everywhere costs readability and buys nothing. ### The Python-specific traps The subtle part is that `==` hides inside other constructs. `token in valid_tokens` on a `list` runs `==` against each element and short-circuits. On a `set` or as a `dict` key it hashes first, which is better, but a hash collision still falls back to `==`, and the lookup structure itself can leak. `presented.startswith(secret_prefix)` short-circuits. `sorted()` and any comparison-based container operation on secret values short-circuits. If a secret is being matched against a collection, the safe shape is to look the record up by a **non-secret** identifier — a key id, a tenant id, a username — and then run exactly one `hmac.compare_digest` against the single stored value for that record. Two more things it does not do. It does not make the check safe on its own: without rate limiting, an attacker with unlimited guesses does not need a timing side channel. And it does not hide the *length* of the values, only their contents — the loop still runs a number of times that depends on the size of what it was given, which is why fixed-length digests are the natural thing to feed it. ### Reading the timing argument honestly Over a noisy network a single measurement tells an attacker nothing; the differences involved are sub-microsecond and the jitter is milliseconds. The reason this is still non-negotiable in review is that noise is removable by averaging over enough samples, co-located attackers exist, and the fix costs one function call. A candidate who argues 'the network hides it' has understood the physics and missed the engineering: you do not build a system whose safety rests on an attacker not bothering to collect more samples. ### Why not hand-roll it A pure-Python loop cannot credibly deliver this property. `all(x == y for x, y in zip(a, b))` short-circuits by construction; a version that avoids short-circuiting is still at the mercy of the interpreter, which caches small integers, specialises bytecode as it runs, and allocates as it goes — none of which is uniform in time. The constant-time claim lives in a C loop written to defeat the compiler's optimiser, and that is why the answer is always the library function rather than a clever comprehension in your own module.