diff --git a/doc/crypto/about/references b/doc/crypto/about/references index 534ec909..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 @@ -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 diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index f52c2b87..abe156f8 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -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) @@ -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 */ @@ -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) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index fb6ecdfb..6eb52dee 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -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 + :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 diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index 32948603..744ed08b 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -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 + :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 ----------------------------- diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index fc736e5f..1a4caa20 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,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 */ @@ -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 */ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 4fa12dbd..bdcece13 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -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. @@ -204,6 +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` + 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. @@ -211,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 @@ -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`` diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 8183e3a0..6a6bae63 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -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 ~~~~~~~~~~~ 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)