Expand description
purrdf-hash — PurRDF’s native, zero-dependency digests and table hasher.
| Module | Algorithm | Specification | Output |
|---|---|---|---|
blake3 | BLAKE3 hash, keyed hash, key derivation and XOF | BLAKE3 specification | 32 bytes or caller-selected length |
md5 | MD5 | RFC 1321 | 16 bytes |
sha1 | SHA-1 | FIPS 180-4 | 20 bytes |
sha3 | SHA3-224, SHA3-256, SHA3-384, SHA3-512 and Keccak-f[1600] | FIPS 202 | 28 / 32 / 48 / 64 bytes |
sha3 | SHAKE128, SHAKE256 | FIPS 202 | caller-selected byte length |
crc32 | CRC-32/ISO-HDLC | the reflected polynomial 0xEDB88320 | a u32 |
fixed | the fixed-key table hasher | this crate (folded multiplies; AES rounds on AES builds) | a u64 |
fnv | FNV-1a, 64-bit | Fowler, Noll and Vo (draft-eastlake-fnv) | a u64 |
mix | the SplitMix64 generator and finaliser | Steele, Lea and Flood (OOPSLA 2014) | a u64 |
frame is the workspace’s length framing: a variable-length field as its
length in eight little-endian bytes and then its bytes, appended to a
buffer (frame::frame_le) or streamed into a Digest
(frame::frame_le_into).
fixed::hash_one is the table hash of one value. debug_non_exhaustive!,
default_from_new! and vector_backend! are the trait impls every type of
one shape shares — a Debug of some fields, a Default that is new, a
kernel-path family on the vector-ISA ladder — each spelled once for the
workspace, which reaches this root from every crate.
Domain is the one spelling of a hash domain-separation string: every
domain the workspace hashes under is a registered Domain constant, unique
and prefix-free across the workspace, and never renamed once published.
hex is the workspace’s base16 (RFC 4648 §8) codec: hex::Lower and
hex::Upper render any byte string through Display without
allocating, hex::decode and its canonical-lowercase siblings read it
back with a typed error, hex::nibble reads one digit, and
hex::Digest32 is the 32-byte value every content identity wraps.
Every fixed-output hasher has a one-shot associated function
(Md5::digest(data)) and a streaming form (new, update, finalize);
both give the same answer for every way of splitting the input. Every
fixed-output hasher also implements the object-safe Digest trait, so a
caller can choose an algorithm at run
time and drive it through &mut dyn Digest.
SHAKE uses sha3::Shake128 or sha3::Shake256 instead: update
streams input, finalize consumes the absorber, and the returned reader’s
squeeze continues its output across arbitrary caller-owned buffers.
wipe_secret is the workspace’s single safe-Rust clearing home.
SecretArray owns allocation-free guarded arrays, clearing their complete
storage at explicit last use and on drop. SHAKE buffers and lanes use it;
caller-owned and historical compiler copies remain outside its ownership.
§Hardware paths
SHA-1 runs on the x86 SHA extensions or the Armv8 SHA1 instructions, and
CRC-32 on pclmulqdq carry-less-multiply folding or the Armv8 CRC32
instructions, whenever the processor reports them at run time; otherwise
the portable code runs. Every path computes the same bytes. MD5 is a single
serial dependency chain and SHA-3’s Keccak-f[1600] needs 64-bit lane
rotates most vector units lack, so both are portable scalar code. Base16
encoding is a compare-select loop the compiler packs on every vector
target; inputs longer than a digest run SSSE3 pshufb on x86-64 below
AVX-512BW, NEON tbl on AArch64, and wasm i8x16.swizzle when the build
enables simd128.
The table hasher fixed::FixedHasher is the exception to run-time
selection. It uses an AES accumulator when the build’s target enables
AES (x86-64 or little-endian AArch64).
Otherwise it uses folded multiplies, on wasm32 and 32-bit targets too.
Each build therefore has exactly one table-hash function, and that
function is not the same on every build. A table hash is never persisted.
§Scope
Pure integer arithmetic over caller-supplied bytes: no threads, no
filesystem, no clock and no entropy (the table hasher’s keys are
compile-time constants), so the crate builds for wasm32-unknown-unknown.
Hashing never allocates; the base16 functions that return an owned
String or Vec<u8> (hex::encode, hex::decode, …) allocate that
value and nothing else. The one exception is test-harness support, never
reached by a hashing path: dispatch’s requirement check reads the
PURRDF_REQUIRE_SIMD_PATHS environment variable and Linux
/proc/cpuinfo.
The crate has zero dependencies and is the root of the workspace’s crate
layering: every crate may depend on it. Besides the digests it holds the
small specified kernels shared across the workspace (fnv, mix,
frame) and the Backend trait every family of named execution paths implements. MD5 and SHA-1 are provided because protocols
name them (SPARQL’s MD5()/SHA1(), OpenPGP v4 fingerprints), not as
security primitives: both are broken for collision resistance.
Re-exports§
pub use dispatch::Backend;
Modules§
- blake3
- BLAKE3 hashing, keyed hashing, key derivation and extendable output (§2.1–2.6).
- crc32
- CRC-32/ISO-HDLC: the polynomial
0x04C11DB7processed bit-reflected (0xEDB88320), register initialised to0xFFFFFFFFand the result complemented. The check value (the CRC of"123456789") is0xCBF43926. - dispatch
- Named execution paths, and the one requirement a test harness reads about them.
- error
- Borrowed error inspection, independent of human presentation.
- fixed
- A fixed-key, non-cryptographic hasher for in-memory tables.
- fnv
- FNV-1a, 64-bit (Fowler, Noll and Vo; the IETF draft
draft-eastlake-fnv): for each byte, XOR it into the state, then multiply the state by the FNV prime modulo 2^64, starting from the offset basis. - frame
- Length framing: the one way a variable-length field enters a preimage or a wire encoding.
- hex
- Base16 (RFC 4648 §8): the workspace’s one hex encoder, decoder and digit reader, and the 32-byte digest value every content identity is.
- md5
- MD5 (RFC 1321).
- mix
- SplitMix64 (Steele, Lea and Flood, “Fast Splittable Pseudorandom Number
Generators”, OOPSLA 2014): the golden-ratio increment
0x9E3779B97F4A7C15and the finaliser that mixes a 64-bit word through two xor-shift-multiply rounds (multipliers0xBF58476D1CE4E5B9and0x94D049BB133111EB, shifts 30, 27 and 31) and a final xor-shift. - multiset
- Reversible accounting for multisets of 256-bit member digests.
- sha1
- SHA-1 (FIPS 180-4).
- sha3
- SHA3-224/256/384/512 and SHAKE128/256 over the shared Keccak-f[1600] permutation (FIPS 202).
- word_id
- Checked, reversible word references over
Digest32.
Macros§
- debug_
non_ exhaustive - Implement
Debugfor a struct as the named fields and then... - default_
from_ new - Implement
Defaultas the type’s own no-argumentnew. - error_
sources - Implement the standard error source chain from single-field enum variants
or a native-cause accessor (
error_sources!(Type, native accessor)). Other enum variants have no underlying error. The original cause is borrowed without rendering, cloning or type erasure beyond the Error trait. Named fields and nested variants usepatterns Pattern => causearms. - error_
visit - Implement an enum’s borrowed visitor through exhaustive producer patterns.
- vector_
backend - Declare a
Backendfamily on the vector-ISA ladder every byte kernel of the workspace is compiled for:Portable,Sse2,Avx2,NeonandSimd128, preferred widest first (Avx2,Sse2,Neon,Simd128, thenPortable), each named by its lowercase spelling.
Structs§
- Domain
- A hash domain: the byte string that names one preimage family.
- Secret
Array - An allocation-free owner whose complete array is overwritten on drop.
Constants§
- MAX_
OUTPUT_ LEN - The longest output of any
Digestin this crate (SHA3-512), so a caller dispatching through&mut dyn Digestcan finalize into a stack buffer.
Traits§
- Digest
- A streaming hash function, usable as
&mut dyn Digest.
Functions§
- wipe_
secret - Overwrite every slot, observe the stores and fence before deallocation.