crypto.constant-time-equal

export function constantTimeEqual(a: readonly number[], b: readonly number[]): boolean

import { constantTimeEqual } from "#fune/crypto.constant-time-equal@^1";

function checkBytes(value: readonly number[], name: string): void {
  if (!Array.isArray(value) && !(value instanceof Uint8Array)) {
    throw new TypeError(`${name} must be a list of integers from 0 to 255`);
  }
  for (let i = 0; i < value.length; i++) {
    const b = value[i];
    if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
      throw new RangeError(`${name} must be a list of integers from 0 to 255`);
    }
  }
}

/**
 * Are two byte strings equal, without stopping at the first difference?
 * Every byte is visited and the differences OR-ed together, so the time
 * taken says nothing about where a forged tag goes wrong. Different lengths
 * answer false at once: a digest's length is not a secret.
 */
export function constantTimeEqual(a: readonly number[], b: readonly number[]): boolean {
  checkBytes(a, "a");
  checkBytes(b, "b");
  if (a.length !== b.length) return false;
  let diff = 0;
  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
  return diff === 0;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add crypto.constant-time-equal

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./crypto.constant-time-equal-1.0.0-typescript.fune, or fetch it from a terminal with fune pull crypto.constant-time-equal@1.0.0:typescript.

The whole function, every language, is one file too: crypto.constant-time-equal-1.0.0.fune, 8,608 bytes, sha256 db66dc151f666ef3543ee658d0dba37923deb21f54390dc4595a6c080f23bad3. It installs into a project of any language.

// fune: before crypto.constant-time-equal

// fune: after crypto.constant-time-equal

// fune: step crypto.constant-time-equal after <n|label>

More from the author

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.

Files