sha2_audit - xero/leviathan-crypto GitHub Wiki

Cryptographic audit of the leviathan-crypto WebAssembly SHA-2 implementation (AssemblyScript) against FIPS 180-4, covering SHA-224, SHA-256, SHA-384, and SHA-512.

Table of Contents

• 1. Algorithm Correctness
  • 1.1 Rotation and Shift Operations
  • 1.2 Logical Functions (Ch, Maj, Sigma, sigma)
  • 1.3 Constants
  • 1.4 Padding
  • 1.5 Message Schedule
  • 1.6 Compression Function
  • 1.7 Truncated Variants (SHA-224, SHA-384)
  • 1.8 Buffer Layout and Memory Safety
  • 1.9 TypeScript Wrapper Layer
  • 1.10 HMAC-SHA256 / HMAC-SHA512 / HMAC-SHA384
  • 1.11 HKDF-SHA256 / HKDF-SHA512
  • 1.12 NIST Test Vectors
• 2. Security Analysis
  • 2.1 Side-Channel Analysis
  • 2.2 Known Attacks on SHA-256 / SHA-512
  • 2.3 Usage Context in leviathan-crypto

SHA-256 (sha256.ts:149–152): We use AssemblyScript's built-in rotr<i32>(), which compiles directly to the WASM i32.rotr instruction—a single CPU instruction on all modern architectures. No manual shift-or patterns.

• rotr<i32>(x, n): right rotation. Equivalent to (x >>> n) | (x << (32 - n)).
• x >>> n: logical (unsigned) right shift (WASM i32.shr_u).

SHA-512 (sha512.ts:172): AssemblyScript has no built-in rotr<i64>(), so we define rotr64(x, n) as (x >>> n) | (x << (64 - n)) using i64 operands. This manual form compiles to efficient WASM i64 shift/or instructions.

• x >>> n on i64: logical right shift (WASM i64.shr_u).

Wraparound: SHA-256 arithmetic is on i32, which wraps natively at 2^32 in WASM with no masking. SHA-512 uses i64, wrapping natively at 2^64. Both are correct per FIPS 180-4 §2.2.1.

SHA-256 functions (sha256.ts:147–152):

SHA-512 functions (sha512.ts:175–184):

All rotation amounts are correct. SHA-256 and SHA-512 use different rotation constants—a detail that's easy to miss when copying between implementations. We define separate function sets for each variant. The code includes a prominent warning (sha512.ts:170): "DO NOT copy from SHA-256. The rotation constants are different."

All 64 SHA-256 K constants (sha256.ts:58–121) were independently verified by computing floor(frac(cbrt(prime[t])) * 2^32) for the first 64 primes using Python floating-point arithmetic. Every value matches FIPS 180-4 §4.2.2 exactly.

Spot check (first 8):

The kAt() function (sha256.ts:124–143) returns constants via a switch statement with a default: return K63 fallback. This is correct. The compression loop calls kAt(t) for t = 0..63, and the default case handles t = 63.

All 80 SHA-512 K constants (sha512.ts:57–136) were independently verified by computing floor(frac(cbrt(prime[t])) * 2^64) using Python Decimal with 50-digit precision. Every value matches FIPS 180-4 §4.2.3 exactly.

Spot check:

The kAt512() function (sha512.ts:139–162) mirrors the SHA-256 pattern with default: return K79.

All 8 SHA-256 IVs (sha256.ts:225–232) match FIPS 180-4 §5.3.3 exactly:

Verified by computing floor(frac(sqrt(prime[i])) * 2^32) for primes 2, 3, 5, 7, 11, 13, 17, 19.

All 8 SHA-512 IVs (sha512.ts:265–272) match FIPS 180-4 §5.3.5 exactly:

Verified by computing floor(frac(sqrt(prime[i])) * 2^64) with 50-digit Decimal precision.

All 8 SHA-384 IVs (sha512.ts:275–282) match FIPS 180-4 §5.3.4 exactly:

Verified by computing floor(frac(sqrt(prime[i])) * 2^64) for primes 23, 29, 31, 37, 41, 43, 47, 53 (the 9th through 16th primes). Note: SHA-384 IVs are the full 64-bit values from these primes, not related to the SHA-224 truncation pattern.

