From f401135910760111d47ae194adadd04154061dee Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 13 Feb 2026 16:37:27 +0000 Subject: [PATCH 1/3] Add support for BLAKE2 algorithms --- doc/crypto/about/references | 6 ++++ doc/crypto/api.db/psa/crypto.h | 5 +++ doc/crypto/api/keys/types.rst | 31 +++++++++++++++++ doc/crypto/api/ops/hash.rst | 45 +++++++++++++++++++++++++ doc/crypto/api/ops/mac.rst | 56 +++++++++++++++++++++++++++++++ doc/crypto/appendix/encodings.rst | 5 +++ doc/crypto/appendix/history.rst | 5 +++ 7 files changed, 153 insertions(+) diff --git a/doc/crypto/about/references b/doc/crypto/about/references index 534ec909..7ea16616 100644 --- a/doc/crypto/about/references +++ b/doc/crypto/about/references @@ -539,3 +539,9 @@ :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: IETF + :publication: November 2015 + :url: tools.ietf.org/html/rfc7693.html diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index f52c2b87..21b9d8ac 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -67,6 +67,10 @@ 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_BLAKE2B_HASH512 ((psa_algorithm_t)0x0200001B) +#define PSA_ALG_BLAKE2B_MAC ((psa_algorithm_t)0x03800400) +#define PSA_ALG_BLAKE2S_HASH256 ((psa_algorithm_t)0x0200001A) +#define PSA_ALG_BLAKE2S_MAC ((psa_algorithm_t)0x03800300) #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) @@ -337,6 +341,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)0x200B) #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) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index fb6ecdfb..b05ffed5 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -989,6 +989,37 @@ 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 + :definition: ((psa_key_type_t)0x200B) + + .. summary:: + Key for the BLAKE2s and BLAKE2b MAC algorithms. + + .. 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 cannot be greater than 256 bits, and keys for BLAKE2b cannot be greater than 512 bits. + + .. note:: + When BLAKE2s or BLAKE2b are used as general MAC algorithms, it is recommended to have a key size of at least 128 bits. + + See `PSA_ALG_BLAKE2S_MAC` and `PSA_ALG_BLAKE2B_MAC` for details of the BLAKE2 algorithms. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_BLAKE2S_MAC` + * `PSA_ALG_BLAKE2B_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 diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index 32948603..9254706b 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -300,6 +300,51 @@ Hash algorithms It is recommended that these compound algorithms are not supported with `PSA_ALG_ASCON_HASH256`. +.. macro:: PSA_ALG_BLAKE2S_HASH256 + :definition: ((psa_algorithm_t)0x0200001A) + + .. 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_BLAKE2S_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_BLAKE2B_HASH512 + :definition: ((psa_algorithm_t)0x0200001B) + + .. 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_BLAKE2B_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`. + + Single-part hashing functions ----------------------------- diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index fc736e5f..ea7dbc75 100644 --- a/doc/crypto/api/ops/mac.rst +++ b/doc/crypto/api/ops/mac.rst @@ -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 @@ -141,6 +143,60 @@ MAC algorithms | `PSA_KEY_TYPE_CAMELLIA` | `PSA_KEY_TYPE_SM4` +.. macro:: PSA_ALG_BLAKE2S_MAC + :definition: ((psa_algorithm_t)0x03800300) + + .. summary:: + The BLAKE2s message-authentication-code algorithm (BLAKE2s-MAC). + + .. versionadded:: 1.5 + + BLAKE2s-MAC is the BLAKE2s keyed-hash with a non-zero-length key. + BLAKE2s is defined in :rfc-title:`7693`. + + The BLAKE2s-MAC algorithm must be used with a `PSA_KEY_TYPE_BLAKE2` key, that is no more than 256 bits in length. + + The default tag length for `PSA_ALG_BLAKE2S_MAC` is 32 bytes, which is the maximum output length of BLAKE2s. + BLAKE2s permits any output length from 1 to 32 bytes. + To select a non-default tag length ``tag_len``, use :code:`PSA_ALG_TRUNCATED_MAC(PSA_ALG_BLAKE2S_MAC, tag_len)` as the algorithm. + + .. note:: + When BLAKE2s is used as general MAC algorithm, it is recommended to use an output tag of at least 64 bits (8 bytes). + + .. note:: + To use BLAKE2s as a cryptographic hash, see `PSA_ALG_BLAKE2S_HASH256`. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_BLAKE2` (with ``key_bits <= 256``) + +.. macro:: PSA_ALG_BLAKE2B_MAC + :definition: ((psa_algorithm_t)0x03800400) + + .. summary:: + The BLAKE2b message-authentication-code algorithm (BLAKE2b-MAC). + + .. versionadded:: 1.5 + + BLAKE2b-MAC is the BLAKE2b keyed-hash with a non-zero-length key. + BLAKE2b is defined in :rfc:`7693`. + + The BLAKE2b-MAC algorithm must be used with a `PSA_KEY_TYPE_BLAKE2` key. + + The default tag length for `PSA_ALG_BLAKE2B_MAC` is 64 bytes, which is the maximum output length of BLAKE2b. + BLAKE2b permits any output length from 1 to 64 bytes. + 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). + + .. note:: + To use BLAKE2b as a cryptographic hash, see `PSA_ALG_BLAKE2B_HASH512`. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_BLAKE2` + .. macro:: PSA_ALG_TRUNCATED_MAC :definition: /* specification-defined value */ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 4fa12dbd..0d867fc3 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -140,6 +140,8 @@ 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, ``0x1A``, `PSA_ALG_BLAKE2S_HASH256`, ``0x0200001A`` + BLAKE2b-512, ``0x1B``, `PSA_ALG_BLAKE2B_HASH512`, ``0x0200001B`` *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. @@ -204,6 +206,8 @@ 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` + BLAKE2s-MAC, 0, ``0x03``, `PSA_ALG_BLAKE2S_MAC`, ``0x03800300`` :sup:`a` + BLAKE2b-MAC, 0, ``0x04``, `PSA_ALG_BLAKE2B_MAC`, ``0x03800400`` :sup:`a` 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. @@ -645,6 +649,7 @@ The defined values for BLK, SYM-TYPE and P are shown in :numref:`table-symmetric ChaCha20, 0, 2, 0, `PSA_KEY_TYPE_CHACHA20`, ``0x2004`` XChaCha20, 0, 3, 1, `PSA_KEY_TYPE_XCHACHA20`, ``0x2007`` Ascon, 0, 4, 0, `PSA_KEY_TYPE_ASCON`, ``0x2008`` + BLAKE2, 0, 5, 1, `PSA_KEY_TYPE_BLAKE2`, ``0x200B`` DES, 3, 0, 1, `PSA_KEY_TYPE_DES`, ``0x2301`` AES, 4, 0, 0, `PSA_KEY_TYPE_AES`, ``0x2400`` CAMELLIA, 4, 1, 1, `PSA_KEY_TYPE_CAMELLIA`, ``0x2403`` diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 8183e3a0..bd81b3ca 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -17,6 +17,11 @@ Changes between *1.4.1* and *1.5.0* Changes to the API ~~~~~~~~~~~~~~~~~~ +* Added support for BLAKE2: + + - BLAKE2s cryptographic hash and MAC, `PSA_ALG_BLAKE2S_HASH256` and `PSA_ALG_BLAKE2S_MAC`. + - BLAKE2b cryptographic hash and MAC, `PSA_ALG_BLAKE2B_HASH512` and `PSA_ALG_BLAKE2B_MAC`. + Relaxations ~~~~~~~~~~~ From 1e1f368adb3e73adc19c07641755228285286b59 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 24 Feb 2026 18:46:38 +0000 Subject: [PATCH 2/3] Rework the BLAKE2 hash and MAC algorithm identifiers --- doc/crypto/about/references | 14 ++++-- doc/crypto/api.db/psa/crypto.h | 13 +++-- doc/crypto/api/keys/types.rst | 14 ++---- doc/crypto/api/ops/hash.rst | 61 +++++++++++++++++++++-- doc/crypto/api/ops/mac.rst | 68 ++++++++++++++------------ doc/crypto/appendix/encodings.rst | 13 +++-- doc/crypto/appendix/history.rst | 5 +- doc/crypto/appendix/specdef_values.rst | 9 ++++ 8 files changed, 136 insertions(+), 61 deletions(-) diff --git a/doc/crypto/about/references b/doc/crypto/about/references index 7ea16616..64603d86 100644 --- a/doc/crypto/about/references +++ b/doc/crypto/about/references @@ -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 @@ -542,6 +542,12 @@ .. reference:: RFC7693 :title: The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC) - :author: IETF + :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 diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 21b9d8ac..abe156f8 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -67,10 +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_BLAKE2B_HASH512 ((psa_algorithm_t)0x0200001B) -#define PSA_ALG_BLAKE2B_MAC ((psa_algorithm_t)0x03800400) -#define PSA_ALG_BLAKE2S_HASH256 ((psa_algorithm_t)0x0200001A) -#define PSA_ALG_BLAKE2S_MAC ((psa_algorithm_t)0x03800300) +#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) @@ -110,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 */ @@ -341,7 +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)0x200B) +#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) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index b05ffed5..6eb52dee 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -990,27 +990,23 @@ 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 - :definition: ((psa_key_type_t)0x200B) + :definition: ((psa_key_type_t)0x1103) .. summary:: - Key for the BLAKE2s and BLAKE2b MAC algorithms. + 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 cannot be greater than 256 bits, and keys for BLAKE2b cannot be greater than 512 bits. + Keys for BLAKE2s and BLAKE2sp cannot be greater than 256 bits, and keys for BLAKE2b and BLAKE2bp cannot be greater than 512 bits. - .. note:: - When BLAKE2s or BLAKE2b are used as general MAC algorithms, it is recommended to have a key size of at least 128 bits. - - See `PSA_ALG_BLAKE2S_MAC` and `PSA_ALG_BLAKE2B_MAC` for details of the BLAKE2 algorithms. + See `PSA_ALG_BLAKE2_MAC` for details of the BLAKE2 algorithms. .. subsection:: Compatible algorithms .. hlist:: - * `PSA_ALG_BLAKE2S_MAC` - * `PSA_ALG_BLAKE2B_MAC` + * `PSA_ALG_BLAKE2_MAC` .. subsection:: Key format diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index 9254706b..98f547ea 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -301,7 +301,7 @@ Hash algorithms It is recommended that these compound algorithms are not supported with `PSA_ALG_ASCON_HASH256`. .. macro:: PSA_ALG_BLAKE2S_HASH256 - :definition: ((psa_algorithm_t)0x0200001A) + :definition: ((psa_algorithm_t)0x0200001C) .. summary:: The BLAKE2s cryptographic hash with 256 bits of output (BLAKE2s-256). @@ -312,7 +312,7 @@ Hash algorithms BLAKE2s is defined in :rfc-title:`7693`. .. note:: - To use BLAKE2s as a MAC, see `PSA_ALG_BLAKE2S_MAC`. + 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`. @@ -322,8 +322,27 @@ Hash algorithms 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)0x0200001B) + :definition: ((psa_algorithm_t)0x0200001E) .. summary:: The BLAKE2b cryptographic hash with 512 bits of output (BLAKE2b-512). @@ -334,7 +353,7 @@ Hash algorithms BLAKE2b is defined in :rfc:`7693`. .. note:: - To use BLAKE2b as a MAC, see `PSA_ALG_BLAKE2B_MAC`. + 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`. @@ -344,6 +363,40 @@ Hash algorithms 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 ----------------------------- diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index ea7dbc75..1ddbdba7 100644 --- a/doc/crypto/api/ops/mac.rst +++ b/doc/crypto/api/ops/mac.rst @@ -143,55 +143,44 @@ MAC algorithms | `PSA_KEY_TYPE_CAMELLIA` | `PSA_KEY_TYPE_SM4` -.. macro:: PSA_ALG_BLAKE2S_MAC - :definition: ((psa_algorithm_t)0x03800300) +.. macro:: PSA_ALG_BLAKE2_MAC + :definition: /* specification-defined value */ .. summary:: - The BLAKE2s message-authentication-code algorithm (BLAKE2s-MAC). + Macro to build an BLAKE2 message-authentication-code algorithm from a BLAKE2 hash algorithm. .. versionadded:: 1.5 - BLAKE2s-MAC is the BLAKE2s keyed-hash with a non-zero-length key. - BLAKE2s is defined in :rfc-title:`7693`. - - The BLAKE2s-MAC algorithm must be used with a `PSA_KEY_TYPE_BLAKE2` key, that is no more than 256 bits in length. - - The default tag length for `PSA_ALG_BLAKE2S_MAC` is 32 bytes, which is the maximum output length of BLAKE2s. - BLAKE2s permits any output length from 1 to 32 bytes. - To select a non-default tag length ``tag_len``, use :code:`PSA_ALG_TRUNCATED_MAC(PSA_ALG_BLAKE2S_MAC, tag_len)` as the algorithm. - - .. note:: - When BLAKE2s is used as general MAC algorithm, it is recommended to use an output tag of at least 64 bits (8 bytes). + .. 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. - .. note:: - To use BLAKE2s as a cryptographic hash, see `PSA_ALG_BLAKE2S_HASH256`. + .. return:: + The corresponding BLAKE2 MAC algorithm. - .. subsection:: Compatible key types + Unspecified if ``hash_alg`` is not a supported BLAKE2 hash algorithm. - | `PSA_KEY_TYPE_BLAKE2` (with ``key_bits <= 256``) + For example, :code:`PSA_ALG_BLAKE2_MAC(PSA_ALG_BLAKE2S_HASH256)` is BLAKE2s-MAC. -.. macro:: PSA_ALG_BLAKE2B_MAC - :definition: ((psa_algorithm_t)0x03800400) + 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``. - .. summary:: - The BLAKE2b message-authentication-code algorithm (BLAKE2b-MAC). + BLAKE2s and BLAKE2b are defined in :rfc-title:`7693`. BLAKE2sp and BLAKE2bp are defined in :cite-title:`BLAKE2`. - .. versionadded:: 1.5 + The BLAKE2 MAC algorithms must be used with a `PSA_KEY_TYPE_BLAKE2` key: - BLAKE2b-MAC is the BLAKE2b keyed-hash with a non-zero-length key. - BLAKE2b is defined in :rfc:`7693`. + * 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 BLAKE2b-MAC algorithm must be used with a `PSA_KEY_TYPE_BLAKE2` key. + The default tag length for BLAKE2 MACs is the output length of the underlying BLAKE2 hash: - The default tag length for `PSA_ALG_BLAKE2B_MAC` is 64 bytes, which is the maximum output length of BLAKE2b. - BLAKE2b permits any output length from 1 to 64 bytes. - To select a non-default tag length ``tag_len``, use :code:`PSA_ALG_TRUNCATED_MAC(PSA_ALG_BLAKE2B_MAC, tag_len)` as the algorithm. + * 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. - .. note:: - When BLAKE2b is used as general MAC algorithm, it is recommended to use an output tag of at least 64 bits (8 bytes). + BLAKE2 permits any non-zero tag length from 1 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 BLAKE2b as a cryptographic hash, see `PSA_ALG_BLAKE2B_HASH512`. + 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 @@ -726,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 */ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 0d867fc3..bdcece13 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -140,8 +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, ``0x1A``, `PSA_ALG_BLAKE2S_HASH256`, ``0x0200001A`` - BLAKE2b-512, ``0x1B``, `PSA_ALG_BLAKE2B_HASH512`, ``0x0200001B`` + 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. @@ -206,8 +208,7 @@ 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` - BLAKE2s-MAC, 0, ``0x03``, `PSA_ALG_BLAKE2S_MAC`, ``0x03800300`` :sup:`a` - BLAKE2b-MAC, 0, ``0x04``, `PSA_ALG_BLAKE2B_MAC`, ``0x03800400`` :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. @@ -215,6 +216,8 @@ b. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash_alg``, used to constr 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 @@ -617,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`` @@ -649,7 +653,6 @@ The defined values for BLK, SYM-TYPE and P are shown in :numref:`table-symmetric ChaCha20, 0, 2, 0, `PSA_KEY_TYPE_CHACHA20`, ``0x2004`` XChaCha20, 0, 3, 1, `PSA_KEY_TYPE_XCHACHA20`, ``0x2007`` Ascon, 0, 4, 0, `PSA_KEY_TYPE_ASCON`, ``0x2008`` - BLAKE2, 0, 5, 1, `PSA_KEY_TYPE_BLAKE2`, ``0x200B`` DES, 3, 0, 1, `PSA_KEY_TYPE_DES`, ``0x2301`` AES, 4, 0, 0, `PSA_KEY_TYPE_AES`, ``0x2400`` CAMELLIA, 4, 1, 1, `PSA_KEY_TYPE_CAMELLIA`, ``0x2403`` diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index bd81b3ca..6a6bae63 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -19,8 +19,9 @@ Changes to the API * Added support for BLAKE2: - - BLAKE2s cryptographic hash and MAC, `PSA_ALG_BLAKE2S_HASH256` and `PSA_ALG_BLAKE2S_MAC`. - - BLAKE2b cryptographic hash and MAC, `PSA_ALG_BLAKE2B_HASH512` and `PSA_ALG_BLAKE2B_MAC`. + - 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 ~~~~~~~~~~~ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index bbcfcd1f..b3aadaff 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -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))) @@ -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) From f76e95a16392f67412d0665e122cdcb613e32d43 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 24 Feb 2026 18:50:17 +0000 Subject: [PATCH 3/3] Lost typographic fixes --- doc/crypto/api/ops/hash.rst | 8 ++++---- doc/crypto/api/ops/mac.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index 98f547ea..744ed08b 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -308,7 +308,7 @@ Hash algorithms .. versionadded:: 1.5 - 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. BLAKE2s is defined in :rfc-title:`7693`. .. note:: @@ -330,7 +330,7 @@ Hash algorithms .. 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. + 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:: @@ -349,7 +349,7 @@ Hash algorithms .. versionadded:: 1.5 - The BLAKE2b-512 hash is BLAKE2b with a zero-length key, and a 512 bit (64 byte) output. + 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:: @@ -371,7 +371,7 @@ Hash algorithms .. 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. + 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:: diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index 1ddbdba7..1a4caa20 100644 --- a/doc/crypto/api/ops/mac.rst +++ b/doc/crypto/api/ops/mac.rst @@ -176,7 +176,7 @@ MAC algorithms * 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 1 to the maximum tag size. + 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::