From 00365a9a51a98137998c7b099a87f02c162ef8d6 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 2 Oct 2024 17:02:18 +0100 Subject: [PATCH 1/8] Clean version of encapsulation Signed-off-by: Marcus Streets --- doc/crypto/api/keys/policy.rst | 27 ++++++++++++- doc/crypto/api/keys/types.rst | 74 ++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 1 deletion(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 614cb78b..c4e99d52 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -250,6 +250,31 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation. +.. macro:: PSA_KEY_USAGE_ENCAPSULATE + :definition: ((psa_key_usage_t)0x00010000) + + .. summary:: + Permission to encapsulate new keys. + + This flag is required to encapsulate new keys to send to a counter party. + + This flag must be present on public keys used with the following APIs: + + * `psa_encapsulate()` + +.. macro:: PSA_KEY_USAGE_DECAPSULATE + :definition: ((psa_key_usage_t)0x00020000) + + .. summary:: + Permission to decapsulate an encapsulated key. + + This flag is required to decapsulate a key buffer obtained from a counter party. + + This flag must be present on private keys used with the following APIs: + + * `psa_decapsulate()` + + .. function:: psa_set_key_usage_flags .. summary:: diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index ea18391c..b20b2bf1 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1482,6 +1482,80 @@ SPAKE2+ keys .. return:: psa_ecc_family_t The elliptic curve family id, if ``type`` is a supported SPAKE2+ key. Unspecified if ``type`` is not a supported SPAKE2+ key. + +Module Lattice keys +------------------- + + +The |API| supports Module Lattice-based digital signatures (ML-DSA), as defined in :cite-title:`FIPS204`. +and Module Lattice-based Key Encapsulation as defined in :cite:`FIPS204`. + +.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR + :definition: ((psa_key_type_t)0xy001) + + .. summary:: + MLKEM key pair: contains both the decapsulation and encapsulation keys. + PSA Crypto treats decapsulation keys as private keys and encapsulation keys as public keys. + + The size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in FIPS 203. + + The parameter sets refer to the key strength, the actual size of the key + + .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :header-rows: 1 + + * - Size + - Parameter Set + - Encapsulation key + - Decapsulation key + - Ciphertext + + * - 512 + - ML-KEM-512 + - 800 + - 1632 + - 768 + + * - 768 + - ML-KEM-768 + - 1184 + - 2400 + - 1088 + + * - 1024 + - ML-KEM-1024 + - 1568 + - 3168 + - 1568 + + In all cases the shared secret produced is 32-bytes, 256-bits long. + The shared secret can be used directly or passed to a PRF to derive further keys. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLKEM` + +.. macro:: PSA_KEY_TYPE_ML_KEM _PUBLIC_KEY + :definition: ((psa_key_type_t)0x4001) + + .. summary:: + ML-KEM public key. + + The size of an ML-KEM key is the numeric part of the parameter set identifier. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_MLKEM` (encapsulation only) + | +.. macro:: PSA_KEY_TYPE_IS_MLKEM + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-KEM key. This includes both key pairs and public keys. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + Attribute accessors ------------------- From 67ddd5f496afc7941fe27932a9c96f03586a5a76 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 2 Oct 2024 17:03:07 +0100 Subject: [PATCH 2/8] Clean upload of encapsulation Signed-off-by: Marcus Streets --- doc/crypto/api/ops/algorithms.rst | 15 ++ doc/crypto/api/ops/encap.rst | 253 ++++++++++++++++++++++++++++++ doc/crypto/api/ops/index.rst | 1 + 3 files changed, 269 insertions(+) create mode 100644 doc/crypto/api/ops/encap.rst diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 98517b75..4966014a 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -24,6 +24,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope * :secref:`asymmetric-encryption-algorithms` * :secref:`key-agreement-algorithms` * :secref:`pake` +* :secref:`encapsulation-algorithms` Algorithm encoding @@ -193,6 +194,20 @@ Algorithm categories ``1`` if ``alg`` is a password-authenticated key exchange (PAKE) algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. +.. macro:: PSA_ALG_IS_ENCAPSULATION + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an encapsulation algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an encapsuulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See :secref:`encapsulation-algorithms` for a list of defined key derivation algorithms. + Support macros -------------- diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst new file mode 100644 index 00000000..6edad69b --- /dev/null +++ b/doc/crypto/api/ops/encap.rst @@ -0,0 +1,253 @@ +Key Encapsulation +================= + +A key encapsulation effectively combines an ephemeral asymmetric key exchange, key derivation and a authenticated symmetric encryption. + +As the exact details of the key derivation stage depends on the protocol used, the encapsulation and decapsulation functions only perform the asymmetric portion. + +Encapsulation takes the counterparties public key, generates a new key pair, and emits the public key. It also creates a raw and an encapsulated seed value. + +The raw seed can then be passed to a KDF function to produce the symmetric encryption key or keys. + +The public key, encapsulated key and encrypted message can be sent to the counter party. + +Decapsulation uses a private half of a key pair, with the public key and encapsulated seed received from the sender and recreated the raw seed. They can then use the same KDF to creates the keys needed to verify and decrypt the message. + +Elliptic Curve Integrated Encryption Scheme +------------------------------------------- + +The Elliptic Curve Integrated Encryption Scheme was fist proposed by Shoup, then improved by Ballare and Rogaway. + +The original specification permitted a number of variants. This specification only defines the version specified in [SEC1], that is with the use of labels and with the label size defined in bytes. + +It is possible that some applications may need to use older versions to interoperate with legacy systems. + +While the application can always implement this using the other algorithm functions provided, however, an implementation may choose to add these as a convenience in the implementation numbering space. + +.. macro:: PSA_ALG_ECIES_SEC1 + :definition: ((psa_algorithm_t)0x09yyyxxxx) + + .. summary:: + The Elliptic Curve Integrated Encryption Scheme. + + When used as a key's permitted-algorithm policy, the following uses are permitted: + + * In a call to `psa_encapsulate()` or `psa_decapsulate()`. + + This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. + + This uses Cofactor ECDH. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` + + where ``family`` is a Weierstrass or Montgomery Elliptic curve family. That is, one of the following values: + + * ``PSA_ECC_FAMILY_SECT_XX`` + * ``PSA_ECC_FAMILY_SECP_XX`` + * `PSA_ECC_FAMILY_FRP` + * `PSA_ECC_FAMILY_BRAINPOOL_P_R1` + * `PSA_ECC_FAMILY_MONTGOMERY` + +Module Lattice Encapsulation +---------------------------- + +PSA Crypto supports Module Lattice Encapsulation as defined in :city:`FIPS 203`. + +.. macro:: PSA_ALG_MLKEM + :definition: ((psa_algorithm_t)0x09yyyxxxx) + + .. summary:: + Module Lattice Encapsulation. + + 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` + +.. _encapsulation-algorithms: + +Encapsulation Algorithms +------------------------ +.. function:: psa_encapsulate + + .. summary:: + Generate a new key pair and a use that to encapsulate a new secret value, 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. Depending on the protocol, this key may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. + + .. param:: const psa_key_id_t * counterparty_key + The identifier for the public key of the peer. You must have previously imported this key using `psa_import_key()`, and specified the key attributes for the public key type corresponding to the type required for the encapsulation, and the usage usage `PSA_KEY_USAGE_ENCAPSULATE`. + + .. param:: uint8_t * ephemeral_public_key + Buffer where the ephemeral public key key is to be written, ready to be sent to the counterparty. The content of the buffer will be in the same format as `psa_export_key()` for a key of the same type as ``counterparty_key``. + + .. param:: size_t ephemeral_public_key_size + Size of the ``ephemeral_public_key`` buffer in bytes. + This must be at least :code:`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(alg)`. + A buffer of at least :code:`PSA_EXPORT_PUBLIC_KEY_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + + .. param:: psa_algorithm_t alg + The ful encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true and :code:`PSA_ALG_IS_RAW_ENCAPSULATION(alg)` is false . + + .. param:: const psa_key_attributes_t * attributes + The attributes for the new symmetric key. + This function uses the attributes as follows: + + * The key type is required. It cannot be an asymmetric public key. + * The key size is required. It must be a valid size for the key type. + * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. + * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. + * The key lifetime and identifier are required for a persistent key. + + .. note:: + This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. + + .. param:: psa_key_id_t * output_key + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + + .. param:: uint8_t * encapsulation + Buffer where the encapsulated key is to be written, ready to be sent to the counterparty. + + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + + .. param:: size_t * encapsulation_length + On success, the number of bytes that make up the hash value. This is always :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + + .. return:: psa_status_t + + .. retval:: PSA_SUCCESS + Success. + The bytes of ``encapsulation`` contain the encapsulated key, the bytes of ``ephemeral_public_key`` contain the public key and ``output_key`` contains the identifier for the key to be used to encrypt the message. + + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: + + * ``alg`` is not a encapsulation algorithm. + + .. retval:: PSA_ERROR_BUFFER_TOO_SMALL + The size of the ``encapsulation`` or the ``ephemeral_public_key`` buffer is too small. + + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. + +.. function:: psa_decapsulate + + .. summary:: + Uses a private key to decapsulate an encapsulated key received from a counter party. Depending on the protocol, this key may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. + + .. param:: const psa_key_id_t * peer_key + Public key of the peer. The peer key must be in the same format that `psa_import_key()` accepts for the public key type corresponding to the type of ``private_key``. That is, this function performs the equivalent of :code:`psa_import_key(..., peer_key, peer_key_length)`, with key attributes indicating the public key type corresponding to the type of ``private_key``. For example, for ECC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of `psa_export_public_key()`. + + .. param:: size_t peer_key_length + Size of the ``encapsulation`` buffer in bytes. + + .. param:: const psa_key_id_t * private_key + Identifier of the key belonging to the person receiving the encapsulated message. + It must be an asymmetric key pair. + The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` + + .. param:: conts uint8_t * encapsulation + Buffer containing the encapsulated key that was received from the counterparty. + + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + + .. param:: psa_algorithm_t alg + The encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + + .. param:: const psa_key_attributes_t * attributes + The attributes for the new key. + This function uses the attributes as follows: + + * The key type is required. It cannot be an asymmetric public key. + * The key size is required. It must be a valid size for the key type. + * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. + * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. + * The key lifetime and identifier are required for a persistent key. + + .. note:: + This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. + + .. param:: psa_key_id_t * output_key + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. + +Support macros +-------------- + +.. macro:: PSA_ALG_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. + +.. macro:: PSA_ENCAPSULATION_OUTPUT_SIZE + :definition: /* implementation-defined value */ + + .. summary:: + Sufficient output buffer size for `psa_encapsulate()`. + + .. param:: key_type + A supported key type. + .. param:: key_bits + The size of the key in bits. + + .. return:: + A sufficient output buffer size for the specified key type and size. An implementation can return either ``0`` or a correct size for a key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. + + If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. + + See also `PSA_ENCAPSULATION_OUTPUT_MAX_SIZE`. + +.. macro:: PSA_ENCAPSULATION_OUTPUT_MAX_SIZE + :definition: /* implementation-defined value */ + + .. summary:: + Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. + + If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. + + See also `PSA_ENCAPSULATION_OUTPUT_SIZE()`. + diff --git a/doc/crypto/api/ops/index.rst b/doc/crypto/api/ops/index.rst index 903c79cf..d8c1d2e3 100644 --- a/doc/crypto/api/ops/index.rst +++ b/doc/crypto/api/ops/index.rst @@ -19,4 +19,5 @@ Cryptographic operation reference pk-encryption key-agreement pake + encap rng From df06985ff070fc517d8efcda583a6ec1ff44b7b8 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Thu, 3 Oct 2024 12:53:05 +0100 Subject: [PATCH 3/8] Addressing Andrew's comments Removing references to ML-DSA in ML-KEM section Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index b20b2bf1..f965ffaf 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1483,12 +1483,11 @@ SPAKE2+ keys The elliptic curve family id, if ``type`` is a supported SPAKE2+ key. Unspecified if ``type`` is not a supported SPAKE2+ key. -Module Lattice keys -------------------- +Module Lattice-based Key Encapsulation keys +------------------------------------------- -The |API| supports Module Lattice-based digital signatures (ML-DSA), as defined in :cite-title:`FIPS204`. -and Module Lattice-based Key Encapsulation as defined in :cite:`FIPS204`. +The |API| supports Module Lattice-based Key Encapsulation as defined in :cite:`FIPS203`. .. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR :definition: ((psa_key_type_t)0xy001) From b59f16e98061d6202efa064c5332b92010bc659f Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 14 Oct 2024 16:59:51 +0100 Subject: [PATCH 4/8] Answering Andrew's comments Oct 14 Signed-off-by: Marcus Streets --- doc/crypto/api/keys/types.rst | 87 ++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index f965ffaf..46e4e60c 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1489,53 +1489,54 @@ Module Lattice-based Key Encapsulation keys The |API| supports Module Lattice-based Key Encapsulation as defined in :cite:`FIPS203`. -.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR - :definition: ((psa_key_type_t)0xy001) +.. macro:: PSA_KEY_TYPE_ML_KEM_KEY_PAIR + :definition: ((psa_key_type_t)0x7004) .. 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. + ML-KEM key pair: contains both the decapsulation and encapsulation keys. - The size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in FIPS 203. - - The parameter sets refer to the key strength, the actual size of the key - - .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM - :header-rows: 1 - - * - Size - - Parameter Set - - Encapsulation key - - Decapsulation key - - Ciphertext - - * - 512 - - ML-KEM-512 - - 800 - - 1632 - - 768 - - * - 768 - - ML-KEM-768 - - 1184 - - 2400 - - 1088 - - * - 1024 - - ML-KEM-1024 - - 1568 - - 3168 - - 1568 - - In all cases the shared secret produced is 32-bytes, 256-bits long. - The shared secret can be used directly or passed to a PRF to derive further keys. + The |API| treats decapsulation keys as private keys and encapsulation keys as public keys. + + The key attribute size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in :CITE:`FIPS203`. + + The parameter set identifiers refer to the key strength, and not to the actual size of the key, the key and ciphertext sizes are given in the following table. + + .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM + :header-rows: 1 + + * - Key Attribute Size + - Parameter Set + - Encapsulation key + - Decapsulation key + - Ciphertext + + * - 512 + - ML-KEM-512 + - 800 + - 1632 + - 768 + + * - 768 + - ML-KEM-768 + - 1184 + - 2400 + - 1088 + + * - 1024 + - ML-KEM-1024 + - 1568 + - 3168 + - 1568 + + In all cases the shared secret produced is 32-bytes, 256-bits long. + The shared secret can be used directly or passed to a PRF to derive further keys. .. subsection:: Compatible algorithms - | `PSA_ALG_MLKEM` + | `PSA_ALG_ML_KEM` -.. macro:: PSA_KEY_TYPE_ML_KEM _PUBLIC_KEY - :definition: ((psa_key_type_t)0x4001) +.. macro:: PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4004) .. summary:: ML-KEM public key. @@ -1544,9 +1545,9 @@ The |API| supports Module Lattice-based Key Encapsulation as defined in :cite:`F .. subsection:: Compatible algorithms - | `PSA_ALG_MLKEM` (encapsulation only) - | -.. macro:: PSA_KEY_TYPE_IS_MLKEM + | `PSA_ALG_ML_KEM` (encapsulation only) + +.. macro:: PSA_KEY_TYPE_IS_ML_KEM :definition: /* specification-defined value */ .. summary:: From 5b2bfc0a01d8541f962117b920903fd0fb0d4d65 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 14 Oct 2024 17:00:38 +0100 Subject: [PATCH 5/8] Answering Andrew's comments Oct 14 Signed-off-by: Marcus Streets --- doc/crypto/api/ops/encap.rst | 409 +++++++++++++++++++++-------------- 1 file changed, 243 insertions(+), 166 deletions(-) diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst index 6edad69b..ade01e80 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -1,3 +1,11 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. header:: psa/crypto + :seq: 31 + +.. _encapsulation: + Key Encapsulation ================= @@ -5,69 +13,72 @@ A key encapsulation effectively combines an ephemeral asymmetric key exchange, k As the exact details of the key derivation stage depends on the protocol used, the encapsulation and decapsulation functions only perform the asymmetric portion. -Encapsulation takes the counterparties public key, generates a new key pair, and emits the public key. It also creates a raw and an encapsulated seed value. +Encapsulation takes the counterparties public key, generates a new key pair, and emits a raw seed and encapsulated data to transferred to the other participant: + +For ECIES, the data to transfer includes the ephemeral public key and encapsulated seed. +For ML-KEM, the data is a ciphertext of the PKE, conveying a random seed for the shared secret. The raw seed can then be passed to a KDF function to produce the symmetric encryption key or keys. -The public key, encapsulated key and encrypted message can be sent to the counter party. +The encapsulated data and encrypted message can be sent to the counter party. -Decapsulation uses a private half of a key pair, with the public key and encapsulated seed received from the sender and recreated the raw seed. They can then use the same KDF to creates the keys needed to verify and decrypt the message. +Decapsulation uses a private half of a key pair, with the encapsulated data received from the sender and recreated the raw seed. They can then use the same KDF to creates the keys needed to verify and decrypt the message. Elliptic Curve Integrated Encryption Scheme ------------------------------------------- The Elliptic Curve Integrated Encryption Scheme was fist proposed by Shoup, then improved by Ballare and Rogaway. -The original specification permitted a number of variants. This specification only defines the version specified in [SEC1], that is with the use of labels and with the label size defined in bytes. +The original specification permitted a number of variants. This specification only defines the version specified in :cite-title:`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. +While the application can always implement this using the other algorithm functions provided, however, a specific implementation may choose to add these as a convenience with an Implementation-defined algorithm identifier. .. macro:: PSA_ALG_ECIES_SEC1 - :definition: ((psa_algorithm_t)0x09yyyxxxx) +:definition: ((psa_algorithm_t)0x0b000100) + +.. summary:: +The Elliptic Curve Integrated Encryption Scheme. - .. summary:: - The Elliptic Curve Integrated Encryption Scheme. +When used as a key's permitted-algorithm policy, the following uses are permitted: - When used as a key's permitted-algorithm policy, the following uses are permitted: +* In a call to `psa_encapsulate()` or `psa_decapsulate()`. - * In a call to `psa_encapsulate()` or `psa_decapsulate()`. +This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. - This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. - - This uses Cofactor ECDH. +This uses Cofactor ECDH. - .. subsection:: Compatible key types +.. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` +| :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: +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` +* ``PSA_ECC_FAMILY_SECT_XX`` +* ``PSA_ECC_FAMILY_SECP_XX`` +* `PSA_ECC_FAMILY_FRP` +* `PSA_ECC_FAMILY_BRAINPOOL_P_R1` +* `PSA_ECC_FAMILY_MONTGOMERY` Module Lattice Encapsulation ---------------------------- -PSA Crypto supports Module Lattice Encapsulation as defined in :city:`FIPS 203`. +The |API| supports Module Lattice Encapsulation as defined in :cite:`FIPS203`. -.. macro:: PSA_ALG_MLKEM - :definition: ((psa_algorithm_t)0x09yyyxxxx) +.. macro:: PSA_ALG_ML_KEM +:definition: ((psa_algorithm_t)0x0b000200) - .. summary:: - Module Lattice Encapsulation. +.. summary:: +Module Lattice Encapsulation. - When used as a key's permitted-algorithm policy, the following uses are permitted: +When used as a key's permitted-algorithm policy, the following uses are permitted: - * In a call to `psa_encapsulate()` or `psa_decapsulate()`. +* In a call to `psa_encapsulate()` or `psa_decapsulate()`. - .. subsection:: Compatible key types +.. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_MLKEM` +| :code:`PSA_KEY_TYPE_ML-KEM` .. _encapsulation-algorithms: @@ -75,179 +86,245 @@ Encapsulation Algorithms ------------------------ .. function:: psa_encapsulate - .. summary:: - Generate a new key pair and a use that to encapsulate a new secret value, 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. Depending on the protocol, this key may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. +.. summary:: +Generate a new secret value, emitting it both as a key object and as data to send to a counter party. Depending on the protocol, this value may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. + +.. param:: const psa_key_id_t * counterparty_key +The identifier for the public key of the peer. You must have previously imported this key using `psa_import_key()`, and specified the key attributes for the public key type corresponding to the type required for the encapsulation, and the usage usage `PSA_KEY_USAGE_ENCAPSULATE`. + +.. param:: 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 symmetric key. +This function uses the attributes as follows: + +* The key type. + All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Refer to the documentation of individual encapsulation algorithms for more information. + +The following attributes must be set for keys used in cryptographic operations: + +* The key permitted-algorithm policy, see :secref:`permitted-algorithms`. +* The key usage flags, see :secref:`key-usage-flags`. + +The following attributes must be set for keys that do not use the default volatile lifetime: - .. 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`. +* The key lifetime, see :secref:`key-lifetimes`. +* The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. - .. param:: uint8_t * ephemeral_public_key - Buffer where the ephemeral public key key is to be written, ready to be sent to the counterparty. The content of the buffer will be in the same format as `psa_export_key()` for a key of the same type as ``counterparty_key``. - - .. param:: size_t ephemeral_public_key_size - Size of the ``ephemeral_public_key`` buffer in bytes. - This must be at least :code:`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(alg)`. - A buffer of at least :code:`PSA_EXPORT_PUBLIC_KEY_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + The following attributes are optional: - .. 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 . + * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. - .. param:: const psa_key_attributes_t * attributes - The attributes for the new symmetric key. - This function uses the attributes as follows: +.. 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. - * The key type is required. It cannot be an asymmetric public key. - * The key size is required. It must be a valid size for the key type. - * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. - * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. - * The key lifetime and identifier are required for a persistent key. - - .. note:: - This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. - - .. param:: psa_key_id_t * output_key - On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. - - .. param:: uint8_t * encapsulation - Buffer where the encapsulated key is to be written, ready to be sent to the counterparty. - - .. param:: size_t encapsulation_size - Size of the ``encapsulation`` buffer in bytes. - This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. - A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. - - .. param:: size_t * encapsulation_length - On success, the number of bytes that make up the hash value. This is always :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. +.. 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 +Its location, policy, and type are taken from ``attributes``. - .. retval:: PSA_SUCCESS - Success. - The bytes of ``encapsulation`` contain the encapsulated key, the bytes of ``ephemeral_public_key`` contain the public key and ``output_key`` contains the identifier for the key to be used to encrypt the message. +The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. - .. retval:: PSA_ERROR_NOT_SUPPORTED - The following conditions can result in this error: +It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. - * ``alg`` is not supported or is not an encapsulation algorithm. +For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. +Refer to the documentation of individual encapsulation algorithms for more information. - .. retval:: PSA_ERROR_INVALID_ARGUMENT - The following conditions can result in this error: +.. param:: uint8_t * encapsulation +Buffer where the encapsulated data is to be written, ready to be sent to the counterparty. - * ``alg`` is not a encapsulation algorithm. +.. param:: size_t encapsulation_size +Size of the ``encapsulation`` buffer in bytes. +This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. +A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. - .. retval:: PSA_ERROR_BUFFER_TOO_SMALL - The size of the ``encapsulation`` or the ``ephemeral_public_key`` buffer is too small. +.. param:: size_t * encapsulation_length +On success, the number of bytes that make up the encapsulated data value. This is always less then :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. - .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY +.. return:: psa_status_t - .. retval:: PSA_ERROR_COMMUNICATION_FAILURE +.. retval:: PSA_SUCCESS +Success. +The bytes of ``encapsulation`` contain the data to be sent to the counterparty and ``key`` contains the identifier for the key to be used to encrypt the message. - .. retval:: PSA_ERROR_CORRUPTION_DETECTED +.. retval:: PSA_ERROR_NOT_SUPPORTED +The following conditions can result in this error: - .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to `psa_crypto_init()`. +* ``alg`` is not supported or is not an encapsulation algorithm. +* ``counterparty_key`` is not compatible with ``alg`` +* The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. +.. retval:: PSA_ERROR_INVALID_ARGUMENT +The following conditions can result in this error: + +* ``alg`` is not a encapsulation algorithm. +* ``counterparty_key`` is not a valid public key +* ``counterparty_key`` is not compatible with ``alg`` +* The output key attributes in ``attributes`` are not valid : + - The key type is not valid for key agreement output. + - The key size is nonzero, and is not the size of the shared secret. + - The key lifetime is invalid. + - The key identifier is not valid for the key lifetime. + - The key usage flags include invalid values. + - The key's permitted-usage algorithm is invalid. + - The key attributes, as a whole, are invalid. + +.. retval:: PSA_ERROR_BUFFER_TOO_SMALL +The size of the ``encapsulation`` buffer is too small. + +.. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + +.. retval:: PSA_ERROR_COMMUNICATION_FAILURE + +.. retval:: PSA_ERROR_CORRUPTION_DETECTED + +.. retval:: PSA_ERROR_BAD_STATE +The library requires initializing by a call to `psa_crypto_init()`. .. function:: psa_decapsulate - .. summary:: - Uses a private key to decapsulate an encapsulated key received from a counter party. Depending on the protocol, this key may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. - - .. param:: const psa_key_id_t * peer_key - Public key of the peer. The peer key must be in the same format that `psa_import_key()` accepts for the public key type corresponding to the type of ``private_key``. That is, this function performs the equivalent of :code:`psa_import_key(..., peer_key, peer_key_length)`, with key attributes indicating the public key type corresponding to the type of ``private_key``. For example, for ECC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of `psa_export_public_key()`. - - .. param:: size_t peer_key_length - Size of the ``encapsulation`` buffer in bytes. - - .. param:: const psa_key_id_t * private_key - Identifier of the key belonging to the person receiving the encapsulated message. - It must be an asymmetric key pair. - The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` - - .. param:: conts uint8_t * encapsulation - Buffer containing the encapsulated key that was received from the counterparty. - - .. param:: size_t encapsulation_size - Size of the ``encapsulation`` buffer in bytes. - - .. param:: psa_algorithm_t alg - The encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. - - .. param:: const psa_key_attributes_t * attributes - The attributes for the new key. - This function uses the attributes as follows: - - * The key type is required. It cannot be an asymmetric public key. - * The key size is required. It must be a valid size for the key type. - * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`. - * The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`. - * The key lifetime and identifier are required for a persistent key. - - .. note:: - This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. - - .. param:: psa_key_id_t * output_key - On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. - - .. return:: psa_status_t - .. retval:: PSA_SUCCESS - Success. - - .. retval:: PSA_ERROR_NOT_SUPPORTED - The following conditions can result in this error: - - * ``alg`` is not supported or is not an encapsulation algorithm. - - .. retval:: PSA_ERROR_INVALID_ARGUMENT - The following conditions can result in this error: - - * ``alg`` is not supported or is not an encapsulation algorithm. - - .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY - .. retval:: PSA_ERROR_COMMUNICATION_FAILURE - .. retval:: PSA_ERROR_CORRUPTION_DETECTED - .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to `psa_crypto_init()`. +.. summary:: +Uses a private key to decapsulate a shared secret from encapsulated data received from a counter party. Depending on the protocol, this secret may be used suitabkle to be used directly, or may need to be passed to a KDF to derive encryption and authentication keys. + +.. param:: conts uint8_t * encapsulation +Buffer containing the encapsulation that was received from the counterparty. + +.. param:: size_t encapsulation_length +Size of the ``encapsulation`` buffer in bytes. + +.. param:: const psa_key_id_t key +Identifier of the key belonging to the person receiving the encapsulated message. +It must be an asymmetric key pair. +The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` + +.. param:: 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 symmetric key. +This function uses the attributes as follows: + +* The key type. + All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Refer to the documentation of individual encapsulation algorithms for more information. + +The following attributes must be set for keys used in cryptographic operations: + +* The key permitted-algorithm policy, see :secref:`permitted-algorithms`. +* The key usage flags, see :secref:`key-usage-flags`. + +The following attributes must be set for keys that do not use the default volatile lifetime: + +* The key lifetime, see :secref:`key-lifetimes`. +* The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. + + The following attributes are optional: + + * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. + +.. 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. + +Its location, policy, and type are taken from ``attributes``. + +The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. + +It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. + +For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. +Refer to the documentation of individual encapsulation algorithms for more information. + +* The output is not verified. Key confirmation can be done to verify that both parties have the same key. +* The appropriate steps to take are defined by the higher level protocol that is using the encapsulation method. + +.. return:: psa_status_t +.. retval:: PSA_SUCCESS +Success. +``output_key`` contains the identifier for the shared secret. Depending on the protocol, this value may be used directly to decrypt the message, or may need to be passed to a KDF to derive decryption and authentication keys. + +In some algorithms, decapsulation failure cannot be detected, and simply results in incorrect output. Such failures will return `PSA_SUCCESS`. + +.. retval:: PSA_ERROR_NOT_SUPPORTED +The following conditions can result in this error: + +The following conditions can result in this error: + +* ``alg`` is not supported or is not an encapsulation algorithm. +* ``counterparty_key`` is not compatible with ``alg`` +* The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. +.. retval:: PSA_ERROR_INVALID_ARGUMENT +The following conditions can result in this error: + +* ``alg`` is not a encapsulation algorithm. +* ``counterparty_key`` is not a valid public key +* ``counterparty_key`` is not compatible with ``alg`` +* The output key attributes in ``attributes`` are not valid : + - The key type is not valid for key agreement output. + - The key size is nonzero, and is not the size of the shared secret. + - The key lifetime is invalid. + - The key identifier is not valid for the key lifetime. + - The key usage flags include invalid values. + - The key's permitted-usage algorithm is invalid. + - The key attributes, as a whole, are invalid. +* ``encapsulation`` is not obviously valid for the selected algorithm, for example, the implementation can detect that it is the incorrect length. Or, for ECIES, the public key is not a valid point on the curve. + +.. 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_IS_ENCAPSULATION - :definition: /* specification-defined value */ +:definition: /* specification-defined value */ - .. summary:: - Whether the specified algorithm is a full encapsulation algorithm. +.. summary:: +Whether the specified algorithm is a full encapsulation algorithm. - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. +.. 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. +.. 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. .. macro:: PSA_ENCAPSULATION_OUTPUT_SIZE - :definition: /* implementation-defined value */ +:definition: /* implementation-defined value */ + +.. summary:: +Sufficient output buffer size for `psa_encapsulate()` for the given algorithm and key. + +.. param:: key_type +A supported key type. - .. summary:: - Sufficient output buffer size for `psa_encapsulate()`. +.. param:: key_bits +The size of the key in bits. - .. param:: key_type - A supported key type. - .. param:: key_bits - The size of the key in bits. +.. param:: alg + An encapsulation algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. - .. 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. +.. return:: +A sufficient output buffer size for the specified key type and size. An implementation can return either ``0`` or a correct size for an algorithm, key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. - If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. +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`. +See also `PSA_ENCAPSULATION_OUTPUT_MAX_SIZE`. .. macro:: PSA_ENCAPSULATION_OUTPUT_MAX_SIZE - :definition: /* implementation-defined value */ +:definition: /* implementation-defined value */ - .. summary:: - Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. +.. summary:: +Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. - If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. +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()`. +See also `PSA_ENCAPSULATION_OUTPUT_SIZE()`. From 109b81aed886a52449f18cb87499a32854c8c984 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Mon, 14 Oct 2024 17:01:29 +0100 Subject: [PATCH 6/8] Answering Andrew's comments Oct 14 Still need to add new figure (and its licence file) Signed-off-by: Marcus Streets --- doc/crypto/appendix/encodings.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index a1784f9a..d679c551 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -84,6 +84,7 @@ The CAT field in an algorithm identifier takes the values shown in :numref:`tabl Asymmetric encryption, ``0x07``, See :secref:`pke-encoding` Key agreement, ``0x09``, See :secref:`ka-encoding` PAKE, ``0x0A``, See :secref:`pake-encoding` + Encapsulation, ``0x0B``, See :secref:`encapsulation-encoding` .. rationale:: @@ -416,6 +417,30 @@ The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key derivation algorithm. +.. _encapsulation-encoding: + +Encapsulation algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~ + +The algorithm identifier for encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-encapsulation-encoding`. + +.. figure:: /figure/encoding/encapsulation_encoding.* + :name: fig-encapsulation-encoding + + Encapsulation algorithm encoding + +The defined values for ENCAPSULATION-TYPE are shown in :numref:`table-encapsulation-type`. + +.. csv-table:: Encapsulation algorithm sub-type values + :name: table-encapsulation-type + :header-rows: 1 + :align: left + :widths: auto + + encapsulation algorithm, Algorithm identifier, Algorithm value + ECIES, ``0x01``, ``0x0b000100`` + ML-KEM, ``0x02``, ``0x0b000200`` + .. _key-type-encoding: Key type encoding From 5ce3f11a146c764b26c5c7bec6032b480e83553c Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 16 Oct 2024 14:34:43 +0100 Subject: [PATCH 7/8] Fixing indents Signed-off-by: Marcus Streets --- doc/crypto/api/ops/encap.rst | 375 ++++++++++++++++++----------------- 1 file changed, 191 insertions(+), 184 deletions(-) diff --git a/doc/crypto/api/ops/encap.rst b/doc/crypto/api/ops/encap.rst index ade01e80..9bf40573 100644 --- a/doc/crypto/api/ops/encap.rst +++ b/doc/crypto/api/ops/encap.rst @@ -36,30 +36,30 @@ It is possible that some applications may need to use older versions to interope While the application can always implement this using the other algorithm functions provided, however, a specific implementation may choose to add these as a convenience with an Implementation-defined algorithm identifier. .. macro:: PSA_ALG_ECIES_SEC1 -:definition: ((psa_algorithm_t)0x0b000100) + :definition: ((psa_algorithm_t)0x0b000100) -.. summary:: -The Elliptic Curve Integrated Encryption Scheme. + .. summary:: + The Elliptic Curve Integrated Encryption Scheme. -When used as a key's permitted-algorithm policy, the following uses are permitted: + When used as a key's permitted-algorithm policy, the following uses are permitted: -* In a call to `psa_encapsulate()` or `psa_decapsulate()`. + * In a call to `psa_encapsulate()` or `psa_decapsulate()`. -This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. + This encapsulation scheme is defined by :cite-title:`SEC1` §5.5.1 under the name Elliptic Curve Integrated Encryption Scheme. -This uses Cofactor ECDH. + This uses Cofactor ECDH. -.. subsection:: Compatible key types + .. subsection:: Compatible key types -| :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` + | :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: + 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` + * ``PSA_ECC_FAMILY_SECT_XX`` + * ``PSA_ECC_FAMILY_SECP_XX`` + * `PSA_ECC_FAMILY_FRP` + * `PSA_ECC_FAMILY_BRAINPOOL_P_R1` + * `PSA_ECC_FAMILY_MONTGOMERY` Module Lattice Encapsulation ---------------------------- @@ -67,18 +67,18 @@ Module Lattice Encapsulation The |API| supports Module Lattice Encapsulation as defined in :cite:`FIPS203`. .. macro:: PSA_ALG_ML_KEM -:definition: ((psa_algorithm_t)0x0b000200) + :definition: ((psa_algorithm_t)0x0b000200) -.. summary:: -Module Lattice Encapsulation. + .. summary:: + Module Lattice Encapsulation. -When used as a key's permitted-algorithm policy, the following uses are permitted: + When used as a key's permitted-algorithm policy, the following uses are permitted: -* In a call to `psa_encapsulate()` or `psa_decapsulate()`. + * In a call to `psa_encapsulate()` or `psa_decapsulate()`. -.. subsection:: Compatible key types - -| :code:`PSA_KEY_TYPE_ML-KEM` + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML-KEM` .. _encapsulation-algorithms: @@ -86,245 +86,252 @@ Encapsulation Algorithms ------------------------ .. function:: psa_encapsulate -.. summary:: -Generate a new secret value, emitting it both as a key object and as data to send to a counter party. Depending on the protocol, this value may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. - -.. 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`. + .. summary:: + Generate a new secret value, emitting it both as a key object and as data to send to a counter party. Depending on the protocol, this value may be used directly or may need to be passed to a KDF to derive encryption and authentication keys. -.. 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:: psa_key_id_t key + The identifier for the public key of the peer. You must have previously imported this key using `psa_import_key()`, and specified the key attributes for the public key type corresponding to the type required for the encapsulation, and the usage usage `PSA_KEY_USAGE_ENCAPSULATE`. -.. param:: const psa_key_attributes_t * attributes -The attributes for the new symmetric key. -This function uses the attributes as follows: + .. 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. -* The key type. - All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. - encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. - Refer to the documentation of individual encapsulation algorithms for more information. + .. param:: const psa_key_attributes_t * attributes + The attributes for the new symmetric key. + This function uses the attributes as follows: -The following attributes must be set for keys used in cryptographic operations: + * The key type. + All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Refer to the documentation of individual encapsulation algorithms for more information. -* The key permitted-algorithm policy, see :secref:`permitted-algorithms`. -* The key usage flags, see :secref:`key-usage-flags`. + The following attributes must be set for keys used in cryptographic operations: -The following attributes must be set for keys that do not use the default volatile lifetime: + * The key permitted-algorithm policy, see :secref:`permitted-algorithms`. + * The key usage flags, see :secref:`key-usage-flags`. -* The key lifetime, see :secref:`key-lifetimes`. -* The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. + The following attributes must be set for keys that do not use the default volatile lifetime: - The following attributes are optional: + * The key lifetime, see :secref:`key-lifetimes`. + * The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. - * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. + The following attributes are optional: -.. 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. + * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. -.. param:: psa_key_id_t output_key -On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + .. 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. -Its location, policy, and type are taken from ``attributes``. + .. param:: psa_key_id_t *output_key + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. -The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. + .. param:: uint8_t * encapsulation + Buffer where the encapsulated data is to be written, ready to be sent to the counterparty. -It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. -For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. -Refer to the documentation of individual encapsulation algorithms for more information. + .. param:: size_t * encapsulation_length + On success, the number of bytes that make up the encapsulated data value. This is always less then :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. -.. param:: uint8_t * encapsulation -Buffer where the encapsulated data is to be written, ready to be sent to the counterparty. + .. return:: psa_status_t -.. param:: size_t encapsulation_size -Size of the ``encapsulation`` buffer in bytes. -This must be at least :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. -A buffer of at least :code:`PSA_ENCAPSULATION_MAX_OUTPUT_SIZE`. is guaranteed not to fail due to buffer size for any supported encapsulation algorithm. + .. retval:: PSA_SUCCESS + Success. + The bytes of ``encapsulation`` contain the data to be sent to the counterparty and ``key`` contains the identifier for the key to be used to encrypt the message. -.. param:: size_t * encapsulation_length -On success, the number of bytes that make up the encapsulated data value. This is always less then :code:`PSA_ENCAPSULATION_OUTPUT_SIZE(alg)`. + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: -.. return:: psa_status_t + * ``alg`` is not supported or is not an encapsulation algorithm. + * ``counterparty_key`` is not compatible with ``alg`` + * The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. + + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: -.. retval:: PSA_SUCCESS -Success. -The bytes of ``encapsulation`` contain the data to be sent to the counterparty and ``key`` contains the identifier for the key to be used to encrypt the message. + * ``alg`` is not a encapsulation algorithm. + * ``counterparty_key`` is not a valid public key + * ``counterparty_key`` is not compatible with ``alg`` + * The output key attributes in ``attributes`` are not valid : + - The key type is not valid for key agreement output. + - The key size is nonzero, and is not the size of the shared secret. + - The key lifetime is invalid. + - The key identifier is not valid for the key lifetime. + - The key usage flags include invalid values. + - The key's permitted-usage algorithm is invalid. + - The key attributes, as a whole, are invalid. -.. retval:: PSA_ERROR_NOT_SUPPORTED -The following conditions can result in this error: + .. retval:: PSA_ERROR_BUFFER_TOO_SMALL + The size of the ``encapsulation`` buffer is too small. -* ``alg`` is not supported or is not an encapsulation algorithm. -* ``counterparty_key`` is not compatible with ``alg`` -* The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. -.. retval:: PSA_ERROR_INVALID_ARGUMENT -The following conditions can result in this error: + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY -* ``alg`` is not a encapsulation algorithm. -* ``counterparty_key`` is not a valid public key -* ``counterparty_key`` is not compatible with ``alg`` -* The output key attributes in ``attributes`` are not valid : - - The key type is not valid for key agreement output. - - The key size is nonzero, and is not the size of the shared secret. - - The key lifetime is invalid. - - The key identifier is not valid for the key lifetime. - - The key usage flags include invalid values. - - The key's permitted-usage algorithm is invalid. - - The key attributes, as a whole, are invalid. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE -.. retval:: PSA_ERROR_BUFFER_TOO_SMALL -The size of the ``encapsulation`` buffer is too small. + .. retval:: PSA_ERROR_CORRUPTION_DETECTED -.. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_BAD_STATE + The library requires initializing by a call to `psa_crypto_init()`. -.. retval:: PSA_ERROR_COMMUNICATION_FAILURE + The ``output_key`` location, policy, and type are taken from ``attributes``. + + The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. -.. retval:: PSA_ERROR_CORRUPTION_DETECTED + It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. -.. retval:: PSA_ERROR_BAD_STATE -The library requires initializing by a call to `psa_crypto_init()`. + For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. + + The ``encapsulation`` should be sent to the counterparty with the encrypted message to permit decapsulation. + + Refer to the documentation of individual encapsulation algorithms for more information. .. function:: psa_decapsulate -.. summary:: -Uses a private key to decapsulate a shared secret from encapsulated data received from a counter party. Depending on the protocol, this secret may be used suitabkle to be used directly, or may need to be passed to a KDF to derive encryption and authentication keys. + .. summary:: + Uses a private key to decapsulate a shared secret from encapsulated data received from a counter party. Depending on the protocol, this secret may be suitable to be used directly, or may need to be passed to a KDF to derive encryption and authentication keys. + + .. param:: psa_key_id_t key + Identifier of the key belonging to the person receiving the encapsulated message. + It must be an asymmetric key pair. + The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` + + .. param:: 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:: conts uint8_t * encapsulation + Buffer containing the encapsulation that was received from the counterparty. -.. param:: conts uint8_t * encapsulation -Buffer containing the encapsulation that was received from the counterparty. + .. param:: size_t encapsulation_length + Size of the ``encapsulation`` buffer in bytes. -.. param:: size_t encapsulation_length -Size of the ``encapsulation`` buffer in bytes. + .. param:: const psa_key_attributes_t * attributes + The attributes for the new symmetric key. + This function uses the attributes as follows: -.. param:: const psa_key_id_t key -Identifier of the key belonging to the person receiving the encapsulated message. -It must be an asymmetric key pair. -The private half of the key pair must permit the usage `PSA_KEY_USAGE_DECAPSULATE` + * The key type. + All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Refer to the documentation of individual encapsulation algorithms for more information. -.. 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. + The following attributes must be set for keys used in cryptographic operations: -.. param:: const psa_key_attributes_t * attributes -The attributes for the new symmetric key. -This function uses the attributes as follows: + * The key permitted-algorithm policy, see :secref:`permitted-algorithms`. + * The key usage flags, see :secref:`key-usage-flags`. -* The key type. - All encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. - encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. - Refer to the documentation of individual encapsulation algorithms for more information. + The following attributes must be set for keys that do not use the default volatile lifetime: -The following attributes must be set for keys used in cryptographic operations: + * The key lifetime, see :secref:`key-lifetimes`. + * The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. -* The key permitted-algorithm policy, see :secref:`permitted-algorithms`. -* The key usage flags, see :secref:`key-usage-flags`. + The following attributes are optional: -The following attributes must be set for keys that do not use the default volatile lifetime: + * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. -* The key lifetime, see :secref:`key-lifetimes`. -* The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`. + .. 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. - The following attributes are optional: + .. param:: psa_key_id_t * output_key - * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. -.. 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. + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``output_key`` contains the identifier for the shared secret. Depending on the protocol, this value may be used directly to decrypt the message, or may need to be passed to a KDF to derive decryption and authentication keys. -.. param:: psa_key_id_t * output_key + In some algorithms, decapsulation failure cannot be detected, and simply results in incorrect output. Such failures will return `PSA_SUCCESS`. -On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: -Its location, policy, and type are taken from ``attributes``. + The following conditions can result in this error: -The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. + * ``alg`` is not supported or is not an encapsulation algorithm. -It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. + * ``counterparty_key`` is not compatible with ``alg`` -For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. -Refer to the documentation of individual encapsulation algorithms for more information. + * The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. -* The output is not verified. Key confirmation can be done to verify that both parties have the same key. -* The appropriate steps to take are defined by the higher level protocol that is using the encapsulation method. + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: -.. return:: psa_status_t -.. retval:: PSA_SUCCESS -Success. -``output_key`` contains the identifier for the shared secret. Depending on the protocol, this value may be used directly to decrypt the message, or may need to be passed to a KDF to derive decryption and authentication keys. + * ``alg`` is not a encapsulation algorithm. + * ``key`` is not a valid public key + * ``key`` is not compatible with ``alg`` + * The output key attributes in ``attributes`` are not valid : + - The key type is not valid for key agreement output. + - The key size is nonzero, and is not the size of the shared secret. + - The key lifetime is invalid. + - The key identifier is not valid for the key lifetime. + - The key usage flags include invalid values. + - The key's permitted-usage algorithm is invalid. + - The key attributes, as a whole, are invalid. + * ``encapsulation`` is not obviously valid for the selected algorithm, for example, the implementation can detect that it is the incorrect length. Or, for ECIES, the public key is not a valid point on the curve. -In some algorithms, decapsulation failure cannot be detected, and simply results in incorrect output. Such failures will return `PSA_SUCCESS`. + .. 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()`. -.. retval:: PSA_ERROR_NOT_SUPPORTED -The following conditions can result in this error: + The ``output_key`` location, policy, and type are taken from ``attributes``. -The following conditions can result in this error: + The size of ``output_key`` is always the bit-size of the shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the encapsulation algorithm and cipher suite. -* ``alg`` is not supported or is not an encapsulation algorithm. -* ``counterparty_key`` is not compatible with ``alg`` -* The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. -.. retval:: PSA_ERROR_INVALID_ARGUMENT -The following conditions can result in this error: + It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. -* ``alg`` is not a encapsulation algorithm. -* ``counterparty_key`` is not a valid public key -* ``counterparty_key`` is not compatible with ``alg`` -* The output key attributes in ``attributes`` are not valid : - - The key type is not valid for key agreement output. - - The key size is nonzero, and is not the size of the shared secret. - - The key lifetime is invalid. - - The key identifier is not valid for the key lifetime. - - The key usage flags include invalid values. - - The key's permitted-usage algorithm is invalid. - - The key attributes, as a whole, are invalid. -* ``encapsulation`` is not obviously valid for the selected algorithm, for example, the implementation can detect that it is the incorrect length. Or, for ECIES, the public key is not a valid point on the curve. + For some encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. + Refer to the documentation of individual encapsulation algorithms for more information. -.. 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()`. + * The output is not verified. Key confirmation can be done to verify that both parties have the same key. + * The appropriate steps to take are defined by the higher level protocol that is using the encapsulation method. Support macros -------------- .. macro:: PSA_ALG_IS_ENCAPSULATION -:definition: /* specification-defined value */ + :definition: /* specification-defined value */ -.. summary:: -Whether the specified algorithm is a full encapsulation algorithm. + .. summary:: + Whether the specified algorithm is a full encapsulation algorithm. -.. param:: alg -An algorithm identifier: a value of type `psa_algorithm_t`. + .. 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. + .. 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. .. macro:: PSA_ENCAPSULATION_OUTPUT_SIZE -:definition: /* implementation-defined value */ + :definition: /* implementation-defined value */ -.. summary:: -Sufficient output buffer size for `psa_encapsulate()` for the given algorithm and key. + .. summary:: + Sufficient output buffer size for `psa_encapsulate()` for the given algorithm and key. -.. param:: key_type -A supported key type. + .. param:: key_type + A supported key type. -.. param:: key_bits -The size of the key in bits. + .. param:: key_bits + The size of the key in bits. -.. param:: alg - An encapsulation algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + .. param:: alg + An encapsulation algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. -.. return:: -A sufficient output buffer size for the specified key type and size. An implementation can return either ``0`` or a correct size for an algorithm, key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. + .. return:: + A sufficient output buffer size for the specified key type and size. An implementation can return either ``0`` or a correct size for an algorithm, key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. -If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. + 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`. + See also `PSA_ENCAPSULATION_OUTPUT_MAX_SIZE`. .. macro:: PSA_ENCAPSULATION_OUTPUT_MAX_SIZE -:definition: /* implementation-defined value */ + :definition: /* implementation-defined value */ -.. summary:: -Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. + .. summary:: + Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and encapsulation algorithms. -If the size of the output buffer is at least this large, it is guaranteed that `psa_encapsulate()` will not fail due to an insufficient buffer size. + 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()`. + See also `PSA_ENCAPSULATION_OUTPUT_SIZE()`. From 4291c5ef7ef7f78dfd5ab339eecc52c3cb318348 Mon Sep 17 00:00:00 2001 From: Marcus Streets Date: Wed, 16 Oct 2024 14:35:32 +0100 Subject: [PATCH 8/8] Add key encoding Signed-off-by: Marcus Streets --- doc/crypto/appendix/encodings.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index d679c551..d78f096b 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -420,7 +420,7 @@ a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct .. _encapsulation-encoding: Encapsulation algorithm encoding -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The algorithm identifier for encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-encapsulation-encoding`. @@ -429,7 +429,7 @@ The algorithm identifier for encapsulation algorithms defined in this specificat Encapsulation algorithm encoding -The defined values for ENCAPSULATION-TYPE are shown in :numref:`table-encapsulation-type`. +The defined values for ENCAPS-TYPE are shown in :numref:`table-encapsulation-type`. .. csv-table:: Encapsulation algorithm sub-type values :name: table-encapsulation-type @@ -437,9 +437,9 @@ The defined values for ENCAPSULATION-TYPE are shown in :numref:`table-encapsulat :align: left :widths: auto - encapsulation algorithm, Algorithm identifier, Algorithm value - ECIES, ``0x01``, ``0x0b000100`` - ML-KEM, ``0x02``, ``0x0b000200`` + Encapsulation algorithm, ENCAPS-TYPE, Algorithm identifier, Algorithm value + ECIES, ``0x01``, `PSA_ALG_ECIES_SEC1`, ``0x0b000100`` + ML-KEM, ``0x02``, `PSA_ALG_ML_KEM`, ``0x0b000200`` .. _key-type-encoding: @@ -622,7 +622,9 @@ The defined values for NP-FAMILY and P are shown in :numref:`table-np-type`. Key family, Public/pair, PAIR, NP-FAMILY, P, Key type, Key value RSA, Public key, 0, 0, 1, `PSA_KEY_TYPE_RSA_PUBLIC_KEY`, ``0x4001`` , Key pair, 3, 0, 1, `PSA_KEY_TYPE_RSA_KEY_PAIR`, ``0x7001`` - + ML-KEM, Public key, 0, 2, 0, `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY`, ``0x4004`` + , Key pair, 3, 2, 0, `PSA_KEY_TYPE_ML_KEM_KEY_PAIR`, ``0x7004`` + .. _ecc-key-encoding: Elliptic curve key encoding