Skip to main content

Crate sha3_kernel_hasher

Crate sha3_kernel_hasher 

Source
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:

  1. Absorb — The message is padded with domain byte 0x06 and the pad10*1 rule (FIPS 202, §6.1), split into 72-byte blocks, and each block is XORed into the state followed by Keccak-f[1600].
  2. 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

PropertySecurity (bits)
Collision resistance256
Preimage resistance512
Second preimage resistance512

SHA3 is structurally distinct from the Merkle-Damgård family and is immune to length-extension attacks (Kelsey and Schneier, 2005).

§Modules

ModuleDescription
hexSha3Digest wrapper with Display, LowerHex, UpperHex, hex encode/decode
ctConstant-time byte comparison (Bernstein, Lange and Schwabe, 2012)
ioStreaming std::io::Read adapter and hash_file convenience (std only)
kernel_safeProcessor state save/restore for kernel SIMD usage

§Compilation Modes

  • std (default) — Full standard library, runtime SIMD detection, io module enabled.
  • kernel — no_std + alloc for Windows kernel-mode drivers. The io module 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):

PathThroughputvs. scalar loop
scalar (one hash() per message)~182 MiB/s1.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 sha3 v0.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§

MemoryRegion
Memory region descriptor for kernel hashing.
PerformanceConfig
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)
SimdFeatures
SIMD feature detection results, as probed once via is_x86_feature_detected! and returned by Sha3_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)