BLAKE3

https://docs.rs/blake3/latest/
Admin
The official Rust implementation of the BL BLAKE3 cryptographic hash function, providing incremental...
Tokens:131,757
Snippets:1,063
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Hash Standard Input Example

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Demonstrates how to hash standard input using `update_reader`. This example requires the `std` feature to be enabled.

```rust
# use std::fs::File;
# use std::io;
# fn main() -> io::Result<()> {
# // Hash standard input.
# let mut hasher = blake3::Hasher::new();
# hasher.update_reader(std::io::stdin().lock())?;
# println!("{}", hasher.finalize());
# Ok(())
# }

```

--------------------------------

### derive_key Usage Example

Source: https://docs.rs/blake3/latest/blake3/fn.derive_key.html

An example demonstrating the usage of the derive_key function and its equivalent using the Hasher API.

```APIDOC
let key = blake3::derive_key(CONTEXT, b"key material, not a password");

let key: [u8; 32] = blake3::Hasher::new_derive_key(CONTEXT)
    .update(b"key material, not a password")
    .finalize()
    .into();
```

--------------------------------

### Example: Computing Interior Hashes in a 3-Chunk Tree

Source: https://docs.rs/blake3/latest/blake3/hazmat/index.html

Demonstrates how to compute the chaining values for individual chunks and merge them to form parent nodes, culminating in the final root hash. This example highlights the use of `set_input_offset`, `update`, `finalize_non_root`, `merge_subtrees_non_root`, and `merge_subtrees_root`.

```APIDOC
## Example: Computing Interior Hashes in a 3-Chunk Tree

This example demonstrates computing the chaining values for individual chunks and merging them to form parent nodes, culminating in the final root hash. It highlights the use of `set_input_offset`, `update`, `finalize_non_root`, `merge_subtrees_non_root`, and `merge_subtrees_root`.

```rust
use blake3::{Hasher, CHUNK_LEN};
use blake3::hazmat::{merge_subtrees_non_root, merge_subtrees_root, Mode};
use blake3::hazmat::HasherExt; // an extension trait for Hasher

let chunk0 = [b'a'; CHUNK_LEN];
let chunk1 = [b'b'; CHUNK_LEN];
let chunk2 = [b'c'; 42]; // The final chunk can be short.

// Compute the non-root hashes ("chaining values") of all three chunks. Chunks or subtrees
// that don't begin at the start of the input use `set_input_offset` to say where they begin.
let chunk0_cv = Hasher::new()
    // .set_input_offset(0) is the default.
    .update(&chunk0)
    .finalize_non_root();
let chunk1_cv = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(&chunk1)
    .finalize_non_root();
let chunk2_cv = Hasher::new()
    .set_input_offset(2 * CHUNK_LEN as u64)
    .update(&chunk2)
    .finalize_non_root();

// Join the first two chunks with a non-root parent node and compute its chaining value.
let parent_cv = merge_subtrees_non_root(&chunk0_cv, &chunk1_cv, Mode::Hash);

// Join that parent node and the third chunk with a root parent node and compute the hash.
let root_hash = merge_subtrees_root(&parent_cv, &chunk2_cv, Mode::Hash);

// Double check that we got the right answer.
let mut combined_input = Vec::new();
combined_input.extend_from_slice(&chunk0);
combined_input.extend_from_slice(&chunk1);
combined_input.extend_from_slice(&chunk2);
assert_eq!(root_hash, blake3::hash(&combined_input));
```
```

--------------------------------

### Derive Key Context Example

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.hash_derive_key_context.html

Demonstrates how to use `hash_derive_key_context` to create a `ContextKey` and then use it with `Hasher::new_from_context_key` to derive a key. This is compared against the direct `blake3::derive_key` function.

```rust
use blake3::Hasher;
use blake3::hazmat::HasherExt;

let context_key = blake3::hazmat::hash_derive_key_context("foo");
let mut hasher = Hasher::new_from_context_key(&context_key);
hasher.update(b"bar");
let derived_key = *hasher.finalize().as_bytes();

assert_eq!(derived_key, blake3::derive_key("foo", b"bar"));
```

--------------------------------

### BLAKE3 hashing usage examples

Source: https://docs.rs/blake3/latest/blake3/fn.hash.html?search=u32+-%3E+bool

Demonstrates the default hash function compared to the incremental Hasher API.

```rust
let hash = blake3::hash(b"foo");

let hash = blake3::Hasher::new().update(b"foo").finalize();
```

--------------------------------

### BLAKE3 Hashing Examples in Rust

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Demonstrates hashing input data using BLAKE3, both all at once and incrementally. It also shows how to finalize the hash and use extended output with `OutputReader`. Ensure the `std` feature is enabled for `OutputReader` functionality.

```rust
# fn main() -> Result<(), Box<dyn std::error::Error>> {
// 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.
# #[cfg(feature = "std")] { 
let mut output = [0; 1000];
let mut output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(hash1, output_reader.hasher.finalize());
# }

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

--------------------------------

### Keyed Hash Incremental Example

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Demonstrates the equivalent keyed hash computation using the incremental `Hasher` API.

```rust
let mac = blake3::keyed_hash(KEY, b"foo");
# let mac1 = mac;

