Crate blake3

source ·
Expand description

The official Rust implementation of the BLAKE3 cryptographic hash function.

§Examples

// Hash an input all at once.
let hash1 = blake3::hash(b"foobarbaz");

// Hash an input incrementally.
let mut hasher = blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
let hash2 = hasher.finalize();
assert_eq!(hash1, hash2);

// Extended output. OutputReader also implements Read and Seek.
let mut output = [0; 1000];
let mut output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(hash1, output[..32]);

// Print a hash as hex.
println!("{}", hash1);

§Cargo Features

The std feature (the only feature enabled by default) is required for implementations of the Write and Seek traits, the update_reader helper method, and runtime CPU feature detection on x86. If this feature is disabled, the only way to use the x86 SIMD implementations is to enable the corresponding instruction sets globally, with e.g. RUSTFLAGS="-C target-cpu=native". The resulting binary will not be portable to other machines.

The rayon feature (disabled by default, but enabled for docs.rs) adds the update_rayon and (in combination with mmap below) update_mmap_rayon methods, for multithreaded hashing. However, even if this feature is enabled, all other APIs remain single-threaded.

The mmap feature (disabled by default, but enabled for docs.rs) adds the update_mmap and (in combination with rayon above) update_mmap_rayon helper methods for memory-mapped IO.

The zeroize feature (disabled by default, but enabled for docs.rs) implements Zeroize for this crate’s types.

The serde feature (disabled by default, but enabled for docs.rs) implements serde::Serialize and serde::Deserialize for Hash.

The NEON implementation is enabled by default for AArch64 but requires the neon feature for other ARM targets. Not all ARMv7 CPUs support NEON, and enabling this feature will produce a binary that’s not portable to CPUs without NEON support.

The traits-preview feature enables implementations of traits from the RustCrypto digest crate, and re-exports that crate as traits::digest. However, the traits aren’t stable, and they’re expected to change in incompatible ways before that crate reaches 1.0. For that reason, this crate makes no SemVer guarantees for this feature, and callers who use it should expect breaking changes between patch versions. (The “-preview” feature name follows the conventions of the RustCrypto signature crate.)

Structs§

Constants§

Functions§