feature: implement blake3 hash and keyed hash modes by jakub-mata · Pull Request #641 · orion-rs/orion

jakub-mata · 2026-07-19T07:02:58Z

This PR introduces the BLAKE3 hash function into the /hazardous module, implemented according to the official BLAKE3 specifications.
Features Included:

hash mode: standard BLAKE3 hashing.
keyed hash mode: Supports message authentication (MAC) use cases using a 256-bit key.
extendable output (XOF): Arbitrary output lengths as per the spec.

Note: The "derive key" mode has been omitted from this PR to keep the scope focused on standard hashing. The underlying state machine has been structured so that key derivation can be easily added in a future PR if desired.

Testing includes:

unit tests: located at the bottom of their respective source files.
known-answer tests: set up to match the existing blake2 tests. The test vectors were sourced from the b3sum repository and cover both standard and keyed hashing across various chunk boundaries.

This initial implementation establishes a single-threaded baseline. Because BLAKE3's tree structure is designed for infinite parallelism, a natural next step will be adding a data-parallelism feature flag to support multi-threaded hashing for large inputs.

Resolves #394

codecov · 2026-07-19T07:07:06Z

Codecov Report

❌ Patch coverage is 99.11817% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.05%. Comparing base (bd3a31a) to head (e1e9a53).
⚠️ Report is 8 commits behind head on master.

Files with missing lines	Patch %	Lines
src/hazardous/hash/blake3/internal.rs	99.25%	2 Missing ⚠️
src/hazardous/hash/blake3/cvstack.rs	98.94%	1 Missing ⚠️
tests/hash/blake3_kat.rs	96.96%	1 Missing ⚠️
tests/hash/mod.rs	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #641      +/-   ##
==========================================
- Coverage   99.14%   99.05%   -0.10%     
==========================================
  Files         108      112       +4     
  Lines       19961    20527     +566     
==========================================
+ Hits        19791    20332     +541     
- Misses        170      195      +25

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

brycx · 2026-07-24T08:33:16Z