let mac = blake3::Hasher::new_keyed(KEY).update(b"foo").finalize();
# let mac2 = mac;
# assert_eq!(mac1, mac2);
```

--------------------------------

### Example: Hashing Multiple Chunks in Parallel

Source: https://docs.rs/blake3/latest/blake3/hazmat/index.html

Illustrates how hashing multiple chunks together can improve performance by leveraging internal SIMD parallelism. It shows how to compute a subtree's chaining value by processing multiple chunks simultaneously.

```APIDOC
## Example: Hashing Multiple Chunks in Parallel

Hashing many chunks together is important for performance, because it allows the implementation to use SIMD parallelism internally. (AVX-512 for example needs 16 chunks to really get going.) We can reproduce `parent_cv` by hashing `chunk0` and `chunk1` at the same time:

```rust
let left_subtree_cv = Hasher::new()
    // .set_input_offset(0) is the default.
    .update(&combined_input[..2 * CHUNK_LEN])
    .finalize_non_root();
assert_eq!(left_subtree_cv, parent_cv);

// Using multiple updates gives the same answer, though it's not as efficient.
let mut subtree_hasher = Hasher::new();
// Again, .set_input_offset(0) is the default.
subtree_hasher.update(&chunk0);
subtree_hasher.update(&chunk1);
assert_eq!(left_subtree_cv, subtree_hasher.finalize_non_root());
```

However, hashing multiple chunks together **must** respect the overall tree structure. Hashing `chunk0` and `chunk1` together is valid, but hashing `chunk1` and `chunk2` together is incorrect and gives a garbage result that will never match a standard BLAKE3 hash. The implementation includes a few best-effort asserts to catch some of these mistakes, but these checks aren’t guaranteed. For example, this second call to `update` currently panics:

ⓘ```rust
let oops = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(&chunk1)
    // PANIC: "the subtree starting at 1024 contains at most 1024 bytes"
    .update(&chunk2)
    .finalize_non_root();
```

For more on valid tree structures, see the docs for and `left_subtree_len` and `max_subtree_len`, and see section 2.1 of the BLAKE3 paper. Note that the merging functions (`merge_subtrees_root` and friends) don’t know the shape of the left and right subtrees you’re giving them, and they can’t help you catch mistakes. The best way to catch mistakes with these is to compare your root output to the `blake3::hash` of the same input.
```

--------------------------------

### BLAKE3 keyed_hash example

Source: https://docs.rs/blake3/latest/blake3/fn.keyed_hash.html

Demonstrates the basic usage of the keyed_hash function for generating a MAC. For security, compare the resulting Hash values using constant-time comparison methods.

```rust
let mac = blake3::keyed_hash(KEY, b"foo");
```

--------------------------------

### BLAKE3 Tree Hashing Example

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Demonstrates how to compute a subtree hash using multiple updates and verify it against a parent hash. This is useful for understanding BLAKE3's tree structure and for manual verification.

```rust
# use blake3::{Hasher, CHUNK_LEN};
# use blake3::hazmat::HasherExt;
# fn main() {
# let chunk0 = [b'a'; CHUNK_LEN];
# let chunk1 = [b'b'; CHUNK_LEN];
# let parent_cv = Hasher::new().update(&chunk0).update(&chunk1).finalize_non_root();
# let mut combined_input = Vec::with_capacity(2 * CHUNK_LEN);
//! # combined_input.extend_from_slice(&chunk0);
//! # combined_input.extend_from_slice(&chunk1);
//! let left_subtree_cv = Hasher::new()
//!     // .set_input_offset(0) is the default.
//!     .update(&combined_input[..2 * CHUNK_LEN])
//!     .finalize_non_root();
//! assert_eq!(left_subtree_cv, parent_cv);
//!
//! // Using multiple updates gives the same answer, though it's not as efficient.
//! let mut subtree_hasher = Hasher::new();
//! // Again, .set_input_offset(0) is the default.
//! subtree_hasher.update(&chunk0);
//! subtree_hasher.update(&chunk1);
//! assert_eq!(left_subtree_cv, subtree_hasher.finalize_non_root());
//! # }

```

--------------------------------

### Default Hash Function Usage

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html?search=

Example of the default BLAKE3 hash function call.

```rust
let hash = blake3::hash(b"foo");
```

--------------------------------

### BLAKE3 incremental keyed hash example

Source: https://docs.rs/blake3/latest/blake3/fn.keyed_hash.html

Shows the equivalent incremental hashing approach using Hasher::new_keyed, update, and finalize. This is an alternative to the direct keyed_hash function for multi-write scenarios.

```rust
let mac = blake3::Hasher::new_keyed(KEY).update(b"foo").finalize();
```

--------------------------------

### Example Usage of merge_subtrees_root_xof

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.merge_subtrees_root_xof.html?search=

Demonstrates hashing a 2-chunk subtree by manually merging two child chaining values into a root OutputReader.

```rust
use blake3::hazmat::{merge_subtrees_root_xof, HasherExt, Mode};
use blake3::{Hasher, CHUNK_LEN};

