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);
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[]required

One byte string, such as the tag that was received.

bu8[]required

The 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[]required

The array holding the first window.

aOffi32required

Where the first window starts in a.

bu8[]required

The array holding the second window.

bOffi32required

Where the second window starts in b.

leni32required

How 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.