BLAKE3 is a cryptographic hash function that is:
The chart below shows BLAKE3's performance on modern server hardware, an Intel Cascade Lake-SP 8275CL processor:
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 SIMD implementations, with runtime CPU feature
detection on x86. SSE4.1 and AVX2 are supported in pure Rust. The c
feature enables C/assembly implementations and AVX-512 support. The
c_neon feature enables ARM NEON support. Multi-threading is also
supported, and the rayon feature provides a
Rayon-based implementation.
The b3sum Rust crate, which
provides a command line interface. You can install it from
crates.io with cargo install
b3sum. It enables the rayon and c features of the blake3 crate
by default.
The C implementation, which like the Rust implementation includes SIMD code and dynamic CPU feature detection on x86. Unlike the Rust implementation, it's not currently multi-threaded. The README provides build examples.
The 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 multi-threading or SIMD optimizations, start here.
BLAKE3 was designed by:
The development of BLAKE3 was sponsored by Teserakt and Electric Coin Company.
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.
b3sum utilityThe b3sum utility allows you to process files and data from standard
input using BLAKE3 in any of its three modes.
To use b3sum on the command line, install Rust and
Cargo,
and then run:
bash
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 as follows:
```bash
head -c 1000000000 /dev/zero > /tmp/bigfile
time openssl sha256 /tmp/bigfile
time b3sum /tmp/bigfile ```
blake3 crateTo 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:
```rust // 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 outputreader = hasher.finalizexof(); outputreader.fill(&mut output); asserteq!(&output[..32], hash1.as_bytes()); ```
Besides hash, BLAKE3 provides two other modes, keyed_hash and
derive_key. The keyed_hash mode takes a 256-bit key:
```rust // MAC an input all at once. let examplekey = [42u8; 32]; let mac1 = blake3::keyedhash(&example_key, b"example input");
// MAC incrementally. let mut hasher = blake3::Hasher::newkeyed(&examplekey); hasher.update(b"example input"); let mac2 = hasher.finalize(); assert_eq!(mac1, mac2); ```
The derive_key mode takes a context string of any length and key
material of any length, and it outputs a derived key of any length. The
context string should be hardcoded, globally unique, and
application-specific. A good default format for the context string is
"[application] [commit timestamp] [purpose]":
rust
// 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 = b"some very secret key material (>'-')> <('-'<) ^('-')^";
let mut email_key = [0; 32];
blake3::derive_key(EMAIL_CONTEXT, input_key, &mut email_key);
let mut api_key = [0; 32];
blake3::derive_key(API_CONTEXT, input_key, &mut api_key);
assert!(email_key != api_key);
Please see CONTRIBUTING.md.
The Rust code is copyright Jack O'Connor, 2019-2020. The C code is copyright Samuel Neves and Jack O'Connor, 2019-2020.
This work is released into the public domain with CC0 1.0. Alternatively, it is licensed under the Apache License 2.0.