// Hash a 2-chunk subtree in steps. Note that only
// the final chunk can be shorter than CHUNK_LEN.
let chunk0 = &[42; CHUNK_LEN];
let chunk1 = b"hello world";
let chunk0_cv = Hasher::new()
    .update(chunk0)
    .finalize_non_root();
let chunk1_cv = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(chunk1)
    .finalize_non_root();

// Obtain a blake3::OutputReader at the root and extract 1000 bytes.
let mut output_reader = merge_subtrees_root_xof(&chunk0_cv, &chunk1_cv, Mode::Hash);
let mut output_bytes = [0; 1_000];
output_reader.fill(&mut output_bytes);

// Double check the answer.
let mut hasher = Hasher::new();
hasher.update(chunk0);
hasher.update(chunk1);
let mut expected = [0; 1_000];
hasher.finalize_xof().fill(&mut expected);
assert_eq!(output_bytes, expected);
```

--------------------------------

### Hash a 2-chunk subtree in steps

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.merge_subtrees_root_xof.html

This example demonstrates hashing a 2-chunk subtree by first finalizing each chunk as a non-root chaining value and then merging them into a root OutputReader. Note that only the final chunk can be shorter than CHUNK_LEN. The resulting OutputReader is then used to fill a byte array, and the result is double-checked against a direct hashing approach.

```rust
use blake3::hazmat::{merge_subtrees_root_xof, HasherExt, Mode};
use blake3::{Hasher, CHUNK_LEN};

// Hash a 2-chunk subtree in steps. Note that only
// the final chunk can be shorter than CHUNK_LEN.
let chunk0 = &[42; CHUNK_LEN];
let chunk1 = b"hello world";
let chunk0_cv = Hasher::new()
    .update(chunk0)
    .finalize_non_root();
let chunk1_cv = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(chunk1)
    .finalize_non_root();

// Obtain a blake3::OutputReader at the root and extract 1000 bytes.
let mut output_reader = merge_subtrees_root_xof(&chunk0_cv, &chunk1_cv, Mode::Hash);
let mut output_bytes = [0; 1_000];
output_reader.fill(&mut output_bytes);

// Double check the answer.
let mut hasher = Hasher::new();
hasher.update(chunk0);
hasher.update(chunk1);
let mut expected = [0; 1_000];
hasher.finalize_xof().fill(&mut expected);
assert_eq!(output_bytes, expected);
```

--------------------------------

### Get Current Read Position in Output Stream

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Returns the current read position in the output stream as a `u64`. This is equivalent to `Seek::stream_position` but does not return a `Result`. The position starts at 0 and advances with each read operation.

```rust
pub fn position(&self) -> u64 {
        self.inner.counter * BLOCK_LEN as u64 + self.position_within_block as u64
    }
```

--------------------------------

### Get Maximum Subtree Length

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.max_subtree_len.html

Calculates the maximum length of a subtree in bytes, given its starting offset. Returns `None` for an input offset of zero, and `Some(u64)` for other valid offsets. Panics if `input_offset` is not a multiple of `CHUNK_LEN`.

```rust
pub fn max_subtree_len(input_offset: u64) -> Option<u64>
```

--------------------------------

### Derive Subkeys with BLAKE3

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html?search=

Illustrates key derivation using a context string and key material, showing both the direct function and the incremental Hasher approach.

```rust
# const CONTEXT: &str = "example.com 2019-12-25 16:18:03 session tokens v1";
let key = blake3::derive_key(CONTEXT, b"key material, not a password");
# let key1 = key;

let key: [u8; 32] = blake3::Hasher::new_derive_key(CONTEXT)
    .update(b"key material, not a password")
    .finalize()
    .into();
# let key2 = key;
# assert_eq!(key1, key2);
```

--------------------------------

### set_input_offset

Source: https://docs.rs/blake3/latest/blake3/hazmat/trait.HasherExt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configures the Hasher to process data starting at a specific byte offset, required for processing subtrees that do not start at the beginning of the input.

```APIDOC
## fn set_input_offset(&mut self, offset: u64) -> &mut Self

### Description
Sets the starting input offset for the hasher. This must be called before any input is processed via `update` and is required for subtrees starting at non-zero offsets.

### Parameters
- **offset** (u64) - Required - The byte offset into the input. Must be a multiple of `CHUNK_LEN`.
```

--------------------------------

### Get and Set Position

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html?search=

Methods to retrieve or modify the current read position in the output stream.

```rust
pub fn position(&self) -> u64 {
        self.inner.counter * BLOCK_LEN as u64 + self.position_within_block as u64
    }
```

```rust
pub fn set_position(&mut self, position: u64) {
        self.position_within_block = (position % BLOCK_LEN as u64) as u8;
        self.inner.counter = position / BLOCK_LEN as u64;
    }
