Add support for BLAKE2 algorithms by athoelke · Pull Request #339 · ARM-software/psa-api

athoelke · 2026-02-13T17:23:26Z

One aspect of the PR that I would like feedback on:

Does it make sense to have a single BLAKE2 key type for both BLAKE2s and BLAKE2b MAC algorithms?
- It did not seem necessary to consume two symmetric key type value for the two algorithms.
- However, we have only used 6/128 of those values; and BLAKE2s has to reject keys longer than 32 bytes, which will not be detected at key creation/import time.

Fixes #333

gilles-peskine-arm

Mostly LGTM, with a couple of questions and suggestions.

gilles-peskine-arm · 2026-02-16T17:40:58Z

doc/crypto/api/ops/mac.rst

+    To select a non-default tag length ``tag_len``, use :code:`PSA_ALG_TRUNCATED_MAC(PSA_ALG_BLAKE2B_MAC, tag_len)` as the algorithm.
+
+    .. note::
+        When BLAKE2b is used as general MAC algorithm, it is recommended to use an output tag of at least 64 bits (8 bytes).


Why are we stating 64 bits as a minimum recommended MAC length? We aren't doing that for other MAC algorithms.

It's the diection of travel for official MAC recommendations - NIST SP 800-227 will say this for HMAC.

We could say nothing, or we could put general recommendations/guidelines like this into the MAC chapter preamble instead, as this is not really BLAKE2 specific guidance?

Conclusion: if anywhere, guidance around choosing adequate tag lengths should be in PSA_ALG_TRUNCATED_MAC.

gilles-peskine-arm · 2026-02-16T18:01:12Z

doc/crypto/api/keys/types.rst


        A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.

+.. macro:: PSA_KEY_TYPE_BLAKE2


Does it make sense to have a single BLAKE2 key type for both BLAKE2s and BLAKE2b MAC algorithms?

I have no strong feelings about this. Technically BLAKE2s-MAC and BLAKE2b-MAC are families of algorithms that use different families of keys, since they have different length constraints. But since they're just an array of bytes, it doesn't really matter.

Might be better to be separate, except that if we implement this idea, then a single key type for the family of PSA_ALG_BLAKE2_MAC() algorithms actually makes more sense.

Kept a single key type in the updated PR

gilles-peskine-arm · 2026-02-16T18:15:06Z

doc/crypto/api/ops/hash.rst


        It is recommended that these compound algorithms are not supported with `PSA_ALG_ASCON_HASH256`.

+.. macro:: PSA_ALG_BLAKE2S_HASH256


I assume nobody is using the parallel versions, Blake2bp and Blake2sp?

The only thing I can find on the web (other than software that supports a lot of different hash functions) is Winrar using BLAKE2sp. And p7zip also supports BLAKE2sp but no other BLAKE variant.

According to BLAKE2 §2.11, “parallel hashes have exactly the same interfaces as their sequential counterparts”. So specifying them in PSA would be very cheap, we just need to give them an algorithm encoding. So I lean towards doing it.

Without an explicit request for these variants, with specific use case(s), we might not specify the right algorithms, as BLAKE2 does not map neatly onto our hash vs xof vs MAC taxonomy.

True, but the only use I've found of a p variant is the s hash, with its nominal length.

So perhaps we can add PSA_ALG_BLAKE2SP_HASH256 and PSA_ALG_BLAKE2BP_HASH512 and the associated MACs, as the specification is less effort if done now with the non-parallel variants.

gilles-peskine-arm · 2026-02-16T18:17:16Z

doc/crypto/appendix/encodings.rst

+    BLAKE2s-MAC, 0, ``0x03``, `PSA_ALG_BLAKE2S_MAC`, ``0x03800300`` :sup:`a`
+    BLAKE2b-MAC, 0, ``0x04``, `PSA_ALG_BLAKE2B_MAC`, ``0x03800400`` :sup:`a`


Especially if we add BLAKE2sp and BLAKE2bp, could we have an encoding where (PSA_ALG_BLAKE2S_HASH256 & 3) == (PSA_ALG_BLAKE2S_MAC & 3) etc.?

Are you suggesting that we use [some of] bits 7:0 in the MAC identifier to create a link to the related hash identifier? Given that BLAKE2s-MAC is not parameterized by hash (unlike HMAC), we could instead have BLAKE2s-MAC and BLAKE2b-MAC use the same MAC-TYPE value, and then reuse the HASH identifer bits 7:0? e.g. BLAKE2S_HASH256 == 0x02000019, BLAKE2B_HASH512 == 0x0200001A so BLAKE2S_MAC == 0x03800319; BLAKE2B_MAC == 0x0380031A?

This stops being 'neat' if we ever need to add BLAKE2s hash variants with shorter outputs, which cannot share the same Hash identifier value....

Oh, no, I'd missed that we're not using the low-order bits in MAC and other non-hash algorithms. I didn't mean to deviate from that rule. So what I'd like is for bits 8..9 (or 8, or 8..10, depending on how many BLAKE variants we specify) of the MAC to indicate the BLAKE variant with the same encoding as bits 0..1 of the hash.

If we also add the parallel hashes, then it would make sense to define PSA_ALG_BLAKE2_MAC() which accepts one of the four base BLAKE2 hash algorithms as a parameter.

We can also set the BLAKE2 hash algorithms to be consecutive identifiers starting with a value that has bits[1:0] == 2b00.

doc/crypto/api/ops/hash.rst

gilles-peskine-arm · 2026-02-16T18:25:30Z

doc/crypto/api/ops/hash.rst

+
+        .. versionadded:: 1.5
+
+    The BLAKE2s-256 hash is BLAKE2s with a zero-length key, and a 256 bit (32 byte) output.


Nit (same for BLAKE2b):

Suggested change

The BLAKE2s-256 hash is BLAKE2s with a zero-length key, and a 256 bit (32 byte) output.

The BLAKE2s-256 hash is BLAKE2s with a zero-length key, and a 256-bit (32-byte) output.

Add support for BLAKE2 algorithms

f401135

athoelke added this to the Crypto 1.5 milestone Feb 13, 2026

athoelke requested review from MarcusJGStreets and gilles-peskine-arm February 13, 2026 17:23

athoelke self-assigned this Feb 13, 2026

athoelke added enhancement New feature or request Crypto API Issue or PR related to the Cryptography API labels Feb 13, 2026

athoelke added this to PSA Certified API development Feb 13, 2026

athoelke moved this to In Progress in PSA Certified API development Feb 13, 2026

gilles-peskine-arm requested changes Feb 16, 2026

View reviewed changes

athoelke added 2 commits February 24, 2026 18:46

Rework the BLAKE2 hash and MAC algorithm identifiers

1e1f368

Lost typographic fixes

f76e95a


		A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.

		.. macro:: PSA_KEY_TYPE_BLAKE2


		It is recommended that these compound algorithms are not supported with `PSA_ALG_ASCON_HASH256`.

		.. macro:: PSA_ALG_BLAKE2S_HASH256

		BLAKE2s-MAC, 0, ``0x03``, `PSA_ALG_BLAKE2S_MAC`, ``0x03800300`` :sup:`a`
		BLAKE2b-MAC, 0, ``0x04``, `PSA_ALG_BLAKE2B_MAC`, ``0x03800400`` :sup:`a`


		.. versionadded:: 1.5

		The BLAKE2s-256 hash is BLAKE2s with a zero-length key, and a 256 bit (32 byte) output.

Conversation

athoelke commented Feb 13, 2026

Uh oh!

gilles-peskine-arm left a comment

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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants