Skip to main content

Crate purrdf_hash

Crate purrdf_hash 

Source
Expand description

purrdf-hash — PurRDF’s native, zero-dependency digests and table hasher.

ModuleAlgorithmSpecificationOutput
blake3BLAKE3 hash, keyed hash, key derivation and XOFBLAKE3 specification32 bytes or caller-selected length
md5MD5RFC 132116 bytes
sha1SHA-1FIPS 180-420 bytes
sha3SHA3-224, SHA3-256, SHA3-384, SHA3-512 and Keccak-f[1600]FIPS 20228 / 32 / 48 / 64 bytes
sha3SHAKE128, SHAKE256FIPS 202caller-selected byte length
crc32CRC-32/ISO-HDLCthe reflected polynomial 0xEDB88320a u32
fixedthe fixed-key table hasherthis crate (folded multiplies; AES rounds on AES builds)a u64
fnvFNV-1a, 64-bitFowler, Noll and Vo (draft-eastlake-fnv)a u64
mixthe SplitMix64 generator and finaliserSteele, 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 0x04C11DB7 processed bit-reflected (0xEDB88320), register initialised to 0xFFFFFFFF and the result complemented. The check value (the CRC of "123456789") is 0xCBF43926.
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 0x9E3779B97F4A7C15 and the finaliser that mixes a 64-bit word through two xor-shift-multiply rounds (multipliers 0xBF58476D1CE4E5B9 and 0x94D049BB133111EB, 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 Debug for a struct as the named fields and then ...
default_from_new
Implement Default as the type’s own no-argument new.
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 use patterns Pattern => cause arms.
error_visit
Implement an enum’s borrowed visitor through exhaustive producer patterns.
vector_backend
Declare a Backend family on the vector-ISA ladder every byte kernel of the workspace is compiled for: Portable, Sse2, Avx2, Neon and Simd128, preferred widest first (Avx2, Sse2, Neon, Simd128, then Portable), each named by its lowercase spelling.

Structs§

Domain
A hash domain: the byte string that names one preimage family.
SecretArray
An allocation-free owner whose complete array is overwritten on drop.

Constants§

MAX_OUTPUT_LEN
The longest output of any Digest in this crate (SHA3-512), so a caller dispatching through &mut dyn Digest can 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.