```

--------------------------------

### Get SIMD Degree and Compress

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html?search=

Methods to retrieve the SIMD degree for a platform and perform compression.

```rust
102    pub fn simd_degree(&self) -> usize {
103        let degree = match self {
104            Platform::Portable => 1,
105            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
106            Platform::SSE2 => 4,
107            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
108            Platform::SSE41 => 4,
109            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
110            Platform::AVX2 => 8,
111            #[cfg(blake3_avx512_ffi)]
112            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
113            Platform::AVX512 => 16,
114            #[cfg(blake3_neon)]
115            Platform::NEON => 4,
116            #[cfg(blake3_wasm32_simd)]
117            Platform::WASM32_SIMD => 4,
118        };
119        debug_assert!(degree <= MAX_SIMD_DEGREE);
120        degree
121    }
122
123    pub fn compress_in_place(
124        &self,
125        cv: &mut CVWords,
126        block: &[u8; BLOCK_LEN],
127        block_len: u8,
128        counter: u64,
129        flags: u8,
130    ) {
131        match self {
132            Platform::Portable => portable::compress_in_place(cv, block, block_len, counter, flags),
133            // Safe because detect() checked for platform support.
134            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
135            Platform::SSE2 => unsafe {
136                crate::sse2::compress_in_place(cv, block, block_len, counter, flags)
137            },
138            // Safe because detect() checked for platform support.
139            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
```

--------------------------------

### Constructing a new Hasher

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Shows how to create a new `Hasher` instance for different hashing modes: regular, keyed, and key derivation. For keyed and derive-key modes, specific key or context material is required.

```rust
pub fn new() -> Self {
    Self::new_internal(IV, 0)
}
```

```rust
pub fn new_keyed(key: &[u8; KEY_LEN]) -> Self {
    let key_words = platform::words_from_le_bytes_32(key);
    Self::new_internal(&key_words, KEYED_HASH)
}
```

```rust
pub fn new_derive_key(context: &str) -> Self {
    let context_key = hazmat::hash_derive_key_context(context);
    let context_key_words = platform::words_from_le_bytes_32(&context_key);
    Self::new_internal(&context_key_words, DERIVE_KEY_MATERIAL)
}
```

--------------------------------

### Triggering Subtree Hashing Panic

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html?search=u32+-%3E+bool

Shows an example of incorrect subtree hashing that triggers a panic due to exceeding the maximum subtree length.

```rust
# fn main() {
# use blake3::{Hasher, CHUNK_LEN};
# use blake3::hazmat::HasherExt;
# let chunk0 = [b'a'; CHUNK_LEN];
# let chunk1 = [b'b'; CHUNK_LEN];
# let chunk2 = [b'c'; 42];
let oops = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(&chunk1)
    // PANIC: "the subtree starting at 1024 contains at most 1024 bytes"
    .update(&chunk2)
    .finalize_non_root();
# }
```

--------------------------------

### Perform Hashing Operations with BLAKE3

Source: https://docs.rs/blake3/latest/blake3/index.html?search=

Demonstrates basic hashing, incremental updates, extended output reading, and hex string conversion.

```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 output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(hash1, output[..32]);

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

--------------------------------

### set_input_offset

Source: https://docs.rs/blake3/latest/blake3/hazmat/trait.HasherExt.html?search=std%3A%3Avec

Configures the Hasher to process a chunk or subtree starting at a specific byte offset. Must be called before any input is processed via update.

```APIDOC
fn set_input_offset(&mut self, offset: u64) -> &mut Self
```

--------------------------------

### new_from_context_key

Source: https://docs.rs/blake3/latest/blake3/hazmat/trait.HasherExt.html?search=

Initializes a new Hasher using a pre-hashed ContextKey, optimizing performance for derive-key operations.

```APIDOC
## fn new_from_context_key(context_key: &ContextKey) -> Self

### Description
Creates a new Hasher instance using a pre-computed ContextKey. This is a performance optimization over standard derive-key methods to avoid re-hashing the context string.

### Parameters
- **context_key** (&ContextKey) - Required - A pre-hashed context key obtained from `hash_derive_key_context`.
```

--------------------------------

### Get Total Bytes Hashed

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Returns the total number of bytes that have been processed by the hasher. This count is not affected by `set_input_offset` and only reflects bytes passed to `update`.

```rust
pub fn count(&self) -> u64 {
        // Account for non-zero cases of Hasher::set_input_offset. Note that initial_chunk_counter
        // is always 0 for callers who don't use the hazmat module.
        (self.chunk_state.chunk_counter - self.initial_chunk_counter) * CHUNK_LEN as u64
            + self.chunk_state.count() as u64
    }
```

--------------------------------

### Hashing All At Once

Source: https://docs.rs/blake3/latest/blake3/index.html

Demonstrates how to compute the BLAKE3 hash of an input byte slice directly.

```APIDOC
## hash

### Description
Computes the BLAKE3 hash of an input byte slice.

### Function Signature
`fn hash(input: &[u8]) -> Hash`

### Parameters
- **input** (`&[u8]`): The byte slice to hash.

### Returns
- `Hash`: The resulting BLAKE3 hash.

### Example
```rust
let hash = blake3::hash(b"foobarbaz");
println!("{}", hash);
```
```

--------------------------------

### max_subtree_len(input_offset: u64) -> Option<u64>

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html?search=u32+-%3E+bool

Calculates the maximum length of a subtree starting at the given input offset. This function panics if the input_offset is not a multiple of CHUNK_LEN.

```APIDOC
### Function: max_subtree_len

Calculates the maximum length of a subtree starting at the given input offset. Returns None if the offset is 0.

#### Parameters
- **input_offset** (u64) - The byte offset in the input stream.

#### Returns
- **Option<u64>** - The maximum length of the subtree in bytes, or None if the offset is 0.
```

--------------------------------

### Get SIMD Degree for Platform

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html

Returns the SIMD degree (number of parallel operations) for a given BLAKE3 `Platform`. This value is asserted to be less than or equal to `MAX_SIMD_DEGREE`.

```rust
pub fn simd_degree(&self) -> usize {
    let degree = match self {
        Platform::Portable => 1,
        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        Platform::SSE2 => 4,
        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        Platform::SSE41 => 4,
        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        Platform::AVX2 => 8,
        #[cfg(blake3_avx512_ffi)]
        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        Platform::AVX512 => 16,
        #[cfg(blake3_neon)]
        Platform::NEON => 4,
        #[cfg(blake3_wasm32_simd)]
        Platform::WASM32_SIMD => 4,
    };
    debug_assert!(degree <= MAX_SIMD_DEGREE);
    degree
}
```

--------------------------------

### Equivalent key derivation methods

Source: https://docs.rs/blake3/latest/blake3/fn.derive_key.html?search=

Demonstrates the equivalence between the direct derive_key function and the incremental Hasher approach.

```rust
let key = blake3::derive_key(CONTEXT, b"key material, not a password");

let key: [u8; 32] = blake3::Hasher::new_derive_key(CONTEXT)
    .update(b"key material, not a password")
    .finalize()
    .into();
```

--------------------------------

### new_from_context_key

Source: https://docs.rs/blake3/latest/blake3/hazmat/trait.HasherExt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a new Hasher using a pre-hashed ContextKey, optimizing performance for derive-key operations by avoiding repeated context string hashing.

```APIDOC
## fn new_from_context_key(context_key: &ContextKey) -> Self

### Description
Creates a new Hasher instance initialized with a pre-computed ContextKey. This is a performance-optimized alternative to standard key derivation when the context is reused.

### Parameters
- **context_key** (&ContextKey) - Required - A pre-hashed context key obtained from `hash_derive_key_context`.
```

--------------------------------

### Parallel Chunk Hashing with BLAKE3 Hazmat

Source: https://docs.rs/blake3/latest/blake3/hazmat/index.html

Illustrates how to hash multiple chunks in parallel for performance gains using BLAKE3's hazmat module. It also shows an alternative method using multiple updates to a single Hasher.

```rust
let left_subtree_cv = Hasher::new()
    // .set_input_offset(0) is the default.
    .update(&combined_input[..2 * CHUNK_LEN])
    .finalize_non_root();
assert_eq!(left_subtree_cv, parent_cv);

// Using multiple updates gives the same answer, though it's not as efficient.
let mut subtree_hasher = Hasher::new();
// Again, .set_input_offset(0) is the default.
subtree_hasher.update(&chunk0);
subtree_hasher.update(&chunk1);
assert_eq!(left_subtree_cv, subtree_hasher.finalize_non_root());

```

--------------------------------

### Get Hash as Byte Slice

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Returns the raw bytes of the `Hash` as a slice. Use this for serialization. For comparisons, prefer the `Hash` type's `PartialEq` implementation for constant-time security.

```rust
pub const fn as_slice(&self) -> &[u8] {
        self.0.as_slice()
    }
```

--------------------------------

### Deriving a Key with Context

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.hash_derive_key_context.html?search=u32+-%3E+bool

Demonstrates how to use hash_derive_key_context to initialize a Hasher and derive key material.

```rust
use blake3::Hasher;
use blake3::hazmat::HasherExt;

let context_key = blake3::hazmat::hash_derive_key_context("foo");
let mut hasher = Hasher::new_from_context_key(&context_key);
hasher.update(b"bar");
let derived_key = *hasher.finalize().as_bytes();

assert_eq!(derived_key, blake3::derive_key("foo", b"bar"));
```

--------------------------------

### BLAKE3 compress_in_place for different platforms

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html

Selects the appropriate `compress_in_place` implementation based on the detected platform. This function is safe to call only after `detect()` has confirmed platform support.

```rust
match self {
            Platform::Portable => portable::compress_in_place(cv, block, block_len, counter, flags),
            // Safe because detect() checked for platform support.
            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
            Platform::SSE2 | Platform::SSE41 => unsafe {
                crate::sse41::compress_in_place(cv, block, block_len, counter, flags)
            },
            // Safe because detect() checked for platform support.
            #[cfg(blake3_avx512_ffi)]
            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
            Platform::AVX512 => unsafe {
                crate::avx512::compress_in_place(cv, block, block_len, counter, flags)
            },
            // No NEON compress_in_place() implementation yet.
            #[cfg(blake3_neon)]
            Platform::NEON => portable::compress_in_place(cv, block, block_len, counter, flags),
            #[cfg(blake3_wasm32_simd)]
            Platform::WASM32_SIMD => {
                crate::wasm32_simd::compress_in_place(cv, block, block_len, counter, flags)
            }
        }
```

--------------------------------

### Hashing data with BLAKE3

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html?search=std%3A%3Avec

Demonstrates the basic usage of the blake3::hash function compared to the incremental Hasher API.

```rust
let hash = blake3::Hasher::new().update(b"foo").finalize();
```

--------------------------------

### max_subtree_len(input_offset: u64) -> Option<u64>

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html?search=

Calculates the maximum length of a subtree starting at the given input offset. This function is used to determine the bounds for subtree processing in the BLAKE3 tree structure.

```APIDOC
## fn max_subtree_len

### Description
Returns the maximum length of a subtree starting at the specified input offset. The input offset must be a multiple of the chunk length.

### Parameters
- **input_offset** (u64) - The byte offset in the input stream.

### Returns
- **Option<u64>** - The maximum length of the subtree, or None if the offset is 0.
```

--------------------------------

### SSE4.1 platform constructor

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html

Returns an `Option<Self>` containing `Platform::SSE41` if SSE4.1 instructions are detected on the current CPU. Requires `x86` or `x86_64` target architecture.

```rust
pub fn sse41() -> Option<Self> {
        if sse41_detected() {
            Some(Self::SSE41)
        } else {
            None
        }
    }
```

--------------------------------

### Determining the Start Flag for BLAKE3 Chunk Compression

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Returns the `CHUNK_START` flag if no blocks have been compressed yet, otherwise returns 0. This flag is used to indicate the beginning of a chunk's compression.

```rust
fn start_flag(&self) -> u8 {
    if self.blocks_compressed == 0 {
        CHUNK_START
    } else {
        0
    }
}
```

--------------------------------

### Dispatch compress_in_place by Platform

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html?search=u32+-%3E+bool

Matches the current platform to the appropriate SIMD or portable implementation for in-place compression.

```rust
            Platform::SSE41 | Platform::AVX2 => unsafe {
                crate::sse41::compress_in_place(cv, block, block_len, counter, flags)
            },
            // Safe because detect() checked for platform support.
            #[cfg(blake3_avx512_ffi)]
            #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
            Platform::AVX512 => unsafe {
                crate::avx512::compress_in_place(cv, block, block_len, counter, flags)
            },
            // No NEON compress_in_place() implementation yet.
            #[cfg(blake3_neon)]
            Platform::NEON => portable::compress_in_place(cv, block, block_len, counter, flags),
            #[cfg(blake3_wasm32_simd)]
            Platform::WASM32_SIMD => {
                crate::wasm32_simd::compress_in_place(cv, block, block_len, counter, flags)
            }
        }
    }
```

--------------------------------

### Incremental Hashing and Extended Output

Source: https://docs.rs/blake3/latest/blake3/struct.Hasher.html?search=

Demonstrates updating the hasher state incrementally and using OutputReader for extended output.

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

// 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!(&output[..32], blake3::hash(b"foobarbaz").as_bytes());
```

--------------------------------

### Set Input Offset for Hasher

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Sets the starting offset for input data within a chunk. The offset must be a multiple of CHUNK_LEN and the hasher must not have accepted any input yet. This is crucial for correctly implementing tree hashing.

```rust
assert_eq!(self.count(), 0, "hasher has already accepted input");
assert_eq!(
    offset % CHUNK_LEN as u64,
    0,
    "offset ({offset}) must be a chunk boundary (divisible by {CHUNK_LEN})",
);
let counter = offset / CHUNK_LEN as u64;
self.chunk_state.chunk_counter = counter;
self.initial_chunk_counter = counter;
self
```

--------------------------------

### BLAKE3 Invalid Tree Hashing Panic Example

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Illustrates a scenario where incorrect input offsets lead to a panic during tree hashing. This highlights the importance of maintaining correct tree structure and input offsets to avoid runtime errors.

```rust
# fn main() {
# use blake3::{Hasher, CHUNK_LEN};
# use blake3::hazmat::HasherExt;
# let chunk0 = [b'a'; CHUNK_LEN];
# let chunk1 = [b'b'; CHUNK_LEN];
# let chunk2 = [b'c'; 42];
let oops = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(&chunk1)
    // PANIC: "the subtree starting at 1024 contains at most 1024 bytes"
    .update(&chunk2)
    .finalize_non_root();
# }

```

--------------------------------

### Compress Data for XOF with SSE4.1

Source: https://docs.rs/blake3/latest/src/blake3/ffi_sse41.rs.html

Performs a BLAKE3 compression operation for an extendable-output function (XOF) using SSE4.1. Returns 64 bytes of output. This function is unsafe and requires SSE4.1 support.

```rust
pub unsafe fn compress_xof(
    cv: &CVWords,
    block: &[u8; BLOCK_LEN],
    block_len: u8,
    counter: u64,
    flags: u8,
) -> [u8; 64] {
    unsafe {
        let mut out = [0u8; 64];
        ffi::blake3_compress_xof_sse41(
            cv.as_ptr(),
            block.as_ptr(),
            block_len,
            counter,
            flags,
            out.as_mut_ptr(),
        );
        out
    }
}
```

--------------------------------

### Derive Key using blake3::derive_key

Source: https://docs.rs/blake3/latest/blake3/fn.derive_key.html

This snippet shows how to derive a key using the direct `blake3::derive_key` function. Ensure the context string is hardcoded, globally unique, and application-specific.

```rust
let key = blake3::derive_key(CONTEXT, b"key material, not a password");
```

--------------------------------

### Implement Seek Trait for OutputReader

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Implements the `std::io::Seek` trait for `OutputReader`, enabling seeking within the output stream. It supports `SeekFrom::Start` and `SeekFrom::Current` but not `SeekFrom::End`. It handles potential overflow and seeks before the start.

```rust
impl std::io::Seek for OutputReader {
    fn seek(&mut self, pos: std::io::SeekFrom) -> std::io::Result<u64> {
        let max_position = u64::max_value() as i128;
        let target_position: i128 = match pos {
            std::io::SeekFrom::Start(x) => x as i128,
            std::io::SeekFrom::Current(x) => self.position() as i128 + x as i128,
            std::io::SeekFrom::End(_) => {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "seek from end not supported",
                ));
            }
        };
        if target_position < 0 {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                "seek before start",
            ));
        }
        self.set_position(cmp::min(target_position, max_position) as u64);
        Ok(self.position())
    }
}
```

--------------------------------

### Initialize Hasher with Context Key

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Creates a new Hasher instance initialized with a specific context key for key derivation. This is useful for creating keyed hashes or deriving keys.

```rust
let context_key_words = crate::platform::words_from_le_bytes_32(context_key);
Hasher::new_internal(&context_key_words, crate::DERIVE_KEY_MATERIAL)
```

--------------------------------

### Compute Interior Hashes in a 3-Chunk BLAKE3 Tree

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Demonstrates computing the chaining values of individual chunks and merging them into a parent and then a root hash. Use `set_input_offset` for chunks not starting at the beginning of the input. `finalize_non_root` computes intermediate hashes, and `merge_subtrees_non_root`/`merge_subtrees_root` combine them.

```rust
use blake3::{Hasher, CHUNK_LEN};
use blake3::hazmat::{merge_subtrees_non_root, merge_subtrees_root, Mode};
use blake3::hazmat::HasherExt; // an extension trait for Hasher

