Skip to content

Add support for BLAKE2 algorithms #339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
athoelke wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add support for BLAKE2 algorithms #339

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f401135
Add support for BLAKE2 algorithms
athoelke Feb 13, 2026
1e1f368
Rework the BLAKE2 hash and MAC algorithm identifiers
athoelke Feb 24, 2026
f76e95a
Lost typographic fixes
athoelke Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions doc/crypto/about/references
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

.. reference:: PSM
:title: Platform Security Model
:doc_no: ARM DEN 0128
:url: developer.arm.com/documentation/den0128
:title: Platform Security Model
:doc_no: ARM DEN 0128
:url: developer.arm.com/documentation/den0128

.. reference:: PSA-FFM
:title: Arm® Platform Security Architecture Firmware Framework
Expand Down Expand Up @@ -539,3 +539,15 @@
:author: IETF
:publication: January 2020
:url: tools.ietf.org/html/rfc8702.html

.. reference:: RFC7693
:title: The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC)
:author: J-P. Aumasson, M-J. Saarinen
:publication: November 2015
:url: tools.ietf.org/html/rfc7693.html

.. reference:: BLAKE2
:title: BLAKE2: simpler, smaller, fast as MD5
:author: Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O’Hearn, Christian Winnerlein
:publication: January 2013
:url: blake2.net/blake2.pdf
8 changes: 8 additions & 0 deletions doc/crypto/api.db/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ typedef struct psa_custom_key_parameters_t {
#define PSA_ALG_ASCON_XOF128 ((psa_algorithm_t)0x0D000300)
#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
/* specification-defined value */
#define PSA_ALG_BLAKE2BP_HASH512 ((psa_algorithm_t)0x0200001F)
#define PSA_ALG_BLAKE2B_HASH512 ((psa_algorithm_t)0x0200001E)
#define PSA_ALG_BLAKE2SP_HASH256 ((psa_algorithm_t)0x0200001D)
#define PSA_ALG_BLAKE2S_HASH256 ((psa_algorithm_t)0x0200001C)
#define PSA_ALG_BLAKE2_MAC(hash_alg) /* specification-defined value */
#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)
#define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04404000)
#define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04404100)
Expand Down Expand Up @@ -106,6 +111,8 @@ typedef struct psa_custom_key_parameters_t {
#define PSA_ALG_IS_AEAD(alg) /* specification-defined value */
#define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) /* specification-defined value */
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) /* specification-defined value */
#define PSA_ALG_IS_BLAKE2_HASH(alg) /* specification-defined value */
#define PSA_ALG_IS_BLAKE2_MAC(alg) /* specification-defined value */
#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */
#define PSA_ALG_IS_CIPHER(alg) /* specification-defined value */
#define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */
Expand Down Expand Up @@ -337,6 +344,7 @@ typedef struct psa_custom_key_parameters_t {
#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)
#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406)
#define PSA_KEY_TYPE_ASCON ((psa_key_type_t)0x2008)
#define PSA_KEY_TYPE_BLAKE2 ((psa_key_type_t)0x1103)
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)
#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)
#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)
Expand Down
27 changes: 27 additions & 0 deletions doc/crypto/api/keys/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -989,6 +989,33 @@ Symmetric cryptographic keys

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
Copy link
Contributor

@gilles-peskine-arm gilles-peskine-arm Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@athoelke athoelke Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@athoelke athoelke Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kept a single key type in the updated PR

:definition: ((psa_key_type_t)0x1103)

.. summary::
Key for a BLAKE2 MAC algorithm.

.. versionadded:: 1.5

The bit size of a BLAKE2 key must be a non-zero multiple of 8, that is, a whole number of bytes.
Keys for BLAKE2s and BLAKE2sp cannot be greater than 256 bits, and keys for BLAKE2b and BLAKE2bp cannot be greater than 512 bits.

See `PSA_ALG_BLAKE2_MAC` for details of the BLAKE2 algorithms.

.. subsection:: Compatible algorithms

.. hlist::

* `PSA_ALG_BLAKE2_MAC`

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

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.

.. _structured-keys:

Structured key types
Expand Down
98 changes: 98 additions & 0 deletions doc/crypto/api/ops/hash.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,104 @@ Hash algorithms

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

.. macro:: PSA_ALG_BLAKE2S_HASH256
Copy link
Contributor

@gilles-peskine-arm gilles-peskine-arm Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@athoelke athoelke Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@gilles-peskine-arm gilles-peskine-arm Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@athoelke athoelke Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@athoelke athoelke Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

:definition: ((psa_algorithm_t)0x0200001C)

.. summary::
The BLAKE2s cryptographic hash with 256 bits of output (BLAKE2s-256).

.. versionadded:: 1.5

The BLAKE2s-256 hash is BLAKE2s with a zero-length key, and a 256-bit (32-byte) output.
BLAKE2s is defined in :rfc-title:`7693`.

.. note::
To use BLAKE2s as a MAC, see `PSA_ALG_BLAKE2_MAC`.

Where a protocol requires the use of HMAC or HKDF-HMAC, BLAKE2s-256 can be used with HMAC.
See `PSA_ALG_HMAC`.

.. note::
BLAKE2s-256 is not specified with `PSA_ALG_RSA_PKCS1V15_SIGN`, due to the lack of a standard OID.

It is recommended that this compound algorithm is not supported with `PSA_ALG_BLAKE2S_HASH256`.

.. macro:: PSA_ALG_BLAKE2SP_HASH256
:definition: ((psa_algorithm_t)0x0200001D)

.. summary::
The BLAKE2sp cryptographic hash with 256 bits of output (BLAKE2sp-256).

.. versionadded:: 1.5

The BLAKE2sp-256 hash is the parallel version of BLAKE2s with a zero-length key, and a 256-bit (32-byte) output.
BLAKE2sp is defined in :cite-title:`BLAKE2`.

.. note::
To use BLAKE2sp as a MAC, see `PSA_ALG_BLAKE2_MAC`.

.. note::
BLAKE2sp-256 is not specified with `PSA_ALG_RSA_PKCS1V15_SIGN`, due to the lack of a standard OID.

It is recommended that this compound algorithm is not supported with `PSA_ALG_BLAKE2SP_HASH256`.

.. macro:: PSA_ALG_BLAKE2B_HASH512
:definition: ((psa_algorithm_t)0x0200001E)

.. summary::
The BLAKE2b cryptographic hash with 512 bits of output (BLAKE2b-512).

.. versionadded:: 1.5

The BLAKE2b-512 hash is BLAKE2b with a zero-length key, and a 512-bit (64-byte) output.
BLAKE2b is defined in :rfc:`7693`.

.. note::
To use BLAKE2b as a MAC, see `PSA_ALG_BLAKE2_MAC`.

Where a protocol requires the use of HMAC or HKDF-HMAC, BLAKE2b-512 can be used with HMAC.
See `PSA_ALG_HMAC`.

.. note::
BLAKE2b-512 is not specified with `PSA_ALG_RSA_PKCS1V15_SIGN`, due to the lack of a standard OID.

It is recommended that this compound algorithm is not supported with `PSA_ALG_BLAKE2B_HASH512`.

.. macro:: PSA_ALG_BLAKE2BP_HASH512
:definition: ((psa_algorithm_t)0x0200001F)

.. summary::
The BLAKE2bp cryptographic hash with 512 bits of output (BLAKE2bp-512).

.. versionadded:: 1.5

The BLAKE2bp-512 hash is the parallel version of BLAKE2b with a zero-length key, and a 512-bit (64-byte) output.
BLAKE2bp is defined in :cite-title:`BLAKE2`.

.. note::
To use BLAKE2bp as a MAC, see `PSA_ALG_BLAKE2_MAC`.

.. note::
BLAKE2bp-512 is not specified with `PSA_ALG_RSA_PKCS1V15_SIGN`, due to the lack of a standard OID.

It is recommended that this compound algorithm is not supported with `PSA_ALG_BLAKE2BP_HASH512`.

.. macro:: PSA_ALG_IS_BLAKE2_HASH
:definition: /* specification-defined value */

.. summary::
Whether the specified algorithm is a BLAKE2 hash algorithm.

.. param:: alg
An algorithm identifier: a value of type `psa_algorithm_t`.

.. return::
``1`` if ``alg`` is a BLAKE2 hash algorithm, ``0`` otherwise.
This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

BLAKE2 is a family of hash and MAC algorithms.


Single-part hashing functions
-----------------------------

Expand Down
60 changes: 60 additions & 0 deletions doc/crypto/api/ops/mac.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,8 @@ MAC algorithms
`PSA_ALG_SHA3_384`, 104, 48
`PSA_ALG_SHA3_512`, 72, 64
`PSA_ALG_SM3`, 64, 32
`PSA_ALG_BLAKE2S_HASH256`, 64, 32
`PSA_ALG_BLAKE2B_HASH512`, 128, 64

.. admonition:: Implementation note

Expand Down Expand Up @@ -141,6 +143,49 @@ MAC algorithms
| `PSA_KEY_TYPE_CAMELLIA`
| `PSA_KEY_TYPE_SM4`

.. macro:: PSA_ALG_BLAKE2_MAC
:definition: /* specification-defined value */

.. summary::
Macro to build an BLAKE2 message-authentication-code algorithm from a BLAKE2 hash algorithm.

.. versionadded:: 1.5

.. param:: hash_alg
A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_BLAKE2_HASH(hash_alg)` is true.

.. return::
The corresponding BLAKE2 MAC algorithm.

Unspecified if ``hash_alg`` is not a supported BLAKE2 hash algorithm.

For example, :code:`PSA_ALG_BLAKE2_MAC(PSA_ALG_BLAKE2S_HASH256)` is BLAKE2s-MAC.

BLAKE2 MAC is a BLAKE2 keyed-hash with a non-zero-length key.
This macro is used to construct the BLAKE2 MAC for BLAKE2s, BLAKE2sp, BLAKE2b, and BLAKE2bp, by passing the appropriate BLAKE2 hash algorithm identifier as ``hash_alg``.

BLAKE2s and BLAKE2b are defined in :rfc-title:`7693`. BLAKE2sp and BLAKE2bp are defined in :cite-title:`BLAKE2`.

The BLAKE2 MAC algorithms must be used with a `PSA_KEY_TYPE_BLAKE2` key:

* For BLAKE2s and BLAKE2sp, the key must not be more than 256 bits (32 bytes) in length.
* For BLAKE2b and BLAKE2bp, the key must not be more than 512 bits (64 bytes) in length.

The default tag length for BLAKE2 MACs is the output length of the underlying BLAKE2 hash:

* For BLAKE2s and BLAKE2sp, the default and maximum tag length is 32 bytes.
* For BLAKE2b and BLAKE2bp, the default and maximum tag length is 64 bytes.

BLAKE2 permits any non-zero tag length from one to the maximum tag size.
To select a non-default tag length ``tag_len``, use :code:`PSA_ALG_TRUNCATED_MAC(PSA_ALG_BLAKE2_MAC(blake2_hash), tag_len)` as the algorithm.

.. note::
To use BLAKE2 as a cryptographic hash, see `PSA_ALG_BLAKE2S_HASH256`, `PSA_ALG_BLAKE2SP_HASH256`, `PSA_ALG_BLAKE2B_HASH512`, and `PSA_ALG_BLAKE2BP_HASH512`.

.. subsection:: Compatible key types

| `PSA_KEY_TYPE_BLAKE2`

.. macro:: PSA_ALG_TRUNCATED_MAC
:definition: /* specification-defined value */

Expand Down Expand Up @@ -670,6 +715,21 @@ Support macros

HMAC is a family of MAC algorithms that are based on a hash function.

.. macro:: PSA_ALG_IS_BLAKE2_MAC
:definition: /* specification-defined value */

.. summary::
Whether the specified algorithm is a BLAKE2 MAC algorithm.

.. param:: alg
An algorithm identifier: a value of type `psa_algorithm_t`.

.. return::
``1`` if ``alg`` is a BLAKE2 MAC algorithm, ``0`` otherwise.
This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

BLAKE2 is a family of hash and MAC algorithms.

.. macro:: PSA_ALG_IS_BLOCK_CIPHER_MAC
:definition: /* specification-defined value */

Expand Down
8 changes: 8 additions & 0 deletions doc/crypto/appendix/encodings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,10 @@ The defined values for HASH-TYPE are shown in :numref:`table-hash-type`.
SHAKE256/192, ``0x17``, `PSA_ALG_SHAKE256_192`, ``0x02000017``
SHAKE256/256, ``0x18``, `PSA_ALG_SHAKE256_256`, ``0x02000018``
Ascon-Hash256, ``0x19``, `PSA_ALG_ASCON_HASH256`, ``0x02000019``
BLAKE2s-256, ``0x1C``, `PSA_ALG_BLAKE2S_HASH256`, ``0x0200001C``
BLAKE2sp-256, ``0x1D``, `PSA_ALG_BLAKE2SP_HASH256`, ``0x0200001D``
BLAKE2b-512, ``0x1E``, `PSA_ALG_BLAKE2B_HASH512`, ``0x0200001E``
BLAKE2bp-512, ``0x1F``, `PSA_ALG_BLAKE2BP_HASH512`, ``0x0200001F``
*wildcard* :sup:`a`, ``0xFF``, `PSA_ALG_ANY_HASH`, ``0x020000FF``

a. The wildcard hash `PSA_ALG_ANY_HASH` can be used to parameterize a signature algorithm which defines a key usage policy, permitting any hash algorithm to be specified in a signature operation using the key.
Expand Down Expand Up @@ -204,13 +208,16 @@ H = HASH-TYPE (see :numref:`table-hash-type`) for hash-based MAC algorithms, oth
HMAC, 0, ``0x00``, :code:`PSA_ALG_HMAC(hash_alg)`, ``0x038000hh`` :sup:`a b`
CBC-MAC :sup:`c`, 1, ``0x01``, `PSA_ALG_CBC_MAC`, ``0x03c00100`` :sup:`a`
CMAC :sup:`c`, 1, ``0x02``, `PSA_ALG_CMAC`, ``0x03c00200`` :sup:`a`
BLAKE2 MAC, 0, ``0x03``, :code:`PSA_ALG_BLAKE2_MAC(blake2_hash)`, ``0x038003hh`` :sup:`a d`

a. This is the default algorithm identifier, specifying a standard length tag. `PSA_ALG_TRUNCATED_MAC()` generates identifiers with non-default LEN values. `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` generates permitted-algorithm policies with W = 1.

b. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash_alg``, used to construct the MAC algorithm.

c. This is a MAC constructed using an underlying block cipher. The block cipher is determined by the key type that is provided to the MAC operation.

d. ``hh`` is the HASH-TYPE for a BLAKE2 hash algorithm, ``blake2_hash``, used to construct the MAC algorithm.

.. _cipher-encoding:

Cipher algorithm encoding
Expand Down Expand Up @@ -613,6 +620,7 @@ The defined values for RAW-TYPE, SUB-TYPE, and P are shown in :numref:`table-raw
Raw key type, RAW-TYPE, SUB-TYPE, P, Key type, Key type value
Raw data, 0, 0, 1, `PSA_KEY_TYPE_RAW_DATA`, ``0x1001``
HMAC, 1, 0, 0, `PSA_KEY_TYPE_HMAC`, ``0x1100``
BLAKE2, 1, 1, 1, `PSA_KEY_TYPE_BLAKE2`, ``0x1103``
Derivation secret, 2, 0, 0, `PSA_KEY_TYPE_DERIVE`, ``0x1200``
Password, 2, 1, 1, `PSA_KEY_TYPE_PASSWORD`, ``0x1203``
Password hash, 2, 2, 1, `PSA_KEY_TYPE_PASSWORD_HASH`, ``0x1205``
Expand Down
6 changes: 6 additions & 0 deletions doc/crypto/appendix/history.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ Changes between *1.4.1* and *1.5.0*
Changes to the API
~~~~~~~~~~~~~~~~~~

* Added support for BLAKE2:

- BLAKE2s and BLAKE2sp cryptographic hashes, `PSA_ALG_BLAKE2S_HASH256` and `PSA_ALG_BLAKE2SP_HASH256`.
- BLAKE2b and BLAKE2bp cryptographic hashes, `PSA_ALG_BLAKE2B_HASH512` and `PSA_ALG_BLAKE2BP_HASH512`.
- A BLAKE2 MAC based on a BLAKE2 hash, `PSA_ALG_BLAKE2_MAC()`.

Relaxations
~~~~~~~~~~~

Expand Down
9 changes: 9 additions & 0 deletions doc/crypto/appendix/specdef_values.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ Algorithm macros
#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
( PSA_ALG_TRUNCATED_MAC(mac_alg, min_mac_length) | 0x00008000 )

#define PSA_ALG_BLAKE2_MAC(hash_alg) \
((psa_algorithm_t) (0x03800300 | ((hash_alg) & 0x000000ff)))

#define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \
((psa_algorithm_t) (0x06000700 | ((hash_alg) & 0x000000ff)))

Expand Down Expand Up @@ -81,6 +84,12 @@ Algorithm macros
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
(((alg) & 0x7f000000) == 0x07000000)

#define PSA_ALG_IS_BLAKE2_HASH(alg) \
(((alg) & 0x7ffffffc) == 0x0200001c)

#define PSA_ALG_IS_BLAKE2_MAC(alg) \
(((alg) & 0x7fc0ff00) == 0x03800300)

#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) \
(((alg) & 0x7fc00000) == 0x03c00000)

Expand Down