The implementation does not include a separate SHA-224 variant. The reference lists the SHA-224 IVs:

h0 = 0xc1059ed8    h1 = 0x367cd507
h2 = 0x3070dd17    h3 = 0xf70e5939
h4 = 0xffc00b31    h5 = 0x68581511
h6 = 0x64f98fa7    h7 = 0xbefa4fa4

These are the second (low) 32 bits of the SHA-384 IVs, verified independently. SHA-224 is not implemented in leviathan-crypto; this section is included for completeness only.

SHA-256 padding (sha256.ts:282–312, sha256Final()):

The two-block threshold is correct: after appending 0x80, if partial > 56, there is no room for the 8-byte length field in the remaining bytes [partial..63]. The implementation zeros the rest, compresses, then starts a fresh block with the length field.

The totalBytes counter is stored as i64 (SHA256_TOTAL_OFFSET, 8 bytes), supporting messages up to 2^64 bytes. The bit-length is computed as totalBytes << 3 (i64 shift), then split into high and low 32-bit words for big-endian storage. This correctly handles messages longer than 2^32 bytes.

SHA-512 padding (sha512.ts:349–381, sha512Final()):

The 128-bit length field is split into two 64-bit words: bitsHi captures the top 3 bits of the byte count (the bits that overflow when multiplying by 8), and bitsLo is the byte count left-shifted by 3. The >>> 61 is an unsigned right shift, which is correct for extracting the high bits.

Edge cases:

• Empty message: partial = 0 → append 0x80 at byte 0 → partial = 1 → not > 56 (SHA-256) / not > 112 (SHA-512) → zero fill → length field = 0 → single-block compress. Correct.
• 55-byte SHA-256 message: partial = 55 → append 0x80 at byte 55 → partial = 56 → not > 56 → memory.fill(..., 0, 56 - 56) (zero bytes) → length field at [56..63]. Single block. Correct.
• 56-byte SHA-256 message: partial = 56 → append 0x80 at byte 56 → partial = 57 → 57 > 56 → compress, new block, length field. Two blocks. Correct.

SHA-256 (sha256.ts:182–191):

for t = 0 to 15:   W[t] = load32be(blockOffset, t*4)
for t = 16 to 63:  W[t] = sigma1(W[t-2]) + W[t-7] + sigma0(W[t-15]) + W[t-16]

This matches FIPS 180-4 §6.2.2 exactly. The schedule words are loaded as big-endian 32-bit values via load32be(), and expanded using the sigma0/sigma1 functions verified in §1.2. Addition is mod 2^32 by native i32 arithmetic.

The schedule is stored in SHA256_W_OFFSET (256 bytes = 64 × 4 bytes) using big-endian encoding via store32be()/load32be(). This is consistent. Every access to the schedule goes through the same big-endian helpers.

SHA-512 (sha512.ts:222–231):

for t = 0 to 15:   W[t] = load64be(SHA512_BLOCK_OFFSET, t*8)
for t = 16 to 79:  W[t] = sigma1_512(W[t-2]) + W[t-7] + sigma0_512(W[t-15]) + W[t-16]

Matches FIPS 180-4 §6.4.2 exactly. Uses 64-bit operations, 80 rounds, and load64be()/store64be() for consistent big-endian storage. The schedule lives in SHA512_W_OFFSET (640 bytes = 80 × 8 bytes).

SHA-256 (sha256.ts:180–219):

The compression function implements FIPS 180-4 §6.2.2 steps 2–4:

Step 2: initialize working variables (sha256.ts:194–201):

a,b,c,d,e,f,g,h = load32be(SHA256_H_OFFSET, 0..28)

All 8 state words loaded from H buffer in big-endian format. Correct.

Step 3: 64 rounds (sha256.ts:204–209):

The 8-variable rotation is identical to the spec. The round count is hardcoded to 64 (for (let t = 0; t < 64; t++)).

Step 4: add-back (sha256.ts:212–219):

H[i] = H[i] + working_variable  (for i = 0..7)