let chunk0 = [b'a'; CHUNK_LEN];
let chunk1 = [b'b'; CHUNK_LEN];
let chunk2 = [b'c'; 42]; // The final chunk can be short.

// Compute the non-root hashes ("chaining values") of all three chunks. Chunks or subtrees
// that don't begin at the start of the input use `set_input_offset` to say where they begin.
let chunk0_cv = Hasher::new()
    // .set_input_offset(0) is the default.
    .update(&chunk0)
    .finalize_non_root();
let chunk1_cv = Hasher::new()
    .set_input_offset(CHUNK_LEN as u64)
    .update(&chunk1)
    .finalize_non_root();
let chunk2_cv = Hasher::new()
    .set_input_offset(2 * CHUNK_LEN as u64)
    .update(&chunk2)
    .finalize_non_root();

// Join the first two chunks with a non-root parent node and compute its chaining value.
let parent_cv = merge_subtrees_non_root(&chunk0_cv, &chunk1_cv, Mode::Hash);

// Join that parent node and the third chunk with a root parent node and compute the hash.
let root_hash = merge_subtrees_root(&parent_cv, &chunk2_cv, Mode::Hash);

// Double check that we got the right answer.
let mut combined_input = Vec::new();
combined_input.extend_from_slice(&chunk0);
combined_input.extend_from_slice(&chunk1);
combined_input.extend_from_slice(&chunk2);
assert_eq!(root_hash, blake3::hash(&combined_input));
```

--------------------------------

### Test Key Derivation with Hazmat

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html?search=u32+-%3E+bool

Shows how to derive keys using low-level subtree merging primitives.

```rust
#[test]
    fn test_derive_key() {
        let context = "foo";
        let mut input = [0; 1025];
        crate::test::paint_test_input(&mut input);
        let expected = crate::derive_key(context, &input);

        let cx_key = hash_derive_key_context(context);
        let left = Hasher::new_from_context_key(&cx_key)
            .update(&input[..1024])
            .finalize_non_root();
        let right = Hasher::new_from_context_key(&cx_key)
            .set_input_offset(1024)
            .update(&input[1024..])
            .finalize_non_root();
        let derived_key = merge_subtrees_root(&left, &right, Mode::DeriveKeyMaterial(&cx_key)).0;
        assert_eq!(expected, derived_key);
    }
