b3sum is a command-line tool designed for generating BLAKE3 cryptographic hashes of files or standard input. BLAKE3 is a modern hash function that offers significant performance improvements over traditional algorithms like MD5, SHA-1, SHA-2, and SHA-3 while maintaining robust security.
Key Features:
High Performance: BLAKE3 is much faster than older cryptographic hash functions, making it ideal for performance-critical applications.
Security: It is secure against length extension attacks, unlike SHA-2, and provides stronger resistance to collision attacks compared to MD5 and SHA-1.
Parallel Processing: Its Merkle tree design allows high parallelization across multiple threads and SIMD lanes, enabling efficient processing on modern hardware.
Versatile Use Cases: BLAKE3 serves as a cryptographic hash function, PRF (Pseudo-Random Function), MAC (Message Authentication Code), KDF (Key Derivation Function), and XOF (Extendable Output Function).
Cross-Architecture Support: Optimized for both x86-64 and smaller architectures, ensuring broad compatibility.
Audience & Benefit:
Ideal for developers, security professionals, and researchers who need a fast, secure, and versatile cryptographic tool. b3sum provides a reliable way to generate hashes for files or streams while benefiting from BLAKE3's advanced features, such as incremental updates and verified streaming. Its design ensures efficient performance across various hardware configurations.
b3sum can be installed via winget for easy setup on supported platforms.
README
BLAKE3
BLAKE3 is a cryptographic hash function that is:
Much faster than MD5, SHA-1, SHA-2, SHA-3, and BLAKE2.
Secure, unlike MD5 and SHA-1. And secure against length extension,
unlike SHA-2.
Highly parallelizable across any number of threads and SIMD lanes,
because it's a Merkle tree on the inside.
Capable of verified streaming and incremental updates, again
because it's a Merkle tree.
A PRF, MAC, KDF, and XOF, as well as a regular hash.
One algorithm with no variants, which is fast on x86-64 and also
on smaller architectures.
The chart below
is an example benchmark of 16 KiB inputs on a Cascade Lake-SP 8275CL server CPU
from 2019. For more detailed benchmarks, see the
BLAKE3 paper.
BLAKE3 is based on an optimized instance of the established hash
function BLAKE2 and on the original Bao tree
mode.
The specifications and design rationale are available in the BLAKE3
paper.
The default output size is 256 bits. The current version of
Bao implements verified streaming
with BLAKE3.
This repository is the official implementation of BLAKE3. It includes:
The blake3 Rust crate, which
includes optimized implementations for SSE2, SSE4.1, AVX2, AVX-512,
NEON, and WASM, with automatic runtime CPU feature detection on x86.
The rayon feature provides multithreading.
The b3sum Rust crate, which
provides a command line interface. It uses multithreading by default,
making it an order of magnitude faster than e.g. sha256sum on
typical desktop hardware.
The C implementation, which like the Rust implementation includes SIMD
optimizations (all except WASM), CPU feature detection on x86, and optional
multithreading. See .
The Rust reference implementation,
which is discussed in Section 5.1 of the BLAKE3
paper.
This implementation is much smaller and simpler than the optimized
ones above. If you want to see how BLAKE3 works, or you're writing a
port that doesn't need multithreading or SIMD optimizations, start
here. Ports of the reference implementation to other languages are
hosted in separate repositories
(C,
Python).
A set of test
vectors
that covers extended outputs, all three modes, and a variety of input
lengths.
NOTE: BLAKE3 is not a password hashing algorithm, because it's
designed to be fast, whereas password hashing should not be fast. If you
hash passwords to store the hashes or if you derive keys from passwords,
we recommend Argon2.
Usage
The b3sum utility
The b3sum command line utility prints the BLAKE3 hashes of files or of
standard input. Prebuilt binaries are available for Linux, Windows, and
macOS (requiring the unidentified developer
workaround)
on the releases page.
If you've installed Rust and
Cargo,
you can also build b3sum yourself with:
cargo install b3sum
If rustup didn't configure your PATH for you, you might need to go
looking for the installed binary in e.g. ~/.cargo/bin. You can test
out how fast BLAKE3 is on your machine by creating a big file and
hashing it, for example:
# Create a 1 GB file.
head -c 1000000000 /dev/zero > /tmp/bigfile
# Hash it with SHA-256.
time openssl sha256 /tmp/bigfile
# Hash it with BLAKE3.
time b3sum /tmp/bigfile
The blake3 crate
To use BLAKE3 from Rust code, add a dependency on the blake3 crate to
your Cargo.toml. Here's an example of hashing some input bytes:
// 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);
Besides hash, BLAKE3 provides two other modes, keyed_hash and
derive_key. The keyed_hash mode takes a 256-bit key:
// MAC an input all at once.
let example_key = [42u8; 32];
let mac1 = blake3::keyed_hash(&example_key, b"example input");
// MAC incrementally.
let mut hasher = blake3::Hasher::new_keyed(&example_key);
hasher.update(b"example input");
let mac2 = hasher.finalize();
assert_eq!(mac1, mac2);
The derive_key mode takes a context string and some key material (not a
password). The context string should be hardcoded, globally unique, and
application-specific. A good default format for the context string is
"[application] [commit timestamp] [purpose]":
// Derive a couple of subkeys for different purposes.
const EMAIL_CONTEXT: &str = "BLAKE3 example 2020-01-07 17:10:44 email key";
const API_CONTEXT: &str = "BLAKE3 example 2020-01-07 17:11:21 API key";
let input_key_material = b"usually at least 32 random bytes, not a password";
let email_key = blake3::derive_key(EMAIL_CONTEXT, input_key_material);
let api_key = blake3::derive_key(API_CONTEXT, input_key_material);
assert_ne!(email_key, api_key);