clippy / linting warning in a file I have not touched (I'm not sure how that happened)

You were unlucky and hit a new Rust version which introduced a new lint which made the CI fail. So no fault at all on your part. If you rebase on current master, this should be fixed now.

Note: The "derive key" mode has been omitted from this PR to keep the scope focused on standard hashing. The underlying state machine has been structured so that key derivation can be easily added in a future PR if desired.

This initial implementation establishes a single-threaded baseline. Because BLAKE3's tree structure is designed for infinite parallelism, a natural next step will be adding a data-parallelism feature flag to support multi-threaded hashing for large inputs.

This is a perfect approach, thank you for taking this into account!

brycx

Thank you a lot for all this hard work, @jakub-mata! I get the feeling you were careful and put a lot of effort into it, which really tells.

Let me know if any of my review comments don't make sense or you believe you have a better approach.

brycx · 2026-07-25T08:17:01Z

+    /// Regular hashing
+    Hash,
+    /// Hashing parametrized with a key. Useful for MACs.
+    KeyedHash {


This cannot simply be a raw array. We have newtypes for secret types that need to be used in order to make sure they aren't leaked or misused.

What we need here is something similar to how we handle it for the other MACs:

construct_secret_key! { /// A type to represent the secret key that BLAKE2b uses for keyed mode. /// /// # Errors: /// An error will be returned if: /// - `slice` is empty. /// - `slice` is greater than 64 bytes. /// /// # Panics: /// A panic will occur if: /// - Failure to generate random bytes securely. (SecretKey, test_secret_key, 1, BLAKE2B_KEYSIZE, 32) }

Then we'd convert the key internally to words. That way we avoid forcing users to make a conversion, since secrets keys are usually handled as raw bytes.

Lore (not necessary):

This leads us to why the current BLAKE2b is split across two hazardous modules. Because MACs are by definition also sensitive types, that need constant-time handling and omitted debugs. But let's keep that out of scope for this PR for now, as long as we make the secret key the correct newtype.

If you have any ideas for nice abstraction between those two, I'm all open for suggestions. Feel free to ignore though.

Those are the things I know in theory but don't apply in practice :) Hopefully, I've used the abstraction correctly.

While you've correctly set up SecretKey, it's not being used here. Because Blake3 derives Debug, which Mode does as well and mode is a field for Blake3, a Debug call to Blake3 instance will leak the secret key here.

So this field Mode.key either needs to be SecretKey instead of array or the parsing/holding of the key needs to be removed entirely from this enum

brycx · 2026-07-25T08:41:41Z

+    // The popped value is not manually deleted, only the counter is decreased.
+    fn pop(&mut self) -> ChainingValue {
+        self.stack_len -= 1;
+        self.stack[self.stack_len as usize] // Panics if out-of-bounds


Is it reasonable to expect this to panic at any time?

stack_len is updated only in the push and pop functions so the panics do not occur. I removed the comment.

brycx · 2026-07-25T08:47:14Z

+
+        reader.fill(out_slice);
+    }
+}


We want to add a test here at the bottom, that implements StreamingContextConsistencyTester found here: src/test_framework/incremental_interface.rs.

This is pretty crucial for testing the correctness of incremental handling of inputs.

Done, but I've used a tiny workaround. My finalize() function consumes the hasher, which I find quite nice as it disallows any further usage. However, the testing trait expects to be able to call it, which in my case just cannot happen (I suppose the usage of mut& self is expected with an internal flag, something like is_finalized). Instead of changing the API, there is a special testing struct which has this flag and an inner hasher to work around it.

I hope that's fine.

I completely understand your preference for this type of API, there's less testing even. But it does go against every other streaming API exposed in Orion, which isn't super user-friendly either. I'll have to think about this a bit more.

brycx · 2026-07-25T08:57:16Z

+        let take = min(want, data.len());
+        self.chunk.update(&data[..take]);
+
+        self.update(&data[take..])


This recursive handling here worries me a bit. In release mode, I don't think this would overflow the stack, but in debug it could (not a argument to not remove recursion in crypto-code). If we ever start testing large inputs, this would eventually SIGABRT, depending on the stack for the test thread AFIU.

Have you looked at how we handle this with while !data.is_empty(), @jakub-mata? I think that approach would be more robust than this recursion-based one.

That's reasonable, I've removed the recursion here and in the update() function inside ChunkState (called on line 112 here). A while loop is used instead.

The new version implements the `Drop` trait for various structs, where zeroization occurs. `Blake3`, which contains the secret key used for a keyed hash (if applicable). ChunkState and TreeStack also implement it, as they contain the key, its traces, or internal state.

brycx

I'll have to think about what to do with the mut self and &mut self a bit more.

The rest is just adding omitted debugs where you've added the zeroization.

brycx · 2026-07-30T08:27:09Z

+
+#[derive(Debug, Clone)]
+pub(crate) struct TreeStack {
+    stack: [ChainingValue; MAX_TREE_DEPTH],


If the stack is zeroized, then it also needs to be an omitted debug.

brycx · 2026-07-30T08:28:27Z

+    chunk_counter: u64,
+    /// Input buffer for the next block. When full, it is compressed
+    /// and flushed.
+    block: [u8; BLOCK_LEN],


If secret data flows into here and is zeroized it also needs omitted debug.

brycx · 2026-07-30T08:29:32Z

+#[derive(PartialEq, Debug, Clone)]
+pub(crate) struct ChunkState {
+    /// The resulting chaining value of the last compressed block.
+    cv: ChainingValue,


If secret data flows into here and is zeroized it also needs omitted debug.

brycx · 2026-07-30T08:30:49Z

+    /// Regular hashing
+    Hash,
+    /// Hashing parametrized with a key. Useful for MACs.
+    KeyedHash {


While you've correctly set up SecretKey, it's not being used here. Because Blake3 derives Debug, which Mode does as well and mode is a field for Blake3, a Debug call to Blake3 instance will leak the secret key here.

So this field Mode.key either needs to be SecretKey instead of array or the parsing/holding of the key needs to be removed entirely from this enum

brycx · 2026-07-30T08:35:09Z

+
+        reader.fill(out_slice);
+    }
+}


I completely understand your preference for this type of API, there's less testing even. But it does go against every other streaming API exposed in Orion, which isn't super user-friendly either. I'll have to think about this a bit more.

jakub-mata added 19 commits July 12, 2026 15:27

Setup for blake3 implementation

5bc38f2

Create struct for CFState

975b823

Implement push & finalize on stack

87cd9be

Finalize first version

6b90d6f

Restructure repository

9a2a0ea

Remove unnecessary doc

07f07a5

Include basic unit testing

210cc9f

FIX: use to_le_array in CFState::from(&ChunkState)

afd791e

FIX: unused msg_copy

c0b74e6

FIX: use correct message indeces & truncate with XOR

6f9c697

Update comment

06adc6b

Pass kat tests

56b9f3e

Supply known hash tests

d0521fb

Comment out derive key constants for future use

10a3ed6

Rename variable

ef0691c

Add blake3 known values tests

09643fd

Update comments

fdcf21d

Remove debug print

831117c

use for_each iter for clippy

c14aff7

brycx requested changes Jul 25, 2026

View reviewed changes

jakub-mata added 8 commits July 25, 2026 17:07

Add source of origin for test values & clarifying comments

43d54a8

Derive attributes to important structs

3197a92

Use Blake3 updated API

18cddd3

Remove recursion in hasher update

d9484a0

FIX unused sum & implement reset()

9ab5fe2

Add licence

83a997d

Implement incremental testing

555c387

Use array instead of vector in tests

e1e9a53

brycx requested changes Jul 30, 2026

View reviewed changes

Uh oh!

Conversation

jakub-mata commented Jul 19, 2026

Uh oh!

codecov Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

brycx commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brycx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brycx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Jul 19, 2026 •

edited

Loading

brycx commented Jul 24, 2026 •

edited

Loading