```

--------------------------------

### max_subtree_len

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.max_subtree_len.html

The maximum length of a subtree in bytes, given its starting offset in bytes. If you try to hash more than this many bytes as one subtree, you’ll end up merging parent nodes that shouldn’t be merged, and your output will be garbage. `Hasher::update` will currently panic in this case, but this is not guaranteed.

```APIDOC
## Function max_subtree_len

### Signature
```rust
pub fn max_subtree_len(input_offset: u64) -> Option<u64>
```

### Description
Calculates the maximum length of a subtree in bytes, given its starting offset. For input offset zero, there is no maximum length and this function returns `None`. For all other offsets, it returns `Some`. Valid offsets must be a multiple of `CHUNK_LEN` (1024).

### Panics
This function currently panics if `input_offset` is not a multiple of `CHUNK_LEN`. This is not guaranteed.
```

--------------------------------

### Initialize OutputReader

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html

Creates a new `OutputReader` from an existing `Output` struct.

```rust
impl OutputReader {
    fn new(inner: Output) -> Self {
        Self {
            inner,
            position_within_block: 0,
        }
    }
// ... other methods
```

--------------------------------

### Hashing Subtrees with Hasher

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html?search=u32+-%3E+bool

Demonstrates how to hash subtrees using the Hasher API. Note that input offsets must be managed correctly to match standard BLAKE3 tree structures.

```rust
# let parent_cv = merge_subtrees_non_root(&chunk0_cv, &chunk1_cv, Mode::Hash);
# let mut combined_input = Vec::new();
# combined_input.extend_from_slice(&chunk0);
# combined_input.extend_from_slice(&chunk1);
let left_subtree_cv = Hasher::new()
    // .set_input_offset(0) is the default.
    .update(&combined_input[..2 * CHUNK_LEN])
    .finalize_non_root();
assert_eq!(left_subtree_cv, parent_cv);

// Using multiple updates gives the same answer, though it's not as efficient.
let mut subtree_hasher = Hasher::new();
// Again, .set_input_offset(0) is the default.
subtree_hasher.update(&chunk0);
subtree_hasher.update(&chunk1);
assert_eq!(left_subtree_cv, subtree_hasher.finalize_non_root());
# }
```

--------------------------------

### max_subtree_len(input_offset: u64) -> Option<u64>

Source: https://docs.rs/blake3/latest/blake3/hazmat/fn.max_subtree_len.html?search=

Calculates the maximum length of a subtree in bytes for a given starting offset. If the offset is zero, it returns None as there is no maximum length. For non-zero offsets, it returns the maximum length as Some(u64). Note that the input_offset must be a multiple of CHUNK_LEN (1024).

```APIDOC
## Function: max_subtree_len

### Description
Returns the maximum length of a subtree in bytes, given its starting offset in bytes. This is used to ensure that hashing operations do not merge parent nodes incorrectly.

### Signature
`pub fn max_subtree_len(input_offset: u64) -> Option<u64>`

### Parameters
- **input_offset** (u64) - The starting offset in bytes. Must be a multiple of 1024 (CHUNK_LEN).

### Returns
- **Option<u64>** - Returns `None` if the offset is zero. Returns `Some(u64)` representing the maximum length in bytes for any other valid offset.

### Panics
- Panics if `input_offset` is not a multiple of `CHUNK_LEN` (1024).
```

--------------------------------

### Implement Platform Detection

Source: https://docs.rs/blake3/latest/src/blake3/platform.rs.html?search=

Provides logic to detect the best available platform at runtime.

```rust
63impl Platform {
64    #[allow(unreachable_code)]
65    pub fn detect() -> Self {
66        #[cfg(miri)]
67        {
68            return Platform::Portable;
69        }
70
71        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
72        {
73            #[cfg(blake3_avx512_ffi)]
74            {
75                if avx512_detected() {
76                    return Platform::AVX512;
77                }
78            }
79            if avx2_detected() {
80                return Platform::AVX2;
81            }
82            if sse41_detected() {
83                return Platform::SSE41;
84            }
85            if sse2_detected() {
86                return Platform::SSE2;
87            }
88        }
89        // We don't use dynamic feature detection for NEON. If the "neon"
90        // feature is on, NEON is assumed to be supported.
91        #[cfg(blake3_neon)]
92        {
93            return Platform::NEON;
94        }
95        #[cfg(blake3_wasm32_simd)]
96        {
97            return Platform::WASM32_SIMD;
98        }
99        Platform::Portable
100    }
```

--------------------------------

### Hash Data with BLAKE3

Source: https://docs.rs/blake3/latest/src/blake3/lib.rs.html?search=

Demonstrates the standard hashing function and its equivalent using the Hasher API.

```rust
# let hash1 = hash;

let hash = blake3::Hasher::new().update(b"foo").finalize();
# let hash2 = hash;
# assert_eq!(hash1, hash2);
```

--------------------------------

### BLAKE3 Derive Key from Context Key

Source: https://docs.rs/blake3/latest/src/blake3/hazmat.rs.html

Shows how to create a new Hasher instance pre-configured with a context key for derive-key mode. This is an optimization to avoid re-hashing the context string repeatedly in loops.

```rust
use blake3::Hasher;
use blake3::hazmat::HasherExt;

let context_key = blake3::hazmat::hash_derive_key_context("foo");
let mut hasher = Hasher::new_from_context_key(&context_key);
hasher.update(b"bar");
let derived_key = *hasher.finalize().as_bytes();

assert_eq!(derived_key, blake3::derive_key("foo", b"bar"));

```

--------------------------------

### Derive Key using blake3::Hasher

Source: https://docs.rs/blake3/latest/blake3/fn.derive_key.html

This snippet demonstrates deriving a key incrementally using `blake3::Hasher`. This is equivalent to using `blake3::derive_key` but allows for multiple updates before finalizing. The context string should be hardcoded, globally unique, and application-specific.

```rust
let key: [u8; 32] = blake3::Hasher::new_derive_key(CONTEXT)
    .update(b"key material, not a password")
    .finalize()
    .into();
```
Tokens:
Raw