diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index fdbbe250..27279665 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -250,6 +250,31 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. +.. macro:: PSA_KEY_USAGE_ENCAPSULATE + :definition: ((psa_key_usage_t)0x00010000) + + .. summary:: + Permission to encapsulate new keys. + + This flag is required to encapsulate new keys to send to a counter party. + + This flag must be present on public keys used with the following APIs: + + * `psa_encapsulate()` + +.. macro:: PSA_KEY_USAGE_DECAPSULATE + :definition: ((psa_key_usage_t)0x00020000) + + .. summary:: + Permission to decapsulate an encapsulated key. + + This flag is required to decapsulate a key buffer obtained from a counter party. + + This flag must be present on private keys used with the following APIs: + + * `psa_decapsulate()` + + .. function:: psa_set_key_usage_flags .. summary:: diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 9eef6fbb..d0d29504 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -129,7 +129,7 @@ Symmetric keys It is :scterm:`implementation defined` whether an HMAC key that is longer than the hash block size is supported. If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key. - + .. note:: :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes. @@ -408,6 +408,7 @@ Symmetric keys | `PSA_ALG_STREAM_CIPHER` | `PSA_ALG_CHACHA20_POLY1305` + .. macro:: PSA_KEY_TYPE_XCHACHA20 :definition: ((psa_key_type_t)0x2007) @@ -425,7 +426,6 @@ Symmetric keys | `PSA_ALG_STREAM_CIPHER` | `PSA_ALG_XCHACHA20_POLY1305` - .. _asymmetric-keys: RSA keys @@ -502,7 +502,7 @@ Elliptic Curve keys .. summary:: Elliptic curve key pair: both the private and public key. - The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details. + The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:``q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details. .. param:: curve A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used. @@ -920,6 +920,143 @@ Diffie Hellman keys .. return:: psa_dh_family_t The Diffie-Hellman group family id, if ``type`` is a supported Diffie-Hellman key. Unspecified if ``type`` is not a supported Diffie-Hellman key. +Module Lattice keys +------------------- + +PSA supports Module Lattice Cryptography as defined in :cite:`FIPS203` and :cite:`FIPS204`. + +There are two related, but separate algorithms a key encapsulation method, ML-KEM and a signature method ML-DSA. + +.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR + :definition: ((psa_key_type_t)0xy001) + + .. summary:: + MLKEM key pair: contains both the decapsulation and encapsulation keys. + PSA Crypto treats decapsulation keys as private keys and encapsulation keys as public keys. + + The size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in FIPS 203. + + The parameter sets refer to the key strength, the actual size of the key + + .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :header-rows: 1 + + * - Size + - Parameter Set + - Encapsulation key + - Decapsulation key + - Ciphertext + + * - 512 + - ML-KEM-512 + - 800 + - 1632 + - 768 + + * - 768 + - ML-KEM-768 + - 1184 + - 2400 + - 1088 + + * - 1024 + - ML-KEM-1024 + - 1568 + - 3168 + - 1568 + + In all cases the shared secret produced is 32-bytes, 256-bits long. + The shared secret can be used directly or passed to a PRF to derive further keys. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLKEM` + +.. macro:: PSA_KEY_TYPE_ML_KEM _PUBLIC_KEY + :definition: ((psa_key_type_t)0x4001) + + .. summary:: + ML-KEM public key. + + The size of an ML-KEM key is the numeric part of the parameter set identifier. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLKEM` (encapsulation only) + | +.. macro:: PSA_KEY_TYPE_IS_MLKEM + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-KEM key. This includes both key pairs and public keys. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_MLDSA_KEY_PAIR + :definition: ((psa_key_type_t)0xy001) + + .. summary:: + An ML_DSA key pair: contains both the public and private keys. + + The size of an ML-DSA key is specified by the numeric part of the parameter set identifier defined in FIPS 203. + + The parameter sets refer to the dimensions of the matrix A, and do not directly define key size. + + .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :header-rows: 1 + + * - Size + - Parameter Set + - Private key + - Public key + - Signature + + * - 44 + - ML-DSA-44 + - 2560 + - 1312 + - 2420 + + * - 65 + - ML-DSA-65 + - 4032 + - 1952 + - 3309 + + * - 87 + - ML-DSA-87 + - 4896 + - 2592 + - 4627 + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLDSA_SIGN` + +.. macro:: PSA_KEY_TYPE_MLDSA_PUBLIC_KEY + :definition: ((psa_key_type_t)0xy001) + + .. summary:: + A ML-DSA public key. + + The size of an ML-DSA key is specified by the numeric part of the parameter set identifier defined in FIPS 203. + + The parameter sets refer to the key strength, the actual size of the key + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLDSA_SIGN` (verification only) + +.. macro:: PSA_KEY_TYPE_IS_MLDSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-SIG key. This includes both key pairs and public keys. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + Attribute accessors ------------------- diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 8e1c6989..b8ebdd31 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -23,6 +23,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope * :secref:`sign-algorithms` * :secref:`asymmetric-encryption-algorithms` * :secref:`key-agreement-algorithms` +* :secref:`encapsulation-algorithms` Algorithm encoding @@ -227,3 +228,4 @@ Algorithm categories * `PSA_ALG_TLS12_PRF()` * `PSA_ALG_TLS12_PSK_TO_MS()` * `PSA_ALG_PBKDF2_HMAC()` + * `PSA_ALG_MLDSA_SIGN` diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst new file mode 100644 index 00000000..869cc9d6 --- /dev/null +++ b/doc/crypto/api/ops/encap.rst @@ -0,0 +1,348 @@ +Key Encapsulation +================= + +Elliptic Curve Integrated Encryption Scheme +------------------------------------------- + +The Elliptic Curve Integrated Encryption Scheme was fist proposed by Shoup, then improved by Ballare and Rogaway. + +The original specification permitted a number of variants. This specification only defines the version specified in [SEC1], that is with the use of labels and with the label size defined in bytes. + +It is possible that some applications may need to use older versions to interoperate with legacy systems. +While the application can always implement this using the other algorithm functions provided, however, an implementation may choose to add these as a convenience in the implementation numbering space. + +.. macro:: PSA_ALG_ECIES_SEC1 + :definition: ((psa_algorithm_t)0x09yyyxxxx) + + .. summary:: + The Elliptic Curve Integrated Encryption Scheme. + + This algorithm can only be used when combined with a key derivation operation using `PSA_ALG_ENCAPSULATION()` in a call to `psa_encapsulate()` + + When used as a key's permitted-algorithm policy, the following uses are permitted: + + * In a call to `psa_encapsulate()` or `psa_decapsulate()`, with any combined key establishment and key derivation algorithm constructed with `PSA_ALG_ECIES`. + + This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. + + This uses Cofactor ECDH. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` + + where ``family`` is a Weierstrass or Montgomery Elliptic curve family. That is, one of the following values: + + * ``PSA_ECC_FAMILY_SECT_XX`` + * ``PSA_ECC_FAMILY_SECP_XX`` + * `PSA_ECC_FAMILY_FRP` + * `PSA_ECC_FAMILY_BRAINPOOL_P_R1` + * `PSA_ECC_FAMILY_MONTGOMERY` + +Module Lattice Encapsulation +---------------------------- + +PSA Crypto supports Module Lattice Encapsulation as defined in :city:`FIPS 203`. + +.. macro:: PSA_ALG_MLKEM + :definition: ((psa_algorithm_t)0x09yyyxxxx) + + .. summary:: + Module Lattice Encapsulation. + + ML-KEM as defined, does not permit a choice of PRF. Therefore this algorithm is a combined algotithm and can be used directly in a call to `psa_encapsulate()` There is no need to call `PSA_ALG_ENCAPSULATION` + + When used as a key's permitted-algorithm policy, the following uses are permitted: + + * In a call to `psa_encapsulate()` or `psa_decapsulate()`. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_MLKEM` + +Supporting Macros +----------------- + +.. macro:: PSA_ALG_ENCAPSULATION + :definition: /* specification-defined value */ + + .. summary:: + Macro to build a combined algorithm that chains a key encapsulation with a key derivation. + + .. param:: ka_alg + A encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(ka_alg)` is true. + .. param:: kdf_alg + A key derivation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_DERIVATION(kdf_alg)` is true. + + .. return:: + The corresponding encapsulation and derivation algorithm. + + Unspecified if ``ka_alg`` is not a supported key establishment algorithm or ``kdf_alg`` is not a supported key derivation algorithm. + + A combined encapsulation algorithm is used in a call to `psa_encapsulate()`. + + The component parts of a encapsulation algorithm can be extracted using `PSA_ALG_ENCAPSULATION_GET_BASE()` and `PSA_ALG_ENCAPSULATION_GET_KDF()`. + + .. subsection:: Compatible key types + + The resulting combined encapsulation algorithm is compatible with the same key types as the raw encapsulation algorithm used to construct it. + + + +.. _encapsulation-algorithms: + +Encapsulation Algorithms +------------------------ +.. function:: psa_encapsulate + + .. summary:: + Generate a new key pair and a use that to encapsulate a new symmetric key, emitting it both as a key object and an encapsulation to send to a counter party along with the public key from the ephemeral key pair. + + .. param:: const psa_key_id_t * counterparty_key + The identifier for the public key of the peer. You must have previously imported this key using `psa_import_key()`, and specified the key attributes for the public key type corresponding to the type required for the encapsulation, and the usage usage `PSA_KEY_USAGE_ENCAPSULATE`. + + .. param:: uint8_t * ephemeral_public_key + Buffer where the ephemeral public key key is to be written, ready to be sent to the counterparty. The content of the buffer will be in the same format as `psa_export_key()` for a key of the same type as ``counterparty_key``. + + .. param:: size_t ephemeral_public_key_size + Size of the ``ephemeral_public_key`` buffer in bytes. + This must be at least :code:`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(alg)`. + A buffer of at least :code:`PSA_EXPORT_PUBLIC_KEY_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + + .. param:: psa_algorithm_t alg + The ful encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true and :code:`PSA_ALG_IS_RAW_ENCAPSULATION(alg)` is false . + + .. param:: const psa_key_attributes_t * attributes + The attributes for the new symmetric key. + This function uses the attributes as follows: + + * The key type is required. It cannot be an asymmetric public key. + * The key size is required. It must be a valid size for the key type. + * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. + * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. + * The key lifetime and identifier are required for a persistent key. + + .. note:: + This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. + + .. param:: psa_key_id_t * output_key + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + + .. param:: uint8_t * encapsulation + Buffer where the encapsulated key is to be written, ready to be sent to the counterparty. + + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + + .. param:: size_t * encapsulation_length + On success, the number of bytes that make up the hash value. This is always :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + + .. return:: psa_status_t + + .. retval:: PSA_SUCCESS + Success. + The bytes of ``encapsulation`` contain the encapsulated key, the bytes of ``ephemeral_public_key`` contain the public key and ``output_key`` contains the identifier for the key to be used to encrypt the message. + + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: + + * ``alg`` is not a encapsulation algorithm. + + .. retval:: PSA_ERROR_BUFFER_TOO_SMALL + The size of the ``encapsulation`` or the ``ephemeral_public_key`` buffer is too small. + + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. + + + + + +.. function:: psa_decapsulate + + .. summary:: + Uses a private key to decapsulate an encapsulation received from a counter party. + + .. param:: const psa_key_id_t * peer_key + Public key of the peer. The peer key must be in the same format that `psa_import_key()` accepts for the public key type corresponding to the type of ``private_key``. That is, this function performs the equivalent of :code:`psa_import_key(..., peer_key, peer_key_length)`, with key attributes indicating the public key type corresponding to the type of ``private_key``. For example, for ECC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of `psa_export_public_key()`. + + .. param:: size_t peer_key_length + Size of the ``encapsulation`` buffer in bytes. + + .. param:: const psa_key_id_t * private_key + Identifier of the key belonging to the person receiving the encapsulated message. + It must be an asymmetric key pair. + The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` + + .. param:: conts uint8_t * encapsulation + Buffer containing the encapsulated key that was received from the counterparty. + + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + + .. param:: psa_algorithm_t alg + The encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + + .. param:: const psa_key_attributes_t * attributes + The attributes for the new key. + This function uses the attributes as follows: + + * The key type is required. It cannot be an asymmetric public key. + * The key size is required. It must be a valid size for the key type. + * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. + * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. + * The key lifetime and identifier are required for a persistent key. + + .. note:: + This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. + + .. param:: psa_key_id_t * output_key + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. + + +Support macros +-------------- + +.. macro:: PSA_ALG_ENCAPSULATION_GET_BASE + :definition: /* specification-defined value */ + + .. summary:: + Get the raw key encapsulation algorithm from a full encapsulation algorithm. + + .. param:: alg + A key encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + + .. return:: + The underlying raw key encapsulation algorithm if ``alg`` is a key encapsulation algorithm. + + Unspecified if ``alg`` is not a key encapsulation algorithm or if it is not supported by the implementation. + + See also `PSA_ALG_ENCAPSULATION()` and `PSA_ALG_ENCAPSULATION_GET_KDF()`. + +.. macro:: PSA_ALG_ENCAPSULATION_GET_KDF + :definition: /* specification-defined value */ + + .. summary:: + Get the key derivation algorithm used in a full encapsulation algorithm. + + .. param:: alg + A encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + + .. return:: + The underlying key derivation algorithm if ``alg`` is a encapsulation algorithm. + + Unspecified if ``alg`` is not a encapsulation algorithm or if it is not supported by the implementation. + + See also `PSA_ALG_ENCAPSULATION()` and `PSA_ALG_ENCAPSULATION_GET_BASE()`. + +.. macro:: PSA_ALG_IS_RAW_ENCAPSULATION + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a raw encapsulation algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a raw encapsulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + A raw encapsulation algorithm is one that does not specify a key derivation function. Usually, raw encapsulation algorithms are constructed directly with a ``PSA_ALG_xxx`` macro while non-raw encapsulation algorithms are constructed with `PSA_ALG_ENCAPSULATION()`. + + The raw encapsulation algorithm can be extracted from a full encapsulation algorithm identifier using `PSA_ALG_ENCAPSULATION_GET_BASE()`. + +.. macro:: PSA_ALG_IS_ENCAPSULATION + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a full encapsulation algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a full encapsulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + A full encapsulation algorithm is one that specifies a key derivation function as well as an encapsulation function. Usually, encapsulation algorithms are constructed with `PSA_ALG_ENCAPSULATION()` while non-raw encapsulation algorithms are constructed directly with a ``PSA_ALG_xxx`` macro. + + The raw encapsulation algorithm can be extracted from a full encapsulation algorithm identifier using `PSA_ALG_ENCAPSULATION_GET_BASE()`. + + +.. macro:: PSA_ALG_IS_ECIES + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an Elliptic Curve Integrated Encryption Scheme algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an Elliptic Curve Integrated Encryption Scheme algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported key agreement algorithm identifier. + + This includes the raw Elliptic Curve Integrated Encryption Scheme algorithm as well as Elliptic Curve Integrated Encryption Scheme followed by any supporter key derivation algorithm. + +.. macro:: PSA_ENCAPSULATION_OUTPUT_SIZE + :definition: /* implementation-defined value */ + + .. summary:: + Sufficient output buffer size for `psa_encapsulate()`. + + .. param:: key_type + A supported key type. + .. param:: key_bits + The size of the key in bits. + + .. return:: + A sufficient output buffer size for the specified key type and size. An implementation can return either ``0`` or a correct size for a key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. + + If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. + + See also `PSA_ENCAPSULATION_OUTPUT_MAX_SIZE`. + +.. macro:: PSA_ENCAPSULATION_OUTPUT_MAX_SIZE + :definition: /* implementation-defined value */ + + .. summary:: + Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. + + If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. + + See also `PSA_ENCAPSULATION_OUTPUT_SIZE()`. + + + + diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 9f2e7089..1bf9e6e6 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -79,13 +79,13 @@ Hash algorithms .. summary:: The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction using AES-128. - This is the cryptographic hash function based on the Merkle-DamgÃ¥rd construction over a Matyas-Meyer-Oseas one-way compression function and the AES-128 block cipher, with the parametrization defined in :cite-title:`ZIGBEE` §B.6. + This is the cryptographic hash function based on the Merkle-Damgård construction over a Matyas-Meyer-Oseas one-way compression function and the AES-128 block cipher, with the parametrization defined in :cite-title:`ZIGBEE` §B.6. This hash function can operate on input strings of up to :math:`2^{32} - 1` bits. .. note:: - The Zigbee keyed hash function from `[ZIGBEE]` §B.1.4 is :code:`PSA_ALG_HMAC(PSA_ALG_AES_MMO_ZIGBEE)`. + The Zigbee keyed hash function from `[ZIGBEE]` §B.1.4 is :code:`PSA_ALG_HMAC(PSA_ALG_AES_MMO_ZIGBEE)`. .. macro:: PSA_ALG_SHA_1 :definition: ((psa_algorithm_t)0x02000005) @@ -191,6 +191,19 @@ Hash algorithms .. note:: For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is recommended. SHA3-512 has the same output size, and a theoretically higher security strength. +.. macro:: PSA_ALG_SHAKE128_256 + :definition: ((psa_algorithm_t)0x02000015) + + .. summary:: + The first 256 bits (32 bytes) of the SHAKE128 output. + + This is the prehashing for ML-DSA (see `PSA_ALG_MLDSA_SIGN`). + + SHAKE128 is defined in :cite:`FIPS202`. + + .. note:: + For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is recommended. SHA3-256 has the same output size, and a theoretically higher security strength. + .. macro:: PSA_ALG_SM3 :definition: ((psa_algorithm_t)0x02000014) diff --git a/doc/crypto/api/ops/index.rst b/doc/crypto/api/ops/index.rst index 2b2c03e8..216e381e 100644 --- a/doc/crypto/api/ops/index.rst +++ b/doc/crypto/api/ops/index.rst @@ -18,4 +18,5 @@ Cryptographic operation reference sign pke ka + encap rng diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index d802a9ea..72738938 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.rst @@ -347,7 +347,40 @@ Asymmetric signature algorithms When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as :math:`\text{PH}(M)` in the algorithms defined in :RFC:`8032#5.2`. +.. macro:: PSA_ALG_MLDSA_SIGN + :definition: ((psa_algorithm_t) 0x06000916) + .. summary:: + The Module Lattice Signature scheme, with hashing. + + .. param:: hash_alg + A hash algorithm: A value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. This includes `PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + This algorithm can be used with both the message and hash signature functions. + + This signature scheme is defined by :cite:`FIPS204` as ML-DSA or HashML-DSA. + + When used with `psa_sign_hash()` or `psa_verify_hash()`, the provided ``hash`` parameter is used to select the OID and length prepended to the hash. + + .. subsection:: Usage + + This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches: + + * Call `psa_sign_message()` with the message. + + * Calculate the hash of the message with `psa_hash_compute()`, or with a multi-part hash operation, using the specified hash algorithm. Then sign the calculated hash with `psa_sign_hash()` When using the `psa_sign_hash()` function the caller should provide the raw hash, the function prepends the OID and length based on the ``hash`` parameter. + + Verifying a signature is similar, using `psa_verify_message()` or `psa_verify_hash()` instead of the signature function. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_MLDSA_KEY_PAIR` + | :code:`PSA_KEY_TYPE_MLDSA_PUBLIC_KEY` (signature verification only) + + .. admonition:: Implementation note + + The :cite:`FIPS204` standard specifies OIDs for SHA256, SHA512 and SHA128, but permits use of other hashes, provided they offer at least the same security strength as the signature function and have an agreed OID. + Asymmetric signature functions ------------------------------ diff --git a/doc/crypto/references b/doc/crypto/references index 3f5c5eda..fac9ebce 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -81,6 +81,18 @@ :publication: August 2015 :url: doi.org/10.6028/NIST.FIPS.202 +.. reference:: FIPS203 + :title: FIPS Publication 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.203 + +.. reference:: FIPS204 + :title: FIPS Publication 204: Module-Lattice-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.204 + .. reference:: FRP :title: Publication d'un paramétrage de courbe elliptique visant des applications de passeport électronique et de l'administration électronique française :author: Agence nationale de la sécurité des systèmes d'information @@ -261,6 +273,12 @@ :publication: August 2013 :url: tools.ietf.org/html/rfc6979.html +.. reference:: RFC7539 + :title: ChaCha20 and Poly1305 for IETF Protocols + :author: IETF + :publication: May 2015 + :url: tools.ietf.org/html/rfc7539.html + .. reference:: RFC7748 :title: Elliptic Curves for Security :author: IETF