Each state word is loaded from SHA256_H_OFFSET, added to the corresponding working variable, and stored back. Addition is mod 2^32 by i32 arithmetic. Correct.

SHA-512 (sha512.ts:220–260):

Structurally identical to SHA-256, with the following differences:

• 64-bit operands (i64) throughout
• 80 rounds (for (let t = 0; t < 80; t++))
• Uses Sigma0_512/Sigma1_512/sigma0_512/sigma1_512/Ch512/Maj512
• State at SHA512_H_OFFSET, schedule at SHA512_W_OFFSET
• load64be()/store64be() for memory access

All verified to match FIPS 180-4 §6.4. The round count of 80 is hardcoded.

SHA-384 (sha512.ts:386–391):

sha384Final() simply calls sha512Final(). The SHA-384 digest is the first 48 bytes (6 of 8 64-bit words) at SHA512_OUT_OFFSET. The TypeScript wrapper (src/ts/sha2/index.ts:153) reads only the first 48 bytes:

return mem.slice(this.x.getSha512OutOffset(), this.x.getSha512OutOffset() + 48);

This is correct: SHA-384 uses the same compression as SHA-512, with different IVs (verified in §1.3) and truncated output. The truncation happens after the full compression completes. No early truncation.

The sha384Init() function (sha512.ts:312–315) loads SHA-384-specific IVs via loadIVs(). These IVs are distinct from SHA-512's IVs, independently verified in §1.3.

SHA-224: Not implemented. The codebase provides SHA-256, SHA-384, and SHA-512 only. This is a design choice, not a deficiency; SHA-224 is rarely needed in modern applications.

The SHA-2 WASM module uses static buffer allocation in linear memory (buffers.ts):

Total: 1976 bytes. No gaps, no overlaps. All buffers are contiguous and tightly packed. The layout was verified programmatically: each buffer starts exactly where the previous one ends.

No aliasing: The message schedule W[] and hash state H[] occupy distinct, non-overlapping regions (SHA256_W at offset 96 vs SHA256_H at offset 0; SHA512_W at offset 812 vs SHA512_H at offset 620). No aliasing is possible.

No dynamic allocation: memory.grow() is never called. All offsets are compile-time constants exported from buffers.ts.

Endianness conversions: Both SHA-256 and SHA-512 store and load all multi-byte values in big-endian format using manual byte-level load<u8>/store<u8> helpers (load32be, store32be, load64be, store64be). This is consistent throughout. There are no mixed-endianness bugs. The helpers are correct:

• load32be: loads 4 bytes, shifts into MSB-first order. Correct.
• store32be: extracts bytes via >>> 24/16/8/0, masks with & 0xff. Correct.
• store64be (sha512.ts:202–212): uses arithmetic right shift (>>) instead of logical (>>>), but casts to u8. The low 8 bits are identical regardless of sign extension. Functionally correct.

wipeBuffers() (index.ts:42): memory.fill(0, 0, 1976). Zeros the entire 1976-byte buffer region. This covers all hash state, schedule, HMAC key material, ipad/opad, and intermediate values. Correct and complete.

The TypeScript classes in src/ts/sha2/index.ts provide the public API.

init() gate: Every class constructor calls getExports() → getInstance('sha2'), which throws if the sha2 module has not been loaded via init(['sha2']). No class can be used before initialization. Correct.

Input handling: feedHash() (index.ts:86–96):

function feedHash(x, msg, inputOff, chunkSize, updateFn) {
    const mem = new Uint8Array(x.memory.buffer);
    let pos = 0;
    while (pos < msg.length) {
        const n = Math.min(msg.length - pos, chunkSize);
        mem.set(msg.subarray(pos, pos + n), inputOff);
        updateFn(n);
        pos += n;
    }
}

This correctly chunks arbitrarily-large messages into chunkSize-byte segments (64 for SHA-256, 128 for SHA-512) and feeds each to the WASM update() function. The WASM streaming API handles partial-block accumulation internally.

