Crate blake3

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.)

Modules

traits

Implementations of commonly used traits like Digest and Mac from the digest crate.

Structs

Hash

An output of the default size, 32 bytes, which provides constant-time equality checking.

Hasher

An incremental hash state that can accept any number of writes.

HexError

The error type for Hash::from_hex.

OutputReader

An incremental reader for extended output, returned by Hasher::finalize_xof.

Constants

KEY_LEN

The number of bytes in a key, 32.

OUT_LEN

The number of bytes in a Hash, 32.

Functions

derive_key

The key derivation function.

hash

The default hash function.

keyed_hash

The keyed hash function.