# crypto.constant-time-equal

`constantTimeEqual(expectedTag, givenTag)` is true when the two byte strings
are identical. Use it wherever one side is secret and the other comes from
outside: an HMAC tag, a JWT signature, a password hash, an API key digest.

An ordinary `==` on lists or strings stops at the first byte that differs.
Timed over many requests, that tells an attacker how many leading bytes of a
forged value were right, and lets them find a valid tag a byte at a time.
This looks at every byte whatever it finds, OR-ing the differences together
and deciding once at the end, which is how Node's `timingSafeEqual` and
Python's `hmac.compare_digest` (which the Python implementation uses) work.

Lengths are compared first and different lengths answer false straight away.
That reveals the length, which is not a secret for a MAC or hash (its length
is fixed by the algorithm). Compare fixed-length digests, not raw secrets of
varying length; hash both sides first if you must.

Constant time is a property of the code as written; a JIT or an optimising
compiler may still find shortcuts, which is why the libraries above exist.
This is the same loop they use and is as good as pure code can do, and the
vectors pin its answers, not its timing.

Bytes are lists of integers 0 to 255, as everywhere in the registry (see
`encoding.hex`), and a value outside that range is an error rather than
"not equal", because it means the caller passed the wrong thing.