Output is a copy: All hash/HMAC methods use mem.slice() (not mem.subarray()) to return the digest. slice() creates an independent copy. The returned Uint8Array does not alias WASM linear memory. If WASM memory is later zeroed by dispose() or overwritten by another operation, the caller's digest is unaffected. Correct.

dispose(): Every class calls this.x.wipeBuffers(), which zeros all 1976 bytes of SHA-2 module memory. Correct.

SHA256 class (index.ts:100–117): Calls sha256Init(), feeds via feedHash(..., 64, sha256Update), calls sha256Final(), returns 32 bytes from SHA256_OUT_OFFSET. Correct.

SHA512 class (index.ts:121–138): Same pattern with 128-byte chunks, returns 64 bytes. Correct.

SHA384 class (index.ts:140–159): Uses sha384Init(), feeds via sha512Update (SHA-384 shares SHA-512 buffers), calls sha384Final(), returns 48 bytes. Correct. This is the truncated output per FIPS 180-4 §6.5.

HMAC-SHA256 (hmac.ts):

The implementation follows RFC 2104 exactly:

HMAC(K, m) = H((K' XOR opad) || H((K' XOR ipad) || m))

hmac256Init(keyLen) (hmac.ts:63–79):

1. Reads key from SHA256_INPUT_OFFSET[0..keyLen-1]
2. XORs each key byte with 0x36 → HMAC256_IPAD_OFFSET, with 0x5c → HMAC256_OPAD_OFFSET
3. Zero-pads: remaining bytes get 0x36 / 0x5c (equivalent to 0x00 XOR ipad/opad)
4. Calls sha256Init() + feeds the 64-byte ipad block to start the inner hash

hmac256Final() (hmac.ts:88–101):

1. Finalizes inner hash → SHA256_OUT_OFFSET
2. Saves inner hash to HMAC256_INNER_OFFSET (prevents overwrite by step 3)
3. Starts outer hash: sha256Init() + feeds 64-byte opad block
4. Feeds 32-byte inner hash
5. Finalizes → SHA256_OUT_OFFSET contains the 32-byte HMAC tag

HMAC-SHA512 (hmac512.ts:71–109): Same structure with 128-byte block size, SHA-512 hash, 64-byte inner hash. Correct.

HMAC-SHA384 (hmac512.ts:119–156): Uses SHA-384 init/final (distinct IVs), but 128-byte block size (same as SHA-512). Inner hash is 48 bytes. The implementation copies only 48 bytes at hmac384Final() step 2 (memory.copy(HMAC512_INNER_OFFSET, SHA512_OUT_OFFSET, 48)). The outer hash feeds this 48-byte value. Output is 48 bytes. Correct per RFC 2104 with SHA-384.

Long key handling (TypeScript layer): The HMAC_SHA256 class (index.ts:169–186) pre-hashes keys > 64 bytes via sha256Init/feedHash/sha256Final before calling hmac256Init(32). RFC 2104 §3: "If the length of K > B, then first hash K using H and then use the resulting L-byte string." Correct. HMAC_SHA512 uses the 128-byte threshold with SHA-512 pre-hash. HMAC_SHA384 uses the 128-byte threshold with SHA-384 pre-hash. All correct.

Both HKDF classes (hkdf.ts) implement RFC 5869 as pure TypeScript composition over the HMAC classes.

HKDF-SHA256 (hkdf.ts:31–75):

• Extract (§2.2): PRK = HMAC-SHA256(salt, IKM). If salt is null or empty, defaults to new Uint8Array(32) (32 zero bytes). Correct. RFC 5869 §2.1: "if not provided, [salt] is set to a string of HashLen zeros."
• Expand (§2.3): Iterates T(i) = HMAC-SHA256(PRK, T(i-1) || info || i) for i = 1..N, where N = ceil(L/32). Validates PRK is 32 bytes, length is 1..255*32. Correct.

HKDF-SHA512 (hkdf.ts:79–123): Same structure with 64-byte hash length, 64-byte default salt, PRK must be 64 bytes, max length 255*64. Correct.

Both classes delegate to the already-verified HMAC implementations. No cryptographic computation occurs in the HKDF TypeScript code. Only concatenation and loop control.

All variants verified against NIST FIPS 180-4 known-answer test vectors and Python hashlib:

