Skip to content

Add BLAKE2b-512, BLAKE2s-256 (RFC 7693) and BLAKE3 (#123) - #180

Draft
roy-basmacier wants to merge 4 commits into
bcgit:release/0.1.4alphafrom
roy-basmacier:feature/123-blake
Draft

Add BLAKE2b-512, BLAKE2s-256 (RFC 7693) and BLAKE3 (#123)#180
roy-basmacier wants to merge 4 commits into
bcgit:release/0.1.4alphafrom
roy-basmacier:feature/123-blake

Conversation

@roy-basmacier

@roy-basmacier roy-basmacier commented Oct 25, 2026 •
edited
Loading

Copy link
Copy Markdown

Adds the three BLAKE hashes requested in #123 for OpenSSL provider provisioning, on the key-object API of feature/key-rework-memory (#172): two new crates wired into the factories, the CLI and the stack-memory benches. Other BLAKE2 digest lengths, salt/personalisation, BLAKE2bp/sp/X and tree mode are out of scope.

blake2 (new crate bouncycastle-blake2):

  • BLAKE2b_512 and BLAKE2s_256 implement Hash and Suspendable; G, F, the parameter block and the final-t rule are commented against RFC 7693 s. 3.1-3.3. blake2b.rs and blake2s.rs are kept structurally identical.
  • The native keyed mode (not HMAC): key objects BLAKE2b_512_MACKey and BLAKE2s_256_MACKey (FromAnyKeyMaterial, MacGenerationKey, MacVerificationKey) hand out BLAKE2b_512_MAC / BLAKE2s_256_MAC workers. Key checks run type, then strength, then length (1..=64 / 1..=32).
  • AlgorithmOID: id-blake2b512 and id-blake2s256 (RFC 7693 s. 4), on the hash and MAC types.
  • Suspended states are 213 bytes (BLAKE2b-512) and 109 bytes (BLAKE2s-256), hash and MAC alike. They record the key length kk, so a MAC state cannot be resumed as a hash (which would finish the MAC without the key), nor a hash state as a MAC, nor a MAC state under a key of another length.

blake3 (new crate bouncycastle-blake3):

  • BLAKE3 implements Hash and XOF in hash mode; BLAKE3Squeezer streams the extended output. Both are Suspendable (states of 1874 and 180 bytes). Squeezer resume refuses an output block counter above 2^58 (s. 2.6: ell < 2^64 bytes), so a resumed stream can never wrap and repeat output.
  • derive_key is its own type, BLAKE3DeriveKey (Hash + XOF, constructed with a context string). It is deliberately not Suspendable, and neither is its squeezer BLAKE3DeriveKeySqueezer: a derive_key state holds key material verbatim.
  • keyed_hash: key object BLAKE3KeyedHashKey (exactly 32 bytes) hands out BLAKE3KeyedHash workers, which keep an inherent into_squeezer for extended output. BLAKE3KeyedSqueezer is deliberately not Suspendable. The keyed state is 1838 bytes.
  • The engine follows the reference implementation's chunk state and 54-entry CV stack (spec s. 2.4-2.6, 5.1).

Both crates:

  • MAC output truncates to the caller's buffer with a 4-byte floor (MIN_MAC_OUTPUT_LEN, one constant in bouncycastle_core::traits beside MAC); every _out function zeroizes the buffer before any error check. Partial-bit input: 0 bits is a whole-byte message, 1..=7 returns InvalidInput, more returns InvalidLength.
  • Keyed workers implement SuspendableKeyed with the key object as the key. Suspended states hold no key bytes, resume rebuilds the key-derived fields from the key object, and resume-time comparisons on key-derived values are constant time.
  • Design note: a suspended keyed state still lets its holder compute tags for extensions of the absorbed prefix (BLAKE2 once the key block is compressed; BLAKE3 only within the first chunk). HMAC does not have this property. It is documented and pinned by tests.

factory: HashFactory gains BLAKE2b-512, BLAKE2s-256 and BLAKE3; XOFFactory gains BLAKE3; MACFactory gains the three BLAKE MAC keys and workers. A new Memory Usage section notes that BLAKE3's 1728-byte chaining-value stack makes HashFactory, XOFFactory and MACFactoryWorker 1888 bytes (SHA-3, at 440, was the largest before).

cli: blake2b-512, blake2s-256, blake2b-512-mac, blake2s-256-mac, blake3, blake3-keyed-hash and blake3-derive-key, all streaming. cli/tests/test_blake.sh adds 16 tests on the shell harness. Every MAC command now shares one key loader, so HMAC and KMAC also let --key-file win over --key, as their help text always said, and report bad hex or a missing key file instead of panicking; test_hmac.sh pins the precedence.

tests: RFC 7693 Appendix A/B, selections from the official BLAKE2 KAT, the bc-test-data Blake2KAT.txt sweep (512 + 512 records), all 35 official BLAKE3 vectors in all three modes, and the core-test-framework suites for Hash, XOF, MAC keys, key construction and suspend/resume. Wycheproof has no BLAKE vectors. cargo mutants: blake2 404 tested, 10 missed; blake3 417 tested, 9 missed, 8 timeouts (non-terminating loops); every miss is an equivalent rewrite with a "Mutants note:" at the site.

#![no_std] remains a todo in both crates, as in every hash crate, blocked by the Vec return types in core::traits::Hash.

Assisted-by: Claude:claude-mythos-5-1
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5-5

@ounsworth ounsworth added this to the 0.1.4alpha milestone Oct 25, 2026
roy-basmacier pushed a commit to roy-basmacier/bc-rust that referenced this pull request Nov 2, 2026
royb
blake2, blake3, cli, factory: address the review of bcgit#180
6f5b43a 
blake2:
- The suspended state records the parameter block's key length kk (one
  byte; states grow to 213 / 109 bytes). After the first compression the
  hash and MAC states were byte-identical, so a MAC state resumed as a
  hash finished the MAC with no key, and a hash state resumed as a MAC
  verified a plain digest as a tag. Resume now refuses kk != 0 on the hash
  side and kk != the key's kk on the MAC side; a valid key of the same
  length is still not detected after a compression (documented).
- read_state rejects t > 0 with an empty buffer: update always keeps at
  least one byte back after a compression, and finishing such a state gave
  a digest of no byte string.
- The t == 0 h checks compare in constant time (ct_eq_bytes over the
  serialized words, held in Secret buffers).

blake3:
- derive_key moves to its own type, BLAKE3DeriveKey (Hash + XOF), which is
  not Suspendable, nor is its squeezer: a derive_key state held up to 64
  bytes of key material verbatim, which Suspendable forbids.
  BLAKE3::new_derive_key is removed; BLAKE3 is the hash mode only, and
  BLAKE3 / BLAKE3Squeezer resume refuse derive_key (and keyed) states.
- BLAKE3Squeezer resume rejects an output block counter above 2^58 (s. 2.6:
  ell < 2^64 bytes). A counter near u64::MAX panicked in debug builds and
  wrapped in release, re-emitting output already handed out.
- The hash-mode IV check compares in constant time.

Both crates use one MIN_MAC_OUTPUT_LEN, now in bouncycastle_core::traits
beside MAC, instead of a copy each.

cli: one MAC key loader for every MAC command (helpers::load_mac_key, with
the algorithm's key-length range). HMAC and KMAC now let --key-file win
over --key, as their help text always said, and report bad hex or a
missing key file instead of panicking. test_hmac.sh pins the precedence.

factory: a Memory Usage section. BLAKE3's 1728-byte chaining-value stack
makes HashFactory, XOFFactory and MACFactoryWorker 1888 bytes (SHA-3, at
440, was the largest before).

docs: each spec quote on security strength now lives once, on the
Algorithm impl, and the keyed BLAKE3 suspend note is stated once, on the
SuspendableKeyed impl. The derivation: the key words enter only as the
first chaining value of each chunk and parent (s. 2.4, 2.5), so while the
prefix is 65..=1024 bytes with an empty CV stack the state finishes any
extension within the first chunk without the key.
roy-basmacier pushed a commit to roy-basmacier/bc-rust that referenced this pull request Nov 2, 2026
royb
blake2, blake3, cli, factory: address the review of bcgit#180
6adc1cd 
blake2:
- The suspended state records the parameter block's key length kk (one
  byte; states grow to 213 / 109 bytes). After the first compression the
  hash and MAC states were byte-identical, so a MAC state resumed as a
  hash finished the MAC with no key, and a hash state resumed as a MAC
  verified a plain digest as a tag. Resume now refuses kk != 0 on the hash
  side and kk != the key's kk on the MAC side; a valid key of the same
  length is still not detected after a compression (documented).
- read_state rejects t > 0 with an empty buffer: update always keeps at
  least one byte back after a compression, and finishing such a state gave
  a digest of no byte string.
- The t == 0 h checks compare in constant time (ct_eq_bytes over the
  serialized words, held in Secret buffers).

blake3:
- derive_key moves to its own type, BLAKE3DeriveKey (Hash + XOF), which is
  not Suspendable, nor is its squeezer: a derive_key state held up to 64
  bytes of key material verbatim, which Suspendable forbids.
  BLAKE3::new_derive_key is removed; BLAKE3 is the hash mode only, and
  BLAKE3 / BLAKE3Squeezer resume refuse derive_key (and keyed) states.
- BLAKE3Squeezer resume rejects an output block counter above 2^58 (s. 2.6:
  ell < 2^64 bytes). A counter near u64::MAX panicked in debug builds and
  wrapped in release, re-emitting output already handed out.
- The hash-mode IV check compares in constant time.

Both crates use one MIN_MAC_OUTPUT_LEN, now in bouncycastle_core::traits
beside MAC, instead of a copy each.

cli: one MAC key loader for every MAC command (helpers::load_mac_key, with
the algorithm's key-length range). HMAC and KMAC now let --key-file win
over --key, as their help text always said, and report bad hex or a
missing key file instead of panicking. test_hmac.sh pins the precedence.

factory: a Memory Usage section. BLAKE3's 1728-byte chaining-value stack
makes HashFactory, XOFFactory and MACFactoryWorker 1888 bytes (SHA-3, at
440, was the largest before).

docs: each spec quote on security strength now lives once, on the
Algorithm impl, and the keyed BLAKE3 suspend note is stated once, on the
SuspendableKeyed impl. The derivation: the key words enter only as the
first chaining value of each chunk and parent (s. 2.4, 2.5), so while the
prefix is 65..=1024 bytes with an empty CV stack the state finishes any
extension within the first chunk without the key.
@dghgit
dghgit force-pushed the feature/key-rework-memory branch from 3c170c9 to 81cef74 Compare November 3, 2026 02:36
@hubot
hubot deleted the branch bcgit:feature/key-rework-memory November 3, 2026 13:17
@hubot
hubot deleted the branch bcgit:feature/key-rework-memory November 4, 2026 22:43
@dghgit
dghgit force-pushed the feature/123-blake branch from a1016d6 to 280b233 Compare November 5, 2026 01:35
dghgit pushed a commit to roy-basmacier/bc-rust that referenced this pull request Nov 5, 2026
royb @dghgit
blake2, blake3, cli, factory: address the review of bcgit#180
6434d27 
blake2:
- The suspended state records the parameter block's key length kk (one
  byte; states grow to 213 / 109 bytes). After the first compression the
  hash and MAC states were byte-identical, so a MAC state resumed as a
  hash finished the MAC with no key, and a hash state resumed as a MAC
  verified a plain digest as a tag. Resume now refuses kk != 0 on the hash
  side and kk != the key's kk on the MAC side; a valid key of the same
  length is still not detected after a compression (documented).
- read_state rejects t > 0 with an empty buffer: update always keeps at
  least one byte back after a compression, and finishing such a state gave
  a digest of no byte string.
- The t == 0 h checks compare in constant time (ct_eq_bytes over the
  serialized words, held in Secret buffers).

blake3:
- derive_key moves to its own type, BLAKE3DeriveKey (Hash + XOF), which is
  not Suspendable, nor is its squeezer: a derive_key state held up to 64
  bytes of key material verbatim, which Suspendable forbids.
  BLAKE3::new_derive_key is removed; BLAKE3 is the hash mode only, and
  BLAKE3 / BLAKE3Squeezer resume refuse derive_key (and keyed) states.
- BLAKE3Squeezer resume rejects an output block counter above 2^58 (s. 2.6:
  ell < 2^64 bytes). A counter near u64::MAX panicked in debug builds and
  wrapped in release, re-emitting output already handed out.
- The hash-mode IV check compares in constant time.

Both crates use one MIN_MAC_OUTPUT_LEN, now in bouncycastle_core::traits
beside MAC, instead of a copy each.

cli: one MAC key loader for every MAC command (helpers::load_mac_key, with
the algorithm's key-length range). HMAC and KMAC now let --key-file win
over --key, as their help text always said, and report bad hex or a
missing key file instead of panicking. test_hmac.sh pins the precedence.

factory: a Memory Usage section. BLAKE3's 1728-byte chaining-value stack
makes HashFactory, XOFFactory and MACFactoryWorker 1888 bytes (SHA-3, at
440, was the largest before).

docs: each spec quote on security strength now lives once, on the
Algorithm impl, and the keyed BLAKE3 suspend note is stated once, on the
SuspendableKeyed impl. The derivation: the key words enter only as the
first chaining value of each chunk and parent (s. 2.4, 2.5), so while the
prefix is 65..=1024 bytes with an empty CV stack the state finishes any
extension within the first chunk without the key.
@dghgit
dghgit changed the base branch from feature/key-rework-memory to release/0.1.4alpha November 5, 2026 01:40
royb and others added 4 commits November 5, 2026 13:47
royb @claude @dghgit
Add BLAKE2b-512, BLAKE2s-256 (RFC 7693) and BLAKE3 (bcgit#123)
14c853f 
Adds the three BLAKE hashes requested in bcgit#123 for OpenSSL provider
provisioning, on the key-object API of feature/key-rework-memory (bcgit#172):
two new crates wired into the factories, the CLI and the stack-memory
benches. Other BLAKE2 digest lengths, salt/personalisation, BLAKE2bp/sp/X
and tree mode are out of scope.

blake2 (new crate bouncycastle-blake2):
- BLAKE2b_512 and BLAKE2s_256 implement Hash and Suspendable; G, F, the
  parameter block and the final-t rule are commented against RFC 7693
  s. 3.1-3.3. blake2b.rs and blake2s.rs are kept structurally identical.
- The native keyed mode (not HMAC): key objects BLAKE2b_512_MACKey and
  BLAKE2s_256_MACKey (FromAnyKeyMaterial, MacGenerationKey,
  MacVerificationKey) hand out BLAKE2b_512_MAC / BLAKE2s_256_MAC workers.
  Key checks run type, then strength, then length (1..=64 / 1..=32).
- AlgorithmOID: id-blake2b512 and id-blake2s256 (RFC 7693 s. 4), on the
  hash and MAC types.

blake3 (new crate bouncycastle-blake3):
- BLAKE3 implements Hash and XOF in hash mode (new) and derive_key mode
  (new_derive_key); BLAKE3Squeezer streams the extended output.
- keyed_hash: key object BLAKE3KeyedHashKey (exactly 32 bytes) hands out
  BLAKE3KeyedHash workers, which keep an inherent into_squeezer for
  extended output. BLAKE3KeyedSqueezer is deliberately not Suspendable.
- The engine follows the reference implementation's chunk state and
  54-entry CV stack (spec s. 2.4-2.6, 5.1).

Both crates:
- MAC output truncates to the caller's buffer with a 4-byte floor
  (MIN_MAC_OUTPUT_LEN); every _out function zeroizes the buffer before any
  error check. Partial-bit input: 0 bits is a whole-byte message, 1..=7
  returns InvalidInput, more returns InvalidLength.
- Keyed workers implement SuspendableKeyed with the key object as the key.
  Suspended states hold no key bytes, and resume rebuilds the key-derived
  fields from the key object.
- Design note: a suspended keyed state still lets its holder compute tags
  for extensions of the absorbed prefix (BLAKE2 once the key block is
  compressed; BLAKE3 only within the first chunk). HMAC does not have this
  property. It is documented and pinned by tests.

factory: HashFactory gains BLAKE2b-512, BLAKE2s-256 and BLAKE3; XOFFactory
gains BLAKE3; MACFactory gains the three BLAKE MAC keys and workers.

cli: blake2b-512, blake2s-256, blake2b-512-mac, blake2s-256-mac, blake3,
blake3-keyed-hash and blake3-derive-key, all streaming. cli/tests/
test_blake.sh adds 16 tests on the shell harness.

tests: RFC 7693 Appendix A/B, selections from the official BLAKE2 KAT, the
bc-test-data Blake2KAT.txt sweep (512 + 512 records), all 35 official BLAKE3
vectors in all three modes, and the core-test-framework suites for Hash,
XOF, MAC keys, key construction and suspend/resume. Wycheproof has no BLAKE
vectors. cargo mutants: blake2 378 tested, 10 missed; blake3 384 tested,
9 missed, 8 timeouts (non-terminating loops); every miss is an equivalent
rewrite with a "Mutants note:" at the site.

the Vec return types in core::traits::Hash.

Assisted-by: Claude:claude-mythos-5-1
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
royb @dghgit
blake2, blake3, cli, factory: address the review of bcgit#180
ab67831 
blake2:
- The suspended state records the parameter block's key length kk (one
  byte; states grow to 213 / 109 bytes). After the first compression the
  hash and MAC states were byte-identical, so a MAC state resumed as a
  hash finished the MAC with no key, and a hash state resumed as a MAC
  verified a plain digest as a tag. Resume now refuses kk != 0 on the hash
  side and kk != the key's kk on the MAC side; a valid key of the same
  length is still not detected after a compression (documented).
- read_state rejects t > 0 with an empty buffer: update always keeps at
  least one byte back after a compression, and finishing such a state gave
  a digest of no byte string.
- The t == 0 h checks compare in constant time (ct_eq_bytes over the
  serialized words, held in Secret buffers).

blake3:
- derive_key moves to its own type, BLAKE3DeriveKey (Hash + XOF), which is
  not Suspendable, nor is its squeezer: a derive_key state held up to 64
  bytes of key material verbatim, which Suspendable forbids.
  BLAKE3::new_derive_key is removed; BLAKE3 is the hash mode only, and
  BLAKE3 / BLAKE3Squeezer resume refuse derive_key (and keyed) states.
- BLAKE3Squeezer resume rejects an output block counter above 2^58 (s. 2.6:
  ell < 2^64 bytes). A counter near u64::MAX panicked in debug builds and
  wrapped in release, re-emitting output already handed out.
- The hash-mode IV check compares in constant time.

Both crates use one MIN_MAC_OUTPUT_LEN, now in bouncycastle_core::traits
beside MAC, instead of a copy each.

cli: one MAC key loader for every MAC command (helpers::load_mac_key, with
the algorithm's key-length range). HMAC and KMAC now let --key-file win
over --key, as their help text always said, and report bad hex or a
missing key file instead of panicking. test_hmac.sh pins the precedence.

factory: a Memory Usage section. BLAKE3's 1728-byte chaining-value stack
makes HashFactory, XOFFactory and MACFactoryWorker 1888 bytes (SHA-3, at
440, was the largest before).

docs: each spec quote on security strength now lives once, on the
Algorithm impl, and the keyed BLAKE3 suspend note is stated once, on the
SuspendableKeyed impl. The derivation: the key words enter only as the
first chaining value of each chunk and parent (s. 2.4, 2.5), so while the
prefix is 65..=1024 bytes with an empty CV stack the state finishes any
extension within the first chunk without the key.
royb @dghgit
blake2, blake3, factory: follow feature/key-rework-memory's trait cha…
1bff7ad 
…nges

Rebased onto bb67b77, which reshaped Hash and MAC (711a571, 0e391c4):

- Hash and MAC lose max_security_strength(&self) for the AlgorithmInfo
  supertrait, which every Algorithm implements. The BLAKE impls drop their
  own copies; the values come from the Algorithm impls as before.
- The one-shot hash(data) / hash_out(data, out) move off Hash onto
  HashOneShot. BLAKE2b_512, BLAKE2s_256 and BLAKE3 implement it, so the call
  is BLAKE3::hash(msg). BLAKE3DeriveKey takes its context at construction,
  so like cSHAKE it has inherent hash / hash_out methods instead.
- factory: the BLAKE arms are added to the AlgorithmInfo impls and to
  MACFactoryWorker's MAC impl, whose forwarding macro became written-out
  matches upstream.

Tests, doc examples and the mem benches follow the same call forms.

The CLI MAC key loader now replaces the upstream fix to mac_cmd's own
loader (same file-wins order); upstream's HMAC precedence test is kept and
this branch's duplicate dropped.
@dghgit
blake2, blake3, cli: the adaptations to release/0.1.4alpha, carried o…
d43cc3b 
…ver the rebase from feature/key-rework-memory

The release's CLI already reads every MAC key through mac_cmd's own load_mac_key, which takes
any length (HMAC hashes a long key, KMAC encodes its length), so the review's shared 64-byte
loader is not carried over; the bounded loader stays BLAKE-only as helpers::load_blake_mac_key,
now over the release's load_secret input rule. FixedSeedRNG moved to bouncycastle-rng and lost
its const parameter.

Assisted-by: Claude:claude-opus-5-5
@dghgit
dghgit force-pushed the feature/123-blake branch from 280b233 to d43cc3b Compare November 5, 2026 03:57

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dghgit dghgit Awaiting requested review from dghgit
@ounsworth ounsworth Awaiting requested review from ounsworth

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

0.1.4alpha

Development

Successfully merging this pull request may close these issues.

3 participants

@roy-basmacier @ounsworth @dghgit