Expand description
§SHA3-Kernel-Hasher
Production-grade SHA3-512 (FIPS 202) in pure Rust with dual-mode compilation for userspace and Windows kernel drivers.
§Overview
This crate provides a self-contained implementation of the SHA3-512
cryptographic hash function as standardised in FIPS PUB 202 (National
Institute of Standards and Technology, 2015). It includes the complete
Keccak-f[1600] permutation, correct SHA3 domain separation and
pad10*1 padding, an incremental (streaming) API, and helper modules
for hex encoding, constant-time comparison, and I/O-based hashing.
§Algorithm
SHA3-512 is built on the sponge construction (Bertoni et al., 2011) operating on a 1600-bit state partitioned into a 576-bit rate (r) and a 1024-bit capacity (c). The construction proceeds in two phases:
- Absorb — The message is padded with domain byte
0x06and thepad10*1rule (FIPS 202, §6.1), split into 72-byte blocks, and each block is XORed into the state followed by Keccak-f[1600]. - Squeeze — The first 512 bits (64 bytes) of the post-absorb state are extracted as the digest.
The Keccak-f[1600] permutation applies 24 rounds, each consisting of five step mappings — θ (theta), ρ (rho), π (pi), χ (chi), and ι (iota) — to a 5×5 matrix of 64-bit lanes.
§Security Properties
| Property | Security (bits) |
|---|---|
| Collision resistance | 256 |
| Preimage resistance | 512 |
| Second preimage resistance | 512 |
SHA3 is structurally distinct from the Merkle-Damgård family and is immune to length-extension attacks (Kelsey and Schneier, 2005).
§Modules
| Module | Description |
|---|---|
hex | Sha3Digest wrapper with Display, LowerHex, UpperHex, hex encode/decode |
ct | Constant-time byte comparison (Bernstein, Lange and Schwabe, 2012) |
io | Streaming std::io::Read adapter and hash_file convenience (std only) |
kernel_safe | Processor state save/restore for kernel SIMD usage |
§Compilation Modes
std(default) — Full standard library, runtime SIMD detection,iomodule enabled.kernel—no_std+allocfor Windows kernel-mode drivers. Theiomodule is disabled; SIMD defaults to scalar.
§SIMD Status
Runtime detection probes for AVX-512F/BW/DQ, AVX2+BMI2, and SSE4.2 via
is_x86_feature_detected!, and is exposed through SimdFeatures and
Sha3_512Kernel::simd_features so a caller can query what the current
CPU supports.
AVX-512 single-message permutation (std + x86_64 only): real,
not a stub. Setting PerformanceConfig::use_avx512 to true
dispatches every Keccak-f[1600] call in hash()/update()/
finalize() to a vectorized implementation (src/simd_avx512.rs)
when the CPU supports AVX-512F, cross-validated bit-for-bit against
the scalar implementation (zero state, 2000 random states, 50 chained
permutations, and the same XKCP known-answer values the scalar tests
check). It defaults to false because it is not a measured
throughput win: cargo bench --bench sha3_bench on this container’s
Xeon shows the AVX-512 path within noise of scalar at 64 KiB payloads,
~3-4% slower at 1 MiB, and ~10% slower at 4 KiB. A single
Keccak-f[1600] instance has no independent lanes for one 512-bit
register to exploit — π’s cross-row mixing needs real shuffle/blend
instructions (originally a memory-gather, which measured ~25-30%
slower still; see simd_avx512’s module docs for that history) that
scalar code simply doesn’t pay for. This matches the wider Keccak-SIMD
literature: single-instance vectorization is rarely profitable —
real throughput gains come from hashing multiple independent messages
in parallel, which is exactly what Sha3_512Kernel::hash_many does.
Multi-message batching (hash_many, std + x86_64 only): a real
win. Sha3_512Kernel::hash_many hashes a batch of independent
messages using the SIMD-parallel permutations in src/simd_parallel.rs
— independent messages give the vector width actual parallel work,
unlike single-message hashing above. Measured end to end
(cargo bench --bench sha3_bench sha3_512_hash_many, 64 independent
4 KiB messages, this container’s Xeon):
| Path | Throughput | vs. scalar loop |
|---|---|---|
scalar (one hash() per message) | ~182 MiB/s | 1.0x |
| AVX2×4 batching | ~220 MiB/s | ~1.2x |
| AVX-512×8 batching | ~1004 MiB/s | ~5.5x |
AVX-512×8 is a genuine, substantial win — 8 independent messages
give an 8-lane register real parallel work with no gather/shuffle
needed (ρ+π reduce to array indexing plus a uniform per-register
rotate — see simd_parallel’s module docs for why this layout is so
much more favorable than single-message vectorization). AVX2×4 is
correct and a modest win, but far short of AVX-512: AVX2 has no
64-bit rotate instruction, so ρ is emulated as shift-left +
shift-right + or, which eats most of the 4-way parallelism’s benefit.
Both are controlled by the same
PerformanceConfig::use_avx512/PerformanceConfig::use_avx2
flags as hash(); when neither applies, hash_many falls back to
hashing each message individually via the scalar path.
prefetch_data, parallel_chunks, and chunk_size remain no-ops.
§Correctness Validation
- NIST CAVP SHA3-512 test vectors (empty,
0xCC,0x41FB,0xA3×200) - XKCP Keccak-f[1600] known-answer tests (lanes 0–4)
- Cross-validated against RustCrypto
sha3v0.10 for 20 input lengths - Incremental vs. one-shot, determinism, avalanche, boundary conditions
§Quick Start
use sha3_kernel_hasher::{Sha3_512Kernel, Sha3Digest};
let mut hasher = Sha3_512Kernel::new();
// One-shot with typed digest
let digest: Sha3Digest = hasher.hash_digest(b"hello");
println!("{}", digest);
// Incremental hashing
hasher.reset();
hasher.update(b"hello");
hasher.update(b" world");
let digest = hasher.finalize_digest();
println!("{:X}", digest);§References
- Bertoni, G. et al. (2011) The Keccak Reference, v3.0. https://keccak.team/files/Keccak-reference-3.0.pdf
- NIST (2015) SHA-3 Standard. FIPS PUB 202. doi:10.6028/NIST.FIPS.202
- Bernstein, D.J. (2005) Cache-timing attacks on AES. https://cr.yp.to/antiforgery/cachetiming-20050414.pdf
- Bernstein, D.J., Lange, T. and Schwabe, P. (2012) ‘The Security Impact of a New Cryptographic Library’, LATINCRYPT 2012, LNCS 7533, pp. 159–176.
- Kelsey, J. and Schneier, B. (2005) ‘Second Preimages on n-Bit Hash Functions for Much Less than 2^n Work’, EUROCRYPT 2005, LNCS 3494, pp. 474–490.
- Kocher, P.C. (1996) ‘Timing Attacks on Implementations of Diffie-Hellman, RSA, DSS, and Other Systems’, CRYPTO ’96, LNCS 1109, pp. 104–113.
Re-exports§
pub use hex::Sha3Digest;
Modules§
- benchmarks
- Criterion benchmark harness for
cargo bench --features benchmarks. - ct
- Constant-Time Comparison for SHA3-512 Digests
- hex
- Hexadecimal Encoding Utilities for SHA3-512 Digests
- kernel_
safe - Kernel-safe memory operations
Structs§
- Memory
Region - Memory region descriptor for kernel hashing.
- Performance
Config - Performance configuration for hasher.
- Sha3_
512Kernel - SHA3-512 kernel hasher with SIMD optimisation
- Sha3_
512State - SHA3-512 sponge state (64-byte aligned for SIMD compatibility)
- Simd
Features - SIMD feature detection results, as probed once via
is_x86_feature_detected!and returned bySha3_512Kernel::simd_features.
Constants§
- DEFAULT_
CHUNK_ SIZE - Default chunk size for parallel processing
- MAX_
HASH_ SIZE - Maximum safe hash size for kernel operations (256 MiB)
Type Aliases§
- Sha3_
512Hash - Hash result type — 64 bytes (512 bits)