SHA-2 uses only add, rotate, XOR, AND, OR, and NOT operations. No table lookups. Unlike AES, there are no S-boxes that would create cache-timing side channels. The entire compression function is a fixed sequence of arithmetic operations with no data-dependent branches.

WASM execution model: As noted in the Serpent audit, WASM integer operations (i32.and, i32.xor, i32.rotr, i64.add, etc.) have fixed-width semantics compiled ahead-of-time. JIT speculative optimizations do not apply to WASM. The uniform, branch-free compression loop provides constant-time properties that are as strong as a browser execution environment can offer.

No data-dependent branches in the compression loop: The SHA-256 compression (sha256.ts:204–209) runs exactly 64 iterations unconditionally. The SHA-512 compression (sha512.ts:244–249) runs exactly 80 iterations. No iteration is skipped or short-circuited based on data values.

SHA-256 and SHA-512 are vulnerable to length extension: given H(m) and len(m), an attacker can compute H(m || padding || m') without knowing m. This is a structural property of the Merkle-Damgard construction, not an implementation bug.

Assessment for leviathan-crypto: The codebase never uses raw SHA-256/SHA-512 for MAC purposes (see §2.3). All authentication tags are computed via HMAC, which is immune to length extension by construction (HMAC(K, m) = H((K' XOR opad) || H((K' XOR ipad) || m)). The outer hash prevents extension of the inner hash.

The one usage of raw SHA-256 outside HMAC is in Fortuna (src/ts/fortuna.ts), which uses it for internal state chaining (SHA256(genKey || seed) and SHA256(poolHash || id || data)). These are not MAC constructions. The hash inputs and outputs are internal state; the library never exposes them to an attacker. The Fortuna design (Ferguson & Schneier) deliberately uses raw SHA-256 for this purpose.

Verdict: No length extension vulnerability exists in any externally-observable construction.

Best known collision attack on full SHA-256: none practical. The best theoretical result reaches approximately 38 of 64 rounds (Mendel et al., 2011). Full 64-round SHA-256 retains a 26-round security margin against collision attacks, providing the full 128-bit collision resistance expected of a 256-bit hash.

SHA-512: no collision attack beyond birthday-bound complexity (2^256) is known for the full 80 rounds.

Best known preimage attack on SHA-256: 52 of 64 rounds (Aoki & Sasaki, 2009) with 2^251.7 complexity. No practical threat. Full SHA-256 provides the expected 256-bit preimage resistance.

SHA-512: best known preimage attacks reach fewer rounds with even higher complexity. No practical concern.

SHA-384 truncates SHA-512's output from 512 to 384 bits. Truncation does not reduce collision resistance below the output length: SHA-384 provides 192-bit collision resistance (birthday bound on 384-bit output). This exceeds any practical attack threshold. SHA-384 also uses distinct IVs from SHA-512 (verified in §1.3), ensuring that SHA384(m) != truncate(SHA512(m)). Domain separation is maintained.

A comprehensive search of the codebase identified all SHA-2 usage outside the core SHA-2 module:

Key findings:

1. No raw SHA-2 used for MAC. The library computes every authentication tag via HMAC-SHA256 or HMAC-SHA512. Length extension is not a concern.

2. No key reuse across constructions. SerpentSeal splits its 64-byte key into a 32-byte encryption key and a 32-byte MAC key. SerpentCipher uses HKDF to derive separate keys (enc_key, mac_key, iv_key). No context shares a key for both hashing and another purpose.

3. Fortuna's raw SHA-256 usage is by design. The CSPRNG uses SHA256(genKey || seed) for rekeying and SHA256(poolHash || id || data) for pool chaining. These follow the published Fortuna specification (Ferguson & Schneier, "Practical Cryptography"). The hash outputs are internal state, never exposed to callers. An attacker cannot mount a length extension attack because they never see the intermediate hash values.

4. HKDF usage is correct. Both HKDF-SHA256 and HKDF-SHA512 follow RFC 5869 with proper extract-then-expand. The extract step uses HMAC (not raw hash), so salt+IKM processing is immune to length extension.