feat(stdlib): Crypto.* — SHA-256 + HMAC-SHA256, constant-time verify (#19)
All checks were successful
docs / build-and-deploy (push) Successful in 3s

The security-sensitive counterpart to the fast, non-cryptographic Hash.*
library: standard, test-vector-backed hashing for signed saves and message
integrity, kept in its own namespace so nobody reaches for the wrong tool.

  Crypto.sha256(s)                SHA-256 -> 64-char lowercase hex
  Crypto.hmac_sha256(key, msg)    HMAC-SHA256 -> 64-char hex
  Crypto.verify_hmac(key, msg, mac)  recompute + constant-time compare -> bool
  Crypto.hex(s)                   lowercase hex of a string's bytes
  Crypto.ct_equal(a, b)           constant-time string equality

The primitives are implemented from scratch in plain integer LLVM IR
(FIPS 180-4 / RFC 2104): no libc crypto, no data-dependent branches in the
compression rounds, so a given input hashes to the same 32 bytes on every
platform and run. Digests are returned as hex strings, not raw bytes, because
a `str` is null-terminated and a raw digest can contain a NUL. MAC checks use
a non-short-circuiting compare so timing does not leak how much of a forged tag
was correct.

Emitted on demand via g_uses_cryptort, mirroring the emit_hash prelude gate.
Scoped to the deterministic, known-answer-testable core; OS-backed
random_bytes (the one piece that can't be validated by test vectors) is left
for a follow-up.

Tested against published SHA-256 vectors (empty/"abc"/fox + 55/56/64-byte
multi-block padding) and HMAC-SHA256 vectors; wired into the self-host suite as
`crypto`. Docs: a new Crypto section with honest "what this protects / does
not" guidance, one page per method, all fences checked and in the inventory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-08-30 13:37:02 +03:00
parent 1858ab65ad
commit 9ae69e64b4
15 changed files with 11536 additions and 10437 deletions

View file

@ -0,0 +1,34 @@
---
id: crypto-verify_hmac
name: Crypto.verify_hmac
category: crypto
kind: namespace-method
tokens: Crypto.verify_hmac
sig: Crypto.verify_hmac(key, msg, mac) -> bool
tip: Constant-time check that a MAC matches.
order: 3
ns: Crypto
member: verify_hmac
---
Recomputes HMAC-SHA256(<code>key</code>, <code>msg</code>) and compares it to the supplied <code>mac</code> hex string, returning <code>true</code> only if they match. The comparison is <em>constant-time</em>: it never stops early on the first differing character, so it does not leak — through how long the check took — how many leading bytes of a forged tag happened to be right. That leak is exactly what lets an attacker guess a MAC one byte at a time, which is why you should always verify with this and never with <code>==</code>. A mismatched length returns <code>false</code> immediately (the length of a MAC is not a secret).
Parameters:
- `key` — the shared secret used to sign
- `msg` — the payload as received
- `mac` — the hex tag to check, e.g. from <a href="crypto-hmac_sha256"><code>Crypto.hmac_sha256</code></a>
```ludic
program CheckSave {
entry {
let key = "s3cret"
let payload = "score=9001;level=12"
let mac = Crypto.hmac_sha256(key, payload)
if Crypto.verify_hmac(key, payload, mac) {
print(1) # untampered
} else {
print(0) # altered or forged
}
}
}
```