nish/crypto/ct
Comparing secrets without telling the clock where they differ.
import {
timingSafeEqual,
timingSafeEqualAt,
} from "nish/crypto/ct";
import { timingSafeEqual } from "nish/crypto/ct";
const ok: boolean = timingSafeEqual(expectedTag, receivedTag);
timingSafeEqual
Whether a and b hold the same bytes, reading all of them.
timingSafeEqualAt
Whether the len bytes of a from aOff equal the len bytes of b from bOff, reading all of them.
Every byte is read
An === loop over two MACs stops at the first
differing byte, so the time it takes says how many leading bytes an attacker
already guessed right, and a tag can be recovered one byte at a time. These
functions read every byte of the window whatever it holds: each pair is
XORed, the differences are ORed into one accumulator, and that accumulator is
tested once, after the loop.
Lengths may branch
What is not secret is checked first and may branch: the two lengths, and whether a window lies inside its array. A caller comparing a received tag against an expected one already knows both lengths, so refusing a mismatch early leaks nothing the attacker did not send.
A discipline, not yet a proof
The names are timingSafeEqual*, after
Node's crypto.timingSafeEqual, rather than ctEq: that one is reserved for
the builtin WP34 N6 will add, together with the disassembly check that proves
the loop stays branch-free after LLVM has seen it. Until then this is the
discipline and not a proof.
Functions
timingSafeEqual
Whether a and b hold the same bytes, reading all of them.
Arrays of different lengths answer false at once, because a length is
public; arrays of one length are compared in full, with no early exit.
The lengths are compared as the numbers they are, before any toI32:
under --number-mode f64 toI32 saturates at 2^31 - 1, so two arrays past
it would have looked the same length and been compared only that far. An
array longer than that answers false too — no i32 index reaches its end,
and a compare that cannot read every byte must not say "equal".
const timingSafeEqual: (a: u8[], b: u8[]) => boolean
au8[]requiredOne byte string, such as the tag that was received.
bu8[]requiredThe other, such as the tag computed for comparison.
returnsboolean
true only when both lengths match and every byte does; false for
different lengths or a length past 2^31 - 1.
timingSafeEqualAt
Whether the len bytes of a from aOff equal the len bytes of b from
bOff, reading all of them.
A window that does not lie inside its array — a negative offset or length,
or off + len past the end — answers false instead of panicking on the
first out-of-range read. That is a decision about the caller's position: a
verifier handed a truncated record should say "not equal", not take the
process down, and the bounds are public, so testing them first is safe.
const timingSafeEqualAt: (
a: u8[],
aOff: i32,
b: u8[],
bOff: i32,
len: i32,
) => boolean
au8[]requiredThe array holding the first window.
aOffi32requiredWhere the first window starts in a.
bu8[]requiredThe array holding the second window.
bOffi32requiredWhere the second window starts in b.
leni32requiredHow many bytes each window covers.
returnsboolean
true only when both windows lie inside their arrays and every byte
matches; false for a window out of range.

