crypto.constant-time-equal

Compare two byte strings in time that does not depend on where they differ, for checking MACs and hashes.

1.0.0 · published 2026-10-03 by charlie · Anterra

Pinned by 12 tests, run in TypeScript, Python and Rust.

What it does

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

For example

constant_time_equal(, ) → true two empty byte strings are equal
constant_time_equal(1, 2, 3, 1, 2, 3) → true the same bytes
constant_time_equal(176, 52, 76, 97, 216, 219, 56, 83, 92, 168, 175, 206, 175, 11, 241, 43, 136, 29, 194, 0, 201, 131, 61, 167, 38, 233, 55, 108, 46, 50, 207, 247, 176, 52, 76, 97, 216, 219, 56, 83, …) → true the same 32-byte HMAC tag (RFC 4231 test case 1)

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

def constant_time_equal(a: Sequence[int], b: Sequence[int]) -> bool

a	int[]	bytes, each an integer from 0 to 255
b	int[]	bytes, each an integer from 0 to 255
returns	bool	true when both hold the same bytes in the same order

Your code names it in one line, in the file that uses it

from fune.crypto.constant_time_equal import constant_time_equal  # crypto.constant-time-equal@^1

impl/python.py · 23 lines · open · raw

import hmac
from typing import Any, Sequence


def _check_bytes(value: Any, name: str) -> bytes:
    if isinstance(value, (str, dict)) or not hasattr(value, "__len__"):
        raise TypeError("%s must be a list of integers from 0 to 255" % name)
    for b in value:
        if type(b) is not int or b < 0 or b > 255:
            raise ValueError("%s must be a list of integers from 0 to 255" % name)
    return bytes(value)


def constant_time_equal(a: Sequence[int], b: Sequence[int]) -> bool:
    """Are two byte strings equal, without stopping at the first difference?

    hmac.compare_digest is the standard library's constant-time comparison;
    the byte check before it fails a bad value with the same words as the
    other languages.
    """
    left = _check_bytes(a, "a")
    right = _check_bytes(b, "b")
    return hmac.compare_digest(left, right)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python 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

Download for Python crypto.constant-time-equal-1.0.0-python.fune · 6,055 bytes sha256 b91f00e57c39a5f2d02300d93c341513dcb1fdd1112818a9eeaa325b7159074d

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

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.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

# fune: before crypto.constant-time-equal

after — your function gets the result and the arguments, and returns the final result.

# fune: after crypto.constant-time-equal

replace — it requires no other capability, so there is no dependency to replace.

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show crypto.constant-time-equal --steps.

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

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
two empty byte strings are equal	,	→	true
the same bytes	1, 2, 3, 1, 2, 3	→	true
the same 32-byte HMAC tag (RFC 4231 test case 1)	176, 52, 76, 97, 216, 219, 56, 83, 92, 168, 175, 206, 175, 11, 241, 43, 136, 29, 194, 0, 201, 131, 61, 167, 38, 233, 55, 108, 46, 50, 207, 247, 176, 52, 76, 97, 216, 219, 56, 83, …	→	true
a tag differing only in its last bit, which an early-exit compare finds last	176, 52, 76, 97, 216, 219, 56, 83, 92, 168, 175, 206, 175, 11, 241, 43, 136, 29, 194, 0, 201, 131, 61, 167, 38, 233, 55, 108, 46, 50, 207, 247, 176, 52, 76, 97, 216, 219, 56, 83, …	→	false
a tag differing in its first byte	176, 52, 76, 97, 216, 219, 56, 83, 92, 168, 175, 206, 175, 11, 241, 43, 136, 29, 194, 0, 201, 131, 61, 167, 38, 233, 55, 108, 46, 50, 207, 247, 48, 52, 76, 97, 216, 219, 56, 83, 9…	→	false
a prefix of the other is not equal	1, 2, 3, 1, 2	→	false
empty against non-empty	, 0	→	false
the same bytes in a different order	1, 2, 2, 1	→	false
zero bytes against no bytes: length counts	0, 0, 0	→	false
a value above 255 in the first argument	256, 0	→	error: a must be a list of integers from 0 to 255

Show the other 2 tests

Case	Arguments		Expected
a fraction in the second argument	1, 1.5	→	error: b must be a list of integers from 0 to 255
a boolean is not a byte	1, true	→	error: b must be a list of integers from 0 to 255

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

Path	Bytes
README.md	1,469
impl/python.py	862
impl/rust.rs	1,416
impl/typescript.ts	1,015
vectors.json	2,079