From a2003d9a5cc31d0fc8e7914bd96f718e35882a4c Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Thu, 7 Mar 2024 17:17:56 +0000 Subject: [PATCH 01/27] Key encapsulation functions Signed-off-by: Marcus Streets --- doc/crypto/api/ops/encap.rst | 317 +++++++++++++++++++++++++++++++++++ doc/crypto/api/ops/index.rst | 1 + 2 files changed, 318 insertions(+) create mode 100644 doc/crypto/api/ops/encap.rst diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst new file mode 100644 index 00000000..e7081dc8 --- /dev/null +++ b/doc/crypto/api/ops/encap.rst @@ -0,0 +1,317 @@ +Key Encapsulation +================= + +Elliptic Curve Integrated Encryption Scheme +------------------------------------------- + +The Elliptic Curve Integrated Encryption Scheme was fist proposed by Shoup, then imporved 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 + :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_key()` + + When used as a key's permitted-algorithm policy, the following uses are permitted: + + * In a call to `psa_encapsulate_key()` or `psa_decapsulate_key()`, 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. + + .. 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` + +.. 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 establlishment algorithm or ``kdf_alg`` is not a supported key derivation algorithm. + + A combined encapsulation algorithm is used in a call to `psa_encapsulate_key()`. + + 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 +------------- + +.. function:: psa_encapsulate_key + + .. summary:: + Generate a new key, emitting it both as a key object and an encapsulation to send to a counter party. + + + .. param:: const psa_key_id_t * counterparty_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:: const psa_key_id_t * private_key + Identifier of the key belong to the person performing the encapsulation. + It must be an asymmetric key pair. + The key must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` + + .. 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)` . + + .. 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. + + .. 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 fial 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 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`` buffer is too small. + `PSA_ENCAPSULATION_OUTPUT_SIZE()` can be used to determine a sufficient buffer size. + + .. 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_key + + .. summary:: + Uses a private key to decapsulate an encapsulation received from a counter party. + + .. param:: const psa_key_id_t * counterparty_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:: const psa_key_id_t * private_key + Identifier of the key belonging to the person to whom the encapsulated message has been sent. + It must be an asymmetric key pair. + The key must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` + + .. param:: conts uint8_t * encapsulation + Buffer containing the encapsulated keythat 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_key()`. + + .. 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_key()` 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_key()`, 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_key()` will not fail due to an insufficient buffer size. + + See also `PSA_ENCAPSULATION_OUTPUT_SIZE()`. + + + + 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 From f3ef0bc934d2dad2e9938335ee0eda4cca3b0e8a Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 16 Apr 2024 12:58:50 +0100 Subject: [PATCH 02/27] Added Key encapsulation usage Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index fdbbe250..59aabfaa 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -250,6 +250,22 @@ 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_KEY + :definition: ((psa_key_usage_t)0x00008000) + + .. summary:: + Permission to encapsulate new keys. + + This flag is required to use a private key to encapsulate new keys to send to a counter party, or to decapsulate a key buffer obtained from a counter party. + + This flag must be present on private keys used with the following APIs: + + * `psa_encapsulate_key()` + * `psa_decapsulate_key()` + + + .. function:: psa_set_key_usage_flags .. summary:: From f5fddee3a9eb94c7dcffec8b29fab0f69d12f1ed Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 22 Jul 2024 14:44:44 +0100 Subject: [PATCH 03/27] Fixing two typos Signed-off-by: Marcus Streets --- doc/crypto/api/ops/encap.rst | 81 +++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst index e7081dc8..1a46e210 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -4,7 +4,7 @@ Key Encapsulation Elliptic Curve Integrated Encryption Scheme ------------------------------------------- -The Elliptic Curve Integrated Encryption Scheme was fist proposed by Shoup, then imporved by Ballare and Rogaway. +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. @@ -80,7 +80,7 @@ Encapsulation The key must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` .. 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)` . + The full 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)` . .. param:: const psa_key_attributes_t * attributes The attributes for the new key. @@ -139,6 +139,83 @@ Encapsulation .. retval:: PSA_ERROR_BAD_STATE The library requires initializing by a call to `psa_crypto_init()`. +.. function:: psa_encapsulate_key_ephemeral + + .. 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. + + + .. param:: const psa_key_id_t * counterparty_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:: psa_key_id_t * key_pair + On success an Identifier for the new key pair, which was used to perform the encapsulation. + The key will be the same key type are the counterparty key and will be given the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` + `PSA_KEY_ID_NULL` on failure + + .. 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 fial 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 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`` buffer is too small. + `PSA_ENCAPSULATION_OUTPUT_SIZE()` can be used to determine a sufficient buffer size. + + .. 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_key From 660d21560046cf40213b1b6b8a522d8bd965c9dd Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 22 Jul 2024 16:43:26 +0100 Subject: [PATCH 04/27] Changing encapsulation to use ephemeral key Signed-off-by: Marcus Streets --- doc/crypto/api/ops/algorithms.rst | 1 + doc/crypto/api/ops/encap.rst | 110 ++++++------------------------ 2 files changed, 22 insertions(+), 89 deletions(-) diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 8e1c6989..ee6a2201 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 diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst index 1a46e210..4ecbb375 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -61,98 +61,31 @@ While the application can always implement this using the other algorithm functi The resulting combined encapsulation algorithm is compatible with the same key types as the raw encapsulation algorithm used to construct it. +.. _encapsulation-algorithms: -Encapsulation -------------- - +Encapsulation Algorithms +------------------------ .. function:: psa_encapsulate_key .. summary:: - Generate a new key, emitting it both as a key object and an encapsulation to send to a counter party. - - - .. param:: const psa_key_id_t * counterparty_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:: const psa_key_id_t * private_key - Identifier of the key belong to the person performing the encapsulation. - It must be an asymmetric key pair. - The key must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` - - .. param:: psa_algorithm_t alg - The full 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)` . - - .. 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. - - .. 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 fial 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 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`` buffer is too small. - `PSA_ENCAPSULATION_OUTPUT_SIZE()` can be used to determine a sufficient buffer size. - - .. 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_encapsulate_key_ephemeral - - .. 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. - + 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 - 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()`. + 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_KEY`. .. param:: psa_key_id_t * key_pair - On success an Identifier for the new key pair, which was used to perform the encapsulation. - The key will be the same key type are the counterparty key and will be given the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` + On success an identifier for the new key pair, which was used to perform the encapsulation. + The key will be the key type specified in the atributes of the counterparty key. The private key will be given the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY`. The public key only will be given the usage `PSA_KEY_USAGE_EXPORT`. `PSA_KEY_ID_NULL` on failure + .. param:: uint8_t * ephemeral_public_key + Buffer where the ephemeral public key key is to be written, ready to be sent to the counterparty. + + .. 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 . @@ -179,7 +112,7 @@ Encapsulation .. 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 fial due to buffer size for any supported encapsulation algorithm. + 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)`. @@ -188,7 +121,7 @@ Encapsulation .. retval:: PSA_SUCCESS Success. - The bytes of ``encapsulation`` contain the encapsulated key and ``output_key`` contains the identifier for the key to be used to encrypt the message. + 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: @@ -201,9 +134,8 @@ Encapsulation * ``alg`` is not a encapsulation algorithm. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL - The size of the ``encapsulation`` buffer is too small. - `PSA_ENCAPSULATION_OUTPUT_SIZE()` can be used to determine a sufficient buffer size. - + The size of the ``encapsulation`` or the ``ephemeral_public_key`` buffer is too small. + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE @@ -228,10 +160,10 @@ Encapsulation .. param:: const psa_key_id_t * private_key Identifier of the key belonging to the person to whom the encapsulated message has been sent. It must be an asymmetric key pair. - The key must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` + The private half of the key pair must permit the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY` .. param:: conts uint8_t * encapsulation - Buffer containing the encapsulated keythat was received from the counterparty. + Buffer containing the encapsulated key that was received from the counterparty. .. param:: size_t encapsulation_size Size of the ``encapsulation`` buffer in bytes. From be8e319bc84da1e70e5241659425f68939f458d1 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 22 Jul 2024 16:48:09 +0100 Subject: [PATCH 05/27] Minor changes to Encap policy Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 59aabfaa..349223e9 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -33,10 +33,9 @@ The following algorithm policies are supported: * `PSA_ALG_NONE` does not permit any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags. * A specific algorithm value permits exactly that particular algorithm. * A signature algorithm constructed with `PSA_ALG_ANY_HASH` permits the specified signature scheme with any hash algorithm. In addition, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. -* A standalone key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm. +* A raw key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm. * An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. * An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. -* The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16. When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy. @@ -232,11 +231,10 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. This flag must be present on keys used with the following APIs: - * `psa_key_agreement()` * `psa_key_derivation_key_agreement()` * `psa_raw_key_agreement()` - 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_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()` at the end of the operation. + 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_output_bytes()` or `psa_key_derivation_output_key()` at the end of the operation. .. macro:: PSA_KEY_USAGE_VERIFY_DERIVATION :definition: ((psa_key_usage_t)0x00008000) From b9229dd9773997a74ea767689f2d7b7b1cd3a45f Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 24 Jul 2024 14:53:45 +0100 Subject: [PATCH 06/27] Reverting inadvertent changes due to having a stale copy of the file in my local storage Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 349223e9..b5b074e8 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -33,10 +33,10 @@ The following algorithm policies are supported: * `PSA_ALG_NONE` does not permit any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags. * A specific algorithm value permits exactly that particular algorithm. * A signature algorithm constructed with `PSA_ALG_ANY_HASH` permits the specified signature scheme with any hash algorithm. In addition, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. -* A raw key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm. +* A standalone key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm. * An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. * An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. - +* The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16. When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy. .. function:: psa_set_key_algorithm @@ -231,11 +231,12 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. This flag must be present on keys used with the following APIs: + * `psa_key_agreement()` * `psa_key_derivation_key_agreement()` * `psa_raw_key_agreement()` - 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_output_bytes()` or `psa_key_derivation_output_key()` at the end of the operation. - + 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_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()` at the end of the operation. + .. macro:: PSA_KEY_USAGE_VERIFY_DERIVATION :definition: ((psa_key_usage_t)0x00008000) From 41551ad4f751fa00d5dc12236d3f4628ff39e3c6 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 24 Jul 2024 14:54:52 +0100 Subject: [PATCH 07/27] And again with the correct year Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index b5b074e8..6151f30e 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 From aefbe8f2b331280c85811f0e1538beaf28a18ce2 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 24 Jul 2024 15:10:25 +0100 Subject: [PATCH 08/27] third times the charm Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 6151f30e..14a2cd3d 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -37,6 +37,7 @@ The following algorithm policies are supported: * An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. * An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. * The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16. + When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy. .. function:: psa_set_key_algorithm @@ -236,7 +237,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. * `psa_raw_key_agreement()` 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_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()` at the end of the operation. - + .. macro:: PSA_KEY_USAGE_VERIFY_DERIVATION :definition: ((psa_key_usage_t)0x00008000) From 72a5c24275aae366b563e9c25befec5af75d940b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 29 Jul 2024 15:40:48 +0100 Subject: [PATCH 09/27] Split encapsulate and decapsulate permissions Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 14a2cd3d..97f432bd 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -232,7 +232,6 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. This flag must be present on keys used with the following APIs: - * `psa_key_agreement()` * `psa_key_derivation_key_agreement()` * `psa_raw_key_agreement()` @@ -250,20 +249,29 @@ 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_KEY - :definition: ((psa_key_usage_t)0x00008000) +.. macro:: PSA_KEY_USAGE_ENCAPSULATE + :definition: ((psa_key_usage_t)0x00010000) .. summary:: Permission to encapsulate new keys. - This flag is required to use a private key to encapsulate new keys to send to a counter party, or to decapsulate a key buffer obtained from a counter party. + This flag is required to encapsulate new keys to send to a counter party. - This flag must be present on private keys used with the following APIs: + 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) - * `psa_encapsulate_key()` - * `psa_decapsulate_key()` + .. 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 From a37f4cd6d6cdc352aa3fa51dd4b4aad558392965 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 29 Jul 2024 15:41:58 +0100 Subject: [PATCH 10/27] Change ephemeral keys to read / write from buffers Signed-off-by: Marcus Streets --- doc/crypto/api/ops/encap.rst | 52 +++++++++++++++++------------------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst index 4ecbb375..adb21784 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -11,19 +11,21 @@ The original specification permitted a number of variants. This specification on 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 +.. 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_key()` + 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_key()` or `psa_decapsulate_key()`, with any combined key establishment and key derivation algorithm constructed with `PSA_ALG_ECIES`. + * 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 @@ -51,9 +53,9 @@ While the application can always implement this using the other algorithm functi .. return:: The corresponding encapsulation and derivation algorithm. - Unspecified if ``ka_alg`` is not a supported key establlishment algorithm or ``kdf_alg`` is not a supported key 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_key()`. + 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()`. @@ -65,21 +67,16 @@ While the application can always implement this using the other algorithm functi Encapsulation Algorithms ------------------------ -.. function:: psa_encapsulate_key +.. 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_KEY`. - - .. param:: psa_key_id_t * key_pair - On success an identifier for the new key pair, which was used to perform the encapsulation. - The key will be the key type specified in the atributes of the counterparty key. The private key will be given the usage `PSA_KEY_USAGE_ENCAPSULATE_KEY`. The public key only will be given the usage `PSA_KEY_USAGE_EXPORT`. - `PSA_KEY_ID_NULL` on failure + 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. + 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. @@ -98,11 +95,10 @@ Encapsulation Algorithms * 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. @@ -149,18 +145,21 @@ Encapsulation Algorithms -.. function:: psa_decapsulate_key +.. function:: psa_decapsulate .. summary:: Uses a private key to decapsulate an encapsulation received from a counter party. - .. param:: const psa_key_id_t * counterparty_key + .. 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 to whom the encapsulated message has been sent. + 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_ENCAPSULATE_KEY` + 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. @@ -168,7 +167,6 @@ Encapsulation Algorithms .. 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. @@ -201,9 +199,7 @@ Encapsulation Algorithms 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 @@ -297,7 +293,7 @@ Support macros :definition: /* implementation-defined value */ .. summary:: - Sufficient output buffer size for `psa_encapsulate_key()`. + Sufficient output buffer size for `psa_encapsulate()`. .. param:: key_type A supported key type. @@ -307,7 +303,7 @@ Support macros .. 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_key()` will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. + 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`. @@ -315,9 +311,9 @@ Support macros :definition: /* implementation-defined value */ .. summary:: - Sufficient output buffer size for `psa_encapsulate_key()`, for any of the supported key types and encapsulation algorithms. + 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_key()` will not fail due to an insufficient buffer size. + 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()`. From 64b246eab0133d0b4e65c163d2163e7e9bdc29a7 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 12:33:09 +0100 Subject: [PATCH 11/27] Adding ML key types Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 163 +++++++++++++++++++++++++--------- 1 file changed, 121 insertions(+), 42 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 9eef6fbb..fdb6fb0e 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -106,8 +106,6 @@ Symmetric keys | `PSA_ALG_HKDF` (non-secret inputs) | `PSA_ALG_HKDF_EXPAND` (non-secret inputs) | `PSA_ALG_HKDF_EXTRACT` (non-secret inputs) - | `PSA_ALG_SP800_108_COUNTER_HMAC` (non-secret inputs) - | `PSA_ALG_SP800_108_COUNTER_CMAC` (non-secret inputs) | `PSA_ALG_TLS12_PRF` (non-secret inputs) | `PSA_ALG_TLS12_PSK_TO_MS` (non-secret inputs) @@ -117,18 +115,11 @@ Symmetric keys .. summary:: HMAC key. - HMAC keys can be used in HMAC, or HMAC-based, algorithms. - Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type. - The permitted-algorithm policy for the key must specify a particular hash algorithm. + The key policy determines which underlying hash algorithm the key can be used for. - The bit size of an HMAC key must be a non-zero multiple of 8. - An HMAC key is typically the same size as the output of the underlying hash algorithm. - An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`. + The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use. - It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used. - 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. + When an HMAC key is created that is longer than the block size, it is :scterm:`implementation defined` whether the implementation stores the original HMAC key, or the hash of the HMAC key. If the hash of the key is stored, the key size reported by `psa_get_key_attributes()` will be the size of the hashed key. .. note:: @@ -139,7 +130,6 @@ Symmetric keys .. subsection:: Compatible algorithms | `PSA_ALG_HMAC` - | `PSA_ALG_SP800_108_COUNTER_HMAC` (secret input) .. macro:: PSA_KEY_TYPE_DERIVE :definition: ((psa_key_type_t)0x1200) @@ -244,7 +234,6 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` - | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_ARIA :definition: ((psa_key_type_t)0x2406) @@ -279,7 +268,6 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` - | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_DES :definition: ((psa_key_type_t)0x2301) @@ -345,7 +333,6 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` - | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_SM4 :definition: ((psa_key_type_t)0x2405) @@ -372,7 +359,6 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` - | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_ARC4 :definition: ((psa_key_type_t)0x2002) @@ -408,23 +394,6 @@ Symmetric keys | `PSA_ALG_STREAM_CIPHER` | `PSA_ALG_CHACHA20_POLY1305` -.. macro:: PSA_KEY_TYPE_XCHACHA20 - :definition: ((psa_key_type_t)0x2007) - - .. summary:: - Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm. - - The XChaCha20 key size is 256 bits (32 bytes). - - * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the XChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. - - * Use algorithm `PSA_ALG_XCHACHA20_POLY1305` to use this key with the XChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_XCHACHA20_POLY1305` for details of this algorithm. - - .. subsection:: Compatible algorithms - - | `PSA_ALG_STREAM_CIPHER` - | `PSA_ALG_XCHACHA20_POLY1305` - .. _asymmetric-keys: @@ -488,9 +457,7 @@ Elliptic Curve keys The range of Elliptic curve family identifier values is divided as follows: - :code:`0x00` - Reserved. Not allocated to an ECC family. - :code:`0x01 – 0x7f` + :code:`0x00 – 0x7f` ECC family identifiers defined by this standard. Unallocated values in this range are reserved for future use. :code:`0x80 – 0xff` @@ -502,7 +469,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 *q* for a curve over a field *F*\ :sub:`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. @@ -806,9 +773,7 @@ Diffie Hellman keys The range of Diffie-Hellman group family identifier values is divided as follows: - :code:`0x00` - Reserved. Not allocated to a DH group family. - :code:`0x01 – 0x7f` + :code:`0x00 – 0x7f` DH group family identifiers defined by this standard. Unallocated values in this range are reserved for future use. :code:`0x80 – 0xff` @@ -920,6 +885,120 @@ 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:`FIPS 203` and :cite:`FIPS 204`. + +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 + + .. table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :widths: auto + + ======= =============== =================== =================== ============ + 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. + +.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR + :definition: ((psa_key_type_t)0xy001) + + .. summary:: + ML KEM 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 + + .. 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. + + .. table:: Sizes (in bytes) of keys and cipher texts for ML-DSA + :widths: auto + + ======= =============== ============= ============ =========== + 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 ------------------- From ceac028ab74b5770f1e7a76d3b070dcd8c038c70 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 12:35:02 +0100 Subject: [PATCH 12/27] Adding ML signature and encapsulations algorithms Also adds SHAKE128_256 for use with ML-DSA Signed-off-by: Marcus Streets --- doc/crypto/api/ops/algorithms.rst | 1 + doc/crypto/api/ops/encap.rst | 26 ++++++++++ doc/crypto/api/ops/hashes.rst | 79 +++++++++++++++---------------- doc/crypto/api/ops/sign.rst | 51 ++++++++++++++++---- 4 files changed, 106 insertions(+), 51 deletions(-) diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index ee6a2201..b8ebdd31 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -228,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 index adb21784..869cc9d6 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -39,6 +39,30 @@ While the application can always implement this using the other algorithm functi * `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 */ @@ -63,6 +87,8 @@ While the application can always implement this using the other algorithm functi 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 diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 9f2e7089..122fce9a 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -73,20 +73,6 @@ Hash algorithms RIPEMD-160 is defined in :cite-title:`RIPEMD`, and also in :cite-title:`ISO10118`. -.. macro:: PSA_ALG_AES_MMO_ZIGBEE - :definition: ((psa_algorithm_t)0x02000007) - - .. 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 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)`. - .. macro:: PSA_ALG_SHA_1 :definition: ((psa_algorithm_t)0x02000005) @@ -191,6 +177,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) @@ -323,7 +322,7 @@ Multi-part hashing operations psa_hash_operation_t operation; operation = psa_hash_operation_init(); - This is an implementation-defined type. Applications that make assumptions about the content of this object will result in implementation-specific behavior, and are non-portable. + This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable. .. macro:: PSA_HASH_OPERATION_INIT :definition: /* implementation-defined value */ @@ -780,37 +779,35 @@ Hash suspend state format The hash suspend state has the following format: -.. math:: - - hash\_suspend\_state = algorithm\ ||\ input\_length\ ||\ hash\_state\ ||\ unprocessed\_input +*hash-suspend-state* = *algorithm* || *input-length* || *hash-state* || *unprocessed-input* The fields in the hash suspend state are defined as follows: -:math:`algorithm` +*algorithm* A big-endian 32-bit unsigned integer. The |API| algorithm identifier value. - The byte length of the :math:`algorithm` field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`. + The byte length of the *algorithm* field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`. -:math:`input\_length` +*input-length* A big-endian unsigned integer The content of this field is algorithm-specific: - * For MD2, this is the number of bytes in :math:`unprocessed\_input`. - * For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the :math:`unprocessed\_input` bytes. + * For MD2, this is the number of bytes in the *unprocessed-input*. + * For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the *unprocessed-input* bytes. The size of this field is algorithm-specific: - * For MD2: :math:`input\_length` is an 8-bit unsigned integer. - * For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: :math:`input\_length` is a 64-bit unsigned integer. - * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: :math:`input\_length` is a 128-bit unsigned integer. + * For MD2: *input-length* is an 8-bit unsigned integer. + * For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: *input-length* is a 64-bit unsigned integer. + * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: *input-length* is a 128-bit unsigned integer. - The length, in bytes, of the :math:`input\_length` field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. + The length, in bytes, of the *input-length* field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. -:math:`hash\_state` +*hash-state* An array of bytes Algorithm-specific intermediate hash state: @@ -823,19 +820,17 @@ The fields in the hash suspend state are defined as follows: * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in big-endian encoding. The length of this field is specific to the algorithm. - The length, in bytes, of the :math:`hash\_state` field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. + The length, in bytes, of the *hash-state* field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. -:math:`unprocessed\_input` - :math:`0\ \text{to}\ (hash\_block\_size - 1)` bytes - - A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size - 1` bytes of data, the length can be calculated by: +*unprocessed-input* + 0 to (*hash-block-size*-1) bytes - .. math:: + A partial block of unprocessed input data. This is between zero and *hash-block-size*-1 bytes of data, the length can be calculated by: - \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. + ``length(``\ *unprocessed-input*\ ``)`` ``=`` *input-length* ``%`` *hash-block-size*. - The value of :math:`hash\_block\_size` is specific to the hash algorithm. + The *hash-block-size* is specific to the algorithm. The size of a hash block can be calculated using :code:`PSA_HASH_BLOCK_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. @@ -846,10 +841,10 @@ Hash suspend state field sizes The following table defines the algorithm-specific field lengths for the hash suspend state returned by `psa_hash_suspend()`. All of the field lengths are in bytes. To compute the field lengths for algorithm ``alg``, use the following expressions: -* :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the :math:`algorithm` field. -* :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the :math:`input\_length` field. -* :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the :math:`hash\_state` field. -* :code:`PSA_HASH_BLOCK_LENGTH(alg) - 1` is the maximum length of the :math:`unprocessed\_bytes` field. +* :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the *algorithm* field. +* :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the *input-length* field. +* :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the *hash-state* field. +* :code:`PSA_HASH_BLOCK_LENGTH(alg)-1` is the maximum length of the *unprocessed-bytes* field. * :code:`PSA_HASH_SUSPEND_OUTPUT_SIZE(alg)` returns the maximum size of the hash suspend state. .. csv-table:: @@ -857,7 +852,7 @@ The following table defines the algorithm-specific field lengths for the hash su :widths: auto :align: left - Hash algorithm, :math:`input\_length` size (bytes), :math:`hash\_state` length (bytes), :math:`unprocessed\_bytes` length (bytes) + Hash algorithm, *input-length* size (bytes), *hash-state* length (bytes), *unprocessed-bytes* length (bytes) `PSA_ALG_MD2`, 1, 64, 0 -- 15 `PSA_ALG_MD4`, 8, 16, 0 -- 63 `PSA_ALG_MD5`, 8, 16, 0 -- 63 diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index d802a9ea..c703b640 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -40,7 +40,7 @@ Asymmetric signature algorithms This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5. - When used with `psa_sign_hash()` or `psa_verify_hash()`, the provided ``hash`` parameter is used as :math:`H` from step 2 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`H` is the message digest, computed using the ``hash_alg`` hash algorithm. + When used with `psa_sign_hash()` or `psa_verify_hash()`, the provided ``hash`` parameter is used as *H* from step 2 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. *H* is the message digest, computed using the ``hash_alg`` hash algorithm. .. subsection:: Compatible key types @@ -57,7 +57,7 @@ Asymmetric signature algorithms This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5. - The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as :math:`T` from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`T` is normally the DER encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length. + The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as *T* from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. *T* is normally the DER encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length. The wildcard key policy :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits a key to be used with the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. @@ -172,9 +172,9 @@ Asymmetric signature algorithms In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. - This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. + This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number *k*. - The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math:`s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. + The representation of the signature as a byte string consists of the concatenation of the signature values *r* and *s*. Each of *r* and *s* is encoded as an *N*-octet string, where *N* is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. .. subsection:: Compatible key types @@ -268,9 +268,9 @@ Asymmetric signature algorithms PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported: - * Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of :math:`R` and :math:`S` as defined by :RFC:`8032#5.1.6`. + * Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of *R* and *S* as defined by :RFC:`8032#5.1.6`. - * Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of :math:`R` and :math:`S` as defined by :RFC:`8032#5.2.6`. + * Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of *R* and *S* as defined by :RFC:`8032#5.2.6`. .. note:: Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts. @@ -314,7 +314,7 @@ Asymmetric signature algorithms .. admonition:: Implementation note - 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.1`. + When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as ``PH(M)`` in the algorithms defined in :RFC:`8032#5.1`. .. macro:: PSA_ALG_ED448PH :definition: ((psa_algorithm_t) 0x06000915) @@ -345,9 +345,42 @@ Asymmetric signature algorithms .. admonition:: Implementation note - 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`. + When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as ``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 ------------------------------ From f51173155e806520a99067505673196703718bd9 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 13:12:23 +0100 Subject: [PATCH 13/27] Forgot the citations Signed-off-by: Marcus Streets --- doc/crypto/references | 60 +++++++++++++++---------------------------- 1 file changed, 21 insertions(+), 39 deletions(-) diff --git a/doc/crypto/references b/doc/crypto/references index 3f5c5eda..f451fc33 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -1,8 +1,8 @@ -.. SPDX-FileCopyrightText: Copyright 2020-2024 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2020-2022 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. reference:: PSA-PAKE - :title: PSA Certified Crypto API 1.2 PAKE Extension + :title: PSA Certified Crypto API 1.1 PAKE Extension :doc_no: ARM AES 0058 :url: arm-software.github.io/psa-api/crypto @@ -14,7 +14,7 @@ .. reference:: PSA-FFM :title: Arm® Platform Security Architecture Firmware Framework :doc_no: ARM DEN 0063 - :url: developer.arm.com/documentation/den0063 + :url: pages.arm.com/psa-apis .. reference:: PSA-STAT :title: PSA Certified Status code API @@ -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 @@ -147,12 +159,6 @@ :publication: November 2017 :url: doi.org/10.6028/NIST.SP.800-67r2 -.. reference:: SP800-108 - :title: NIST Special Publication 800-108r1: Recommendation for Key Derivation Using Pseudorandom Functions - :author: NIST - :publication: August 2022 - :url: doi.org/10.6028/NIST.SP.800-108r1 - .. reference:: RFC1319 :title: The MD2 Message-Digest Algorithm :author: IETF @@ -261,6 +267,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 @@ -291,12 +303,6 @@ :publication: January 2017 :url: tools.ietf.org/html/rfc8032.html -.. reference:: RFC8439 - :title: ChaCha20 and Poly1305 for IETF Protocols - :author: IRTF - :publication: June 2018 - :url: tools.ietf.org/html/rfc8439.html - .. reference:: RIPEMD :title: RIPEMD-160: A Strengthened Version of RIPEMD :author: Dobbertin, Bosselaers and Preneel @@ -336,32 +342,8 @@ :url: http://cr.yp.to/chacha/chacha-20080128.pdf :publication: January 2008 -.. reference:: XCHACHA - :title: XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 - :author: Arciszewski - :publication: January 2020 - :url: datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03 - .. reference:: CLULOW :author: Clulow, Jolyon :title: On the Security of PKCS #11 :url: link.springer.com/chapter/10.1007/978-3-540-45238-6_32 :publication: 2003 - -.. reference:: TLS-ECJPAKE - :title: Elliptic Curve J-PAKE Cipher Suites for Transport Layer Security (TLS) - :author: Cragie, Hao - :publication: June 2016 - :url: datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01 - -.. reference:: ZIGBEE - :author: zigbee alliance - :title: zigbee Specification - :url: csa-iot.org/wp-content/uploads/2022/01/docs-05-3474-22-0csg-zigbee-specification-1.pdf - :publication: April 2017 - -.. reference:: IEEE-CCM - :author: IEEE - :title: IEEE Standard for Low-Rate Wireless Networks - :url: standards.ieee.org/ieee/802.15.4/7029/ - :publication: 2020 From 879c587e926b87254702ccc8332260a71b3e355b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 13:14:00 +0100 Subject: [PATCH 14/27] Correcting the tables Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 81 ++++++++++++++++++++++------------- 1 file changed, 52 insertions(+), 29 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index fdb6fb0e..ba27ec7d 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -903,30 +903,36 @@ There are two related, but separate algorithms a key encapsulation method, ML-KE The parameter sets refer to the key strength, the actual size of the key - .. table:: Sizes (in bytes) of keys and cipher texts for ML-KEM - :widths: auto + .. 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 - ======= =============== =================== =================== ============ - 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 - + * - 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. -.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR - :definition: ((psa_key_type_t)0xy001) - - .. summary:: - ML KEM 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 - .. subsection:: Compatible algorithms | `PSA_ALG_MLKEM` @@ -962,16 +968,33 @@ There are two related, but separate algorithms a key encapsulation method, ML-KE The parameter sets refer to the dimensions of the matrix A, and do not directly define key size. - .. table:: Sizes (in bytes) of keys and cipher texts for ML-DSA - :widths: auto + .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :header-rows: 1 + + * - Size + - Parameter Set + - Private key + - Public key + - Signature - ======= =============== ============= ============ =========== - 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 - + * - 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` From 5ceff797b1e8f89fd3019d00adeece3047a93d5e Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 15:19:28 +0100 Subject: [PATCH 15/27] Attempting to resolve merge conflicts Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 50 +++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index ba27ec7d..30ca7864 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2022 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 @@ -106,6 +106,8 @@ Symmetric keys | `PSA_ALG_HKDF` (non-secret inputs) | `PSA_ALG_HKDF_EXPAND` (non-secret inputs) | `PSA_ALG_HKDF_EXTRACT` (non-secret inputs) + | `PSA_ALG_SP800_108_COUNTER_HMAC` (non-secret inputs) + | `PSA_ALG_SP800_108_COUNTER_CMAC` (non-secret inputs) | `PSA_ALG_TLS12_PRF` (non-secret inputs) | `PSA_ALG_TLS12_PSK_TO_MS` (non-secret inputs) @@ -115,12 +117,19 @@ Symmetric keys .. summary:: HMAC key. - The key policy determines which underlying hash algorithm the key can be used for. + HMAC keys can be used in HMAC, or HMAC-based, algorithms. + Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type. + The permitted-algorithm policy for the key must specify a particular hash algorithm. - The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use. + The bit size of an HMAC key must be a non-zero multiple of 8. + An HMAC key is typically the same size as the output of the underlying hash algorithm. + An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`. - When an HMAC key is created that is longer than the block size, it is :scterm:`implementation defined` whether the implementation stores the original HMAC key, or the hash of the HMAC key. If the hash of the key is stored, the key size reported by `psa_get_key_attributes()` will be the size of the hashed key. + It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used. + 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. @@ -130,6 +139,7 @@ Symmetric keys .. subsection:: Compatible algorithms | `PSA_ALG_HMAC` + | `PSA_ALG_SP800_108_COUNTER_HMAC` (secret input) .. macro:: PSA_KEY_TYPE_DERIVE :definition: ((psa_key_type_t)0x1200) @@ -234,6 +244,7 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` + | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_ARIA :definition: ((psa_key_type_t)0x2406) @@ -268,6 +279,7 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` + | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_DES :definition: ((psa_key_type_t)0x2301) @@ -333,6 +345,7 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` + | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_SM4 :definition: ((psa_key_type_t)0x2405) @@ -395,6 +408,23 @@ Symmetric keys | `PSA_ALG_CHACHA20_POLY1305` +.. macro:: PSA_KEY_TYPE_XCHACHA20 + :definition: ((psa_key_type_t)0x2007) + + .. summary:: + Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm. + + The XChaCha20 key size is 256 bits (32 bytes). + + * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the XChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. + + * Use algorithm `PSA_ALG_XCHACHA20_POLY1305` to use this key with the XChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_XCHACHA20_POLY1305` for details of this algorithm. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_STREAM_CIPHER` + | `PSA_ALG_XCHACHA20_POLY1305` + .. _asymmetric-keys: RSA keys @@ -457,7 +487,9 @@ Elliptic Curve keys The range of Elliptic curve family identifier values is divided as follows: - :code:`0x00 – 0x7f` + :code:`0x00` + Reserved. Not allocated to an ECC family. + :code:`0x01 – 0x7f` ECC family identifiers defined by this standard. Unallocated values in this range are reserved for future use. :code:`0x80 – 0xff` @@ -469,7 +501,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 *q* for a curve over a field *F*\ :sub:`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. @@ -773,7 +805,9 @@ Diffie Hellman keys The range of Diffie-Hellman group family identifier values is divided as follows: - :code:`0x00 – 0x7f` + :code:`0x00` + Reserved. Not allocated to a DH group family. + :code:`0x01– 0x7f` DH group family identifiers defined by this standard. Unallocated values in this range are reserved for future use. :code:`0x80 – 0xff` @@ -888,7 +922,7 @@ Diffie Hellman keys Module Lattice keys ------------------- -PSA supports Module Lattice Cryptography as defined in :cite:`FIPS 203` and :cite:`FIPS 204`. +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. From c0437719f6876f6a1e9d6dfe88fa3e7a8f89097a Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 15:22:02 +0100 Subject: [PATCH 16/27] Conflicts Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 30ca7864..d0d29504 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -372,6 +372,7 @@ Symmetric keys | `PSA_ALG_ECB_NO_PADDING` | `PSA_ALG_CCM` | `PSA_ALG_GCM` + | `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input) .. macro:: PSA_KEY_TYPE_ARC4 :definition: ((psa_key_type_t)0x2002) @@ -807,7 +808,7 @@ Diffie Hellman keys :code:`0x00` Reserved. Not allocated to a DH group family. - :code:`0x01– 0x7f` + :code:`0x01 – 0x7f` DH group family identifiers defined by this standard. Unallocated values in this range are reserved for future use. :code:`0x80 – 0xff` From d0d028688432854e0b8dea9554679873cbdfa65b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 15:42:27 +0100 Subject: [PATCH 17/27] Conflicts 2 Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 97f432bd..27279665 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -232,6 +232,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. This flag must be present on keys used with the following APIs: + * `psa_key_agreement()` * `psa_key_derivation_key_agreement()` * `psa_raw_key_agreement()` From 07ee6573c8c983a9235eda9b174bf362dd0300e5 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 15:51:22 +0100 Subject: [PATCH 18/27] Conflicts Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 60 +++++++++++++++++++++++------------ doc/crypto/api/ops/sign.rst | 18 +++++------ 2 files changed, 48 insertions(+), 30 deletions(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 122fce9a..d52448cb 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.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 @@ -73,6 +73,20 @@ Hash algorithms RIPEMD-160 is defined in :cite-title:`RIPEMD`, and also in :cite-title:`ISO10118`. +.. macro:: PSA_ALG_AES_MMO_ZIGBEE + :definition: ((psa_algorithm_t)0x02000007) + + .. 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 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)`. + .. macro:: PSA_ALG_SHA_1 :definition: ((psa_algorithm_t)0x02000005) @@ -322,7 +336,7 @@ Multi-part hashing operations psa_hash_operation_t operation; operation = psa_hash_operation_init(); - This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable. + This is an implementation-defined type. Applications that make assumptions about the content of this object will result in implementation-specific behavior, and are non-portable. .. macro:: PSA_HASH_OPERATION_INIT :definition: /* implementation-defined value */ @@ -779,35 +793,37 @@ Hash suspend state format The hash suspend state has the following format: +.. math:: + *hash-suspend-state* = *algorithm* || *input-length* || *hash-state* || *unprocessed-input* The fields in the hash suspend state are defined as follows: -*algorithm* +:math:`algorithm` A big-endian 32-bit unsigned integer. The |API| algorithm identifier value. - The byte length of the *algorithm* field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`. + The byte length of the :math:`algorithm` field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`. -*input-length* +:math:`input\_length` A big-endian unsigned integer The content of this field is algorithm-specific: - * For MD2, this is the number of bytes in the *unprocessed-input*. - * For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the *unprocessed-input* bytes. + * For MD2, this is the number of bytes in the :math:`unprocessed\_input`. + * For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the :math:`unprocessed\_input` bytes. The size of this field is algorithm-specific: - * For MD2: *input-length* is an 8-bit unsigned integer. - * For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: *input-length* is a 64-bit unsigned integer. - * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: *input-length* is a 128-bit unsigned integer. + * For MD2: :math:`input\_length` is an 8-bit unsigned integer. + * For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: :math:`input\_length` is a 64-bit unsigned integer. + * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: :math:`input\_length` is a 128-bit unsigned integer. - The length, in bytes, of the *input-length* field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. + The length, in bytes, of the :math:`input\_length` field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. -*hash-state* +:math:`hash\_state` An array of bytes Algorithm-specific intermediate hash state: @@ -820,17 +836,19 @@ The fields in the hash suspend state are defined as follows: * For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in big-endian encoding. The length of this field is specific to the algorithm. - The length, in bytes, of the *hash-state* field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. + The length, in bytes, of the :math:`hash\_state` field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. -*unprocessed-input* +:math:`unprocessed\_input` 0 to (*hash-block-size*-1) bytes A partial block of unprocessed input data. This is between zero and *hash-block-size*-1 bytes of data, the length can be calculated by: - ``length(``\ *unprocessed-input*\ ``)`` ``=`` *input-length* ``%`` *hash-block-size*. + :math: + + \\text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. - The *hash-block-size* is specific to the algorithm. + The value of :math:`hash\_block\_size` is specific to the hash algorithm. The size of a hash block can be calculated using :code:`PSA_HASH_BLOCK_LENGTH(alg)` where ``alg`` is a hash algorithm. See :secref:`hash-suspend-state-constants`. @@ -841,10 +859,10 @@ Hash suspend state field sizes The following table defines the algorithm-specific field lengths for the hash suspend state returned by `psa_hash_suspend()`. All of the field lengths are in bytes. To compute the field lengths for algorithm ``alg``, use the following expressions: -* :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the *algorithm* field. -* :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the *input-length* field. -* :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the *hash-state* field. -* :code:`PSA_HASH_BLOCK_LENGTH(alg)-1` is the maximum length of the *unprocessed-bytes* field. +* :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the :math:`algorithm` field. +* :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the :math:`input\_length` field. +* :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the :math:`hash\_state` field. +* :code:`PSA_HASH_BLOCK_LENGTH(alg)-1` is the maximum length of the :math:`unprocessed\_bytes` field. * :code:`PSA_HASH_SUSPEND_OUTPUT_SIZE(alg)` returns the maximum size of the hash suspend state. .. csv-table:: @@ -852,7 +870,7 @@ The following table defines the algorithm-specific field lengths for the hash su :widths: auto :align: left - Hash algorithm, *input-length* size (bytes), *hash-state* length (bytes), *unprocessed-bytes* length (bytes) + Hash algorithm, :math:`input\_length` size (bytes), :math:`hash\_state` length (bytes), :math:`unprocessed\_bytes` length (bytes) `PSA_ALG_MD2`, 1, 64, 0 -- 15 `PSA_ALG_MD4`, 8, 16, 0 -- 63 `PSA_ALG_MD5`, 8, 16, 0 -- 63 diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index c703b640..30caae0e 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.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 @@ -40,7 +40,7 @@ Asymmetric signature algorithms This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5. - When used with `psa_sign_hash()` or `psa_verify_hash()`, the provided ``hash`` parameter is used as *H* from step 2 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. *H* is the message digest, computed using the ``hash_alg`` hash algorithm. + When used with `psa_sign_hash()` or `psa_verify_hash()`, the provided ``hash`` parameter is used as :math:`H` from step 2 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`H` is the message digest, computed using the ``hash_alg`` hash algorithm. .. subsection:: Compatible key types @@ -57,7 +57,7 @@ Asymmetric signature algorithms This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5. - The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as *T* from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. *T* is normally the DER encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length. + The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as :math:`T` from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`T` is normally the DER encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length. The wildcard key policy :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits a key to be used with the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. @@ -172,9 +172,9 @@ Asymmetric signature algorithms In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. - This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number *k*. + This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. - The representation of the signature as a byte string consists of the concatenation of the signature values *r* and *s*. Each of *r* and *s* is encoded as an *N*-octet string, where *N* is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. + The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math`1s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. .. subsection:: Compatible key types @@ -268,9 +268,9 @@ Asymmetric signature algorithms PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported: - * Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of *R* and *S* as defined by :RFC:`8032#5.1.6`. + * Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of :math:`R` and :math:`S` as defined by :RFC:`8032#5.1.6`. - * Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of *R* and *S* as defined by :RFC:`8032#5.2.6`. + * Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of :math:`R` and :math:`S` as defined by :RFC:`8032#5.2.6`. .. note:: Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts. @@ -314,7 +314,7 @@ Asymmetric signature algorithms .. admonition:: Implementation note - When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as ``PH(M)`` in the algorithms defined in :RFC:`8032#5.1`. + 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.1`. .. macro:: PSA_ALG_ED448PH :definition: ((psa_algorithm_t) 0x06000915) @@ -345,7 +345,7 @@ Asymmetric signature algorithms .. admonition:: Implementation note - When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as ``PH(M)`` in the algorithms defined in :RFC:`8032#5.2`. + 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) From 66b07f716609130d15a75e91d973764ba0312c29 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 15:56:45 +0100 Subject: [PATCH 19/27] conflicts Signed-off-by: Marcus Streets --- doc/crypto/references | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/doc/crypto/references b/doc/crypto/references index f451fc33..1077a3e4 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -1,8 +1,8 @@ -.. SPDX-FileCopyrightText: Copyright 2020-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2020-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. reference:: PSA-PAKE - :title: PSA Certified Crypto API 1.1 PAKE Extension + :title: PSA Certified Crypto API 1.2 PAKE Extension :doc_no: ARM AES 0058 :url: arm-software.github.io/psa-api/crypto @@ -14,7 +14,7 @@ .. reference:: PSA-FFM :title: Arm® Platform Security Architecture Firmware Framework :doc_no: ARM DEN 0063 - :url: pages.arm.com/psa-apis + :url: developer.arm.com/documentation/den0063 .. reference:: PSA-STAT :title: PSA Certified Status code API @@ -159,6 +159,12 @@ :publication: November 2017 :url: doi.org/10.6028/NIST.SP.800-67r2 +.. reference:: SP800-108 + :title: NIST Special Publication 800-108r1: Recommendation for Key Derivation Using Pseudorandom Functions + :author: NIST + :publication: August 2022 + :url: doi.org/10.6028/NIST.SP.800-108r1 + .. reference:: RFC1319 :title: The MD2 Message-Digest Algorithm :author: IETF @@ -303,6 +309,12 @@ :publication: January 2017 :url: tools.ietf.org/html/rfc8032.html +.. reference:: RFC8439 + :title: ChaCha20 and Poly1305 for IETF Protocols + :author: IRTF + :publication: June 2018 + :url: tools.ietf.org/html/rfc8439.html + .. reference:: RIPEMD :title: RIPEMD-160: A Strengthened Version of RIPEMD :author: Dobbertin, Bosselaers and Preneel @@ -342,8 +354,32 @@ :url: http://cr.yp.to/chacha/chacha-20080128.pdf :publication: January 2008 +.. reference:: XCHACHA + :title: XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 + :author: Arciszewski + :publication: January 2020 + :url: datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03 + .. reference:: CLULOW :author: Clulow, Jolyon :title: On the Security of PKCS #11 :url: link.springer.com/chapter/10.1007/978-3-540-45238-6_32 :publication: 2003 + +.. reference:: TLS-ECJPAKE + :title: Elliptic Curve J-PAKE Cipher Suites for Transport Layer Security (TLS) + :author: Cragie, Hao + :publication: June 2016 + :url: datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01 + +.. reference:: ZIGBEE + :author: zigbee alliance + :title: zigbee Specification + :url: csa-iot.org/wp-content/uploads/2022/01/docs-05-3474-22-0csg-zigbee-specification-1.pdf + :publication: April 2017 + +.. reference:: IEEE-CCM + :author: IEEE + :title: IEEE Standard for Low-Rate Wireless Networks + :url: standards.ieee.org/ieee/802.15.4/7029/ + :publication: 2020 \ No newline at end of file From e6c24fea76aef79ea108862985e01962debd817e Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:24:19 +0100 Subject: [PATCH 20/27] Add files via upload Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index d52448cb..5c8548c8 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -795,7 +795,7 @@ The hash suspend state has the following format: .. math:: -*hash-suspend-state* = *algorithm* || *input-length* || *hash-state* || *unprocessed-input* +hash\_suspend\_state = algorithm || input\_length || hash\_state || unprocessed\_input The fields in the hash suspend state are defined as follows: @@ -811,7 +811,7 @@ The fields in the hash suspend state are defined as follows: The content of this field is algorithm-specific: - * For MD2, this is the number of bytes in the :math:`unprocessed\_input`. + * For MD2, this is the number of bytes in :math:`unprocessed\_input`. * For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the :math:`unprocessed\_input` bytes. The size of this field is algorithm-specific: @@ -840,13 +840,13 @@ The fields in the hash suspend state are defined as follows: See :secref:`hash-suspend-state-constants`. :math:`unprocessed\_input` - 0 to (*hash-block-size*-1) bytes + :math:`0\ \text{to}\ (hash\_block\_size - 1)` bytes - A partial block of unprocessed input data. This is between zero and *hash-block-size*-1 bytes of data, the length can be calculated by: + A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size`-1 bytes of data, the length can be calculated by: :math: - \\text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. + \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. The value of :math:`hash\_block\_size` is specific to the hash algorithm. The size of a hash block can be calculated using :code:`PSA_HASH_BLOCK_LENGTH(alg)` where ``alg`` is a hash algorithm. @@ -862,7 +862,7 @@ The following table defines the algorithm-specific field lengths for the hash su * :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the :math:`algorithm` field. * :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the :math:`input\_length` field. * :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the :math:`hash\_state` field. -* :code:`PSA_HASH_BLOCK_LENGTH(alg)-1` is the maximum length of the :math:`unprocessed\_bytes` field. +* :code:`PSA_HASH_BLOCK_LENGTH(alg) - 1` is the maximum length of the :math:`unprocessed\_bytes` field. * :code:`PSA_HASH_SUSPEND_OUTPUT_SIZE(alg)` returns the maximum size of the hash suspend state. .. csv-table:: From 6ac902005c94b99a6071bf847db8017eb611fb7f Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:30:21 +0100 Subject: [PATCH 21/27] Conflict resolution Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 5c8548c8..378a8158 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -795,7 +795,7 @@ The hash suspend state has the following format: .. math:: -hash\_suspend\_state = algorithm || input\_length || hash\_state || unprocessed\_input + hash\_suspend\_state = algorithm || input\_length || hash\_state || unprocessed\_input The fields in the hash suspend state are defined as follows: @@ -842,9 +842,9 @@ The fields in the hash suspend state are defined as follows: :math:`unprocessed\_input` :math:`0\ \text{to}\ (hash\_block\_size - 1)` bytes - A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size`-1 bytes of data, the length can be calculated by: + A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size - 1` bytes of data, the length can be calculated by: - :math: + .. math:: \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. From 10f719685439ef019b3ab7f32fdedf0454afdc13 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:31:51 +0100 Subject: [PATCH 22/27] Add files via upload Signed-off-by: Marcus Streets --- doc/crypto/api/ops/sign.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index 30caae0e..413090c0 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.rst @@ -174,7 +174,7 @@ Asymmetric signature algorithms This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. - The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math`1s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. + The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math`s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. .. subsection:: Compatible key types From 55ed4da6471baad2c0b9cffe856ebfee2a4cb134 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:33:28 +0100 Subject: [PATCH 23/27] conflicts Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 378a8158..3be303aa 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -845,8 +845,8 @@ The fields in the hash suspend state are defined as follows: A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size - 1` bytes of data, the length can be calculated by: .. math:: - - \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. + + \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size. The value of :math:`hash\_block\_size` is specific to the hash algorithm. The size of a hash block can be calculated using :code:`PSA_HASH_BLOCK_LENGTH(alg)` where ``alg`` is a hash algorithm. From eca28a0e267abe74cbd86152c224ec043df2be7b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:35:19 +0100 Subject: [PATCH 24/27] Conflict Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 3be303aa..b09c7a41 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -795,7 +795,7 @@ The hash suspend state has the following format: .. math:: - hash\_suspend\_state = algorithm || input\_length || hash\_state || unprocessed\_input + hash\_suspend\_state = algorithm\ ||\ input\_length\ ||\ hash\_state\ ||\ unprocessed\_input The fields in the hash suspend state are defined as follows: From 4293e53e18e6ffc42ea7bdbda0bf328117f3cb4c Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:37:24 +0100 Subject: [PATCH 25/27] Add files via upload Signed-off-by: Marcus Streets --- doc/crypto/api/ops/hashes.rst | 2 +- doc/crypto/api/ops/sign.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index b09c7a41..1bf9e6e6 100644 --- a/doc/crypto/api/ops/hashes.rst +++ b/doc/crypto/api/ops/hashes.rst @@ -795,7 +795,7 @@ The hash suspend state has the following format: .. math:: - hash\_suspend\_state = algorithm\ ||\ input\_length\ ||\ hash\_state\ ||\ unprocessed\_input + hash\_suspend\_state = algorithm\ ||\ input\_length\ ||\ hash\_state\ ||\ unprocessed\_input The fields in the hash suspend state are defined as follows: diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index 413090c0..e31a8926 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.rst @@ -174,7 +174,7 @@ Asymmetric signature algorithms This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. - The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math`s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. + The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math:`s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. .. subsection:: Compatible key types From a8445f0ccd5a6c77435131b019eff90ca4dc0b4b Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:40:06 +0100 Subject: [PATCH 26/27] Conflcts - white space Signed-off-by: Marcus Streets --- doc/crypto/references | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/references b/doc/crypto/references index 1077a3e4..fac9ebce 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -314,7 +314,7 @@ :author: IRTF :publication: June 2018 :url: tools.ietf.org/html/rfc8439.html - + .. reference:: RIPEMD :title: RIPEMD-160: A Strengthened Version of RIPEMD :author: Dobbertin, Bosselaers and Preneel @@ -382,4 +382,4 @@ :author: IEEE :title: IEEE Standard for Low-Rate Wireless Networks :url: standards.ieee.org/ieee/802.15.4/7029/ - :publication: 2020 \ No newline at end of file + :publication: 2020 From a7ee3a80f26d1f16d8794806fcc7ba90201741fd Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 2 Sep 2024 16:43:46 +0100 Subject: [PATCH 27/27] lost some important white space Signed-off-by: Marcus Streets --- doc/crypto/api/ops/sign.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/sign.rst index e31a8926..72738938 100644 --- a/doc/crypto/api/ops/sign.rst +++ b/doc/crypto/api/ops/sign.rst @@ -350,10 +350,10 @@ Asymmetric signature algorithms .. macro:: PSA_ALG_MLDSA_SIGN :definition: ((psa_algorithm_t) 0x06000916) -.. summary:: + .. summary:: The Module Lattice Signature scheme, with hashing. -.. param:: hash_alg + .. 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.