feat(stdlib): Crypto.* — SHA-256 + HMAC-SHA256, constant-time verify (#19)
All checks were successful
docs / build-and-deploy (push) Successful in 3s
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:
parent
1858ab65ad
commit
9ae69e64b4
15 changed files with 11536 additions and 10437 deletions
27
docs/language/crypto/crypto-ct_equal.md
Normal file
27
docs/language/crypto/crypto-ct_equal.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
id: crypto-ct_equal
|
||||
name: Crypto.ct_equal
|
||||
category: crypto
|
||||
kind: namespace-method
|
||||
tokens: Crypto.ct_equal
|
||||
sig: Crypto.ct_equal(a, b) -> bool
|
||||
tip: Constant-time string equality for secrets.
|
||||
order: 5
|
||||
ns: Crypto
|
||||
member: ct_equal
|
||||
---
|
||||
|
||||
Compares two strings for equality without short-circuiting: every character is examined even once a difference is found, so the time taken does not reveal where — or whether — the strings first diverged. Reach for it whenever you compare a secret, token, or MAC that an attacker might be probing. For the common case of checking a message tag, <a href="crypto-verify_hmac"><code>Crypto.verify_hmac</code></a> already does this for you; use <code>ct_equal</code> directly when you hold both values yourself. Strings of different length return <code>false</code> at once (length is not secret). For ordinary, non-secret text just use <code>==</code> — the constant-time guarantee is not free.
|
||||
|
||||
Parameters:
|
||||
- `a` — one string
|
||||
- `b` — the other string
|
||||
|
||||
```ludic
|
||||
program CompareToken {
|
||||
entry {
|
||||
if Crypto.ct_equal("abc", "abc") { print(1) } else { print(0) } # 1
|
||||
if Crypto.ct_equal("abc", "abd") { print(1) } else { print(0) } # 0
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue