From 43bdb839ee9bb8e2702b5185259782e7b54a80f7 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 21 Oct 2024 23:15:23 +0100 Subject: [PATCH 01/19] Addition of key encapsulation API Also provide ECIES algorithm. --- doc/crypto/api.db/psa/crypto.h | 20 ++ doc/crypto/api/keys/attributes.rst | 2 +- doc/crypto/api/keys/ids.rst | 2 +- doc/crypto/api/keys/lifetimes.rst | 2 +- doc/crypto/api/keys/management.rst | 1 + doc/crypto/api/keys/policy.rst | 40 ++- doc/crypto/api/keys/types.rst | 21 +- doc/crypto/api/ops/algorithms.rst | 15 + doc/crypto/api/ops/index.rst | 1 + doc/crypto/api/ops/key-encapsulation.rst | 331 ++++++++++++++++++ doc/crypto/api/ops/rng.rst | 2 +- doc/crypto/appendix/encodings.rst | 24 ++ doc/crypto/appendix/history.rst | 4 + doc/crypto/appendix/specdef_values.rst | 3 + doc/crypto/figure/encoding/kem_encoding.json | 18 + .../figure/encoding/kem_encoding.json.license | 2 + doc/crypto/figure/encoding/kem_encoding.pdf | Bin 0 -> 8159 bytes .../figure/encoding/kem_encoding.pdf.license | 2 + doc/crypto/figure/encoding/kem_encoding.svg | 2 + .../figure/encoding/kem_encoding.svg.license | 2 + doc/crypto/overview/functionality.rst | 5 + 21 files changed, 489 insertions(+), 10 deletions(-) create mode 100644 doc/crypto/api/ops/key-encapsulation.rst create mode 100644 doc/crypto/figure/encoding/kem_encoding.json create mode 100644 doc/crypto/figure/encoding/kem_encoding.json.license create mode 100644 doc/crypto/figure/encoding/kem_encoding.pdf create mode 100644 doc/crypto/figure/encoding/kem_encoding.pdf.license create mode 100644 doc/crypto/figure/encoding/kem_encoding.svg create mode 100644 doc/crypto/figure/encoding/kem_encoding.svg.license diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 8cc8cf5c..2f11a93e 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -76,6 +76,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_ECDH ((psa_algorithm_t)0x09020000) #define PSA_ALG_ECDSA(hash_alg) /* specification-defined value */ #define PSA_ALG_ECDSA_ANY ((psa_algorithm_t) 0x06000600) +#define PSA_ALG_ECIES_SEC1 ((psa_algorithm_t)0x0b000100) #define PSA_ALG_ED25519PH ((psa_algorithm_t) 0x0600090B) #define PSA_ALG_ED448PH ((psa_algorithm_t) 0x06000915) #define PSA_ALG_FFDH ((psa_algorithm_t)0x09010000) @@ -94,6 +95,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */ #define PSA_ALG_IS_ECDH(alg) /* specification-defined value */ #define PSA_ALG_IS_ECDSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_ENCAPSULATION(alg) /* specification-defined value */ #define PSA_ALG_IS_FFDH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH_AND_SIGN(alg) /* specification-defined value */ @@ -221,6 +223,9 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22) #define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b) #define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42) +#define PSA_ENCAPSULATION_MAX_SIZE /* implementation-defined value */ +#define PSA_ENCAPSULATION_SIZE(key_type, key_bits, alg) \ + /* implementation-defined value */ #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148) #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150) #define PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE /* implementation-defined value */ @@ -324,8 +329,10 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007) #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) +#define PSA_KEY_USAGE_DECAPSULATE ((psa_key_usage_t)0x00020000) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) +#define PSA_KEY_USAGE_ENCAPSULATE ((psa_key_usage_t)0x00010000) #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) @@ -498,7 +505,20 @@ psa_status_t psa_copy_key(psa_key_id_t source_key, const psa_key_attributes_t * attributes, psa_key_id_t * target_key); psa_status_t psa_crypto_init(void); +psa_status_t psa_decapsulate(psa_key_id_t key, + psa_algorithm_t alg, + conts uint8_t * encapsulation, + size_t encapsulation_length, + const psa_key_attributes_t * attributes, + psa_key_id_t * output_key); psa_status_t psa_destroy_key(psa_key_id_t key); +psa_status_t psa_encapsulate(psa_key_id_t key, + psa_algorithm_t alg, + const psa_key_attributes_t * attributes, + psa_key_id_t * output_key, + uint8_t * encapsulation, + size_t encapsulation_size, + size_t * encapsulation_length); psa_status_t psa_export_key(psa_key_id_t key, uint8_t * data, size_t data_size, diff --git a/doc/crypto/api/keys/attributes.rst b/doc/crypto/api/keys/attributes.rst index 71a00fc8..63691dc5 100644 --- a/doc/crypto/api/keys/attributes.rst +++ b/doc/crypto/api/keys/attributes.rst @@ -112,7 +112,7 @@ Managing key attributes #. Set the key policy with `psa_set_key_usage_flags()` and `psa_set_key_algorithm()`. #. Set the key type with `psa_set_key_type()`. Skip this step if copying an existing key with `psa_copy_key()`. #. When generating a random key with `psa_generate_key()` or `psa_generate_key_custom()`, or deriving a key with `psa_key_derivation_output_key()` or `psa_key_derivation_output_key_custom()`, set the desired key size with `psa_set_key_bits()`. - #. Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key. + #. Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_encapsulate()`, `psa_decapsulate()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key. #. Optionally call `psa_reset_key_attributes()`, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself. A typical sequence to query a key's attributes is as follows: diff --git a/doc/crypto/api/keys/ids.rst b/doc/crypto/api/keys/ids.rst index ed537b90..e5a586fa 100644 --- a/doc/crypto/api/keys/ids.rst +++ b/doc/crypto/api/keys/ids.rst @@ -92,7 +92,7 @@ Attribute accessors If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to `PSA_KEY_LIFETIME_PERSISTENT`. - This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. + This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_encapsulate()`, `psa_decapsulate()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. .. admonition:: Implementation note diff --git a/doc/crypto/api/keys/lifetimes.rst b/doc/crypto/api/keys/lifetimes.rst index 300a5cb3..21bc7656 100644 --- a/doc/crypto/api/keys/lifetimes.rst +++ b/doc/crypto/api/keys/lifetimes.rst @@ -273,7 +273,7 @@ Attribute accessors To make a key persistent, give it a persistent key identifier by using `psa_set_key_id()`. By default, a key that has a persistent identifier is stored in the default storage area identifier by `PSA_KEY_LIFETIME_PERSISTENT`. Call this function to choose a storage area, or to explicitly declare the key as volatile. - This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. + This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_encapsulate()`, `psa_decapsulate()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. .. admonition:: Implementation note diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index b6a7391c..abf7fb39 100644 --- a/doc/crypto/api/keys/management.rst +++ b/doc/crypto/api/keys/management.rst @@ -18,6 +18,7 @@ New keys can be created in the following ways: * `psa_generate_key()` and `psa_generate_key_custom()` create a key from randomly generated data. * `psa_key_derivation_output_key()` and `psa_key_derivation_output_key_custom()` create a key from data generated by a pseudorandom derivation process. See :secref:`kdf`. * `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`. +* `psa_encapsulate()` and `psa_decapsulate()` create a shared secret key using a key encapsulation mechanism. * `psa_pake_get_shared_key()` creates a key from the shared secret result of a password-authenticated key exchange. See :secref:`pake`. * `psa_copy_key()` duplicates an existing key with a different lifetime or with a more restrictive usage policy. diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 40b56db2..15a8281a 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 @@ -86,7 +86,18 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. * The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key material can be extracted from the cryptoprocessor, or copied outside of its current security boundary. * The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy. * The cacheable flag `PSA_KEY_USAGE_CACHE` determines whether the implementation is permitted to retain non-essential copies of the key material in RAM. This policy only applies to persistent keys. See also :secref:`key-material`. -* The other usage flags, for example, `PSA_KEY_USAGE_ENCRYPT` and `PSA_KEY_USAGE_SIGN_MESSAGE`, determine whether the corresponding operation is permitted on the key. +* The following usage flags determine whether the corresponding operations are permitted with the key: + + - `PSA_KEY_USAGE_ENCRYPT` + - `PSA_KEY_USAGE_DECRYPT` + - `PSA_KEY_USAGE_SIGN_MESSAGE` + - `PSA_KEY_USAGE_VERIFY_MESSAGE` + - `PSA_KEY_USAGE_SIGN_HASH` + - `PSA_KEY_USAGE_VERIFY_HASH` + - `PSA_KEY_USAGE_DERIVE` + - `PSA_KEY_USAGE_VERIFY_DERIVATION` + - `PSA_KEY_USAGE_ENCAPSULATE` + - `PSA_KEY_USAGE_DECAPSULATE` .. typedef:: uint32_t psa_key_usage_t @@ -254,6 +265,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 the data 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..894c4a95 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -797,7 +797,7 @@ The curve type affects the key format, the key derivation procedure, and the alg * - Curve type - Compatible algorithms * - Weierstrass - - Weierstrass curve key-pairs can be used in asymmetric signature and key agreement algorithms. + - Weierstrass curve key-pairs can be used in asymmetric signature, key agreement, and key encapsulation algorithms. `PSA_ALG_DETERMINISTIC_ECDSA` @@ -806,10 +806,16 @@ The curve type affects the key format, the key derivation procedure, and the alg `PSA_ALG_ECDSA_ANY` `PSA_ALG_ECDH` + + `PSA_ALG_ECIES_SEC1` + * - Montgomery - - Montgomery curve key-pairs can only be used in key agreement algorithms. + - Montgomery curve key-pairs can be used in key agreement and key encapsulation algorithms. `PSA_ALG_ECDH` + + `PSA_ALG_ECIES_SEC1` + * - Twisted Edwards - Twisted Edwards curve key-pairs can only be used in asymmetric signature algorithms. @@ -920,7 +926,7 @@ The curve type affects the key format, the key derivation procedure, and the alg * - Curve type - Compatible algorithms * - Weierstrass - - Weierstrass curve public keys can be used in asymmetric signature algorithms. + - Weierstrass curve public keys can be used in asymmetric signature and key encapsulation algorithms. `PSA_ALG_DETERMINISTIC_ECDSA` @@ -928,8 +934,15 @@ The curve type affects the key format, the key derivation procedure, and the alg `PSA_ALG_ECDSA_ANY` + `PSA_ALG_ECIES_SEC1` + + * - Montgomery + - Montgomery curve public keys can only be used in key encapsulation algorithms. + + `PSA_ALG_ECIES_SEC1` + * - Twisted Edwards - - Twisted Edwards curve public key can only be used in asymmetric signature algorithms. + - Twisted Edwards curve public keys can only be used in asymmetric signature algorithms. `PSA_ALG_PURE_EDDSA` diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 8a5cd299..dab241f8 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` * :secref:`asymmetric-encryption-algorithms` * :secref:`key-agreement-algorithms` +* :secref:`encapsulation-algorithms` * :secref:`pake` @@ -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 encapsulation 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 encapsulation algorithms. + Support macros -------------- diff --git a/doc/crypto/api/ops/index.rst b/doc/crypto/api/ops/index.rst index 903c79cf..d7f1b458 100644 --- a/doc/crypto/api/ops/index.rst +++ b/doc/crypto/api/ops/index.rst @@ -18,5 +18,6 @@ Cryptographic operation reference signature pk-encryption key-agreement + key-encapsulation pake rng diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst new file mode 100644 index 00000000..630e8dc2 --- /dev/null +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -0,0 +1,331 @@ +.. 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: 29 + +.. _encapsulation: + +Key encapsulation +================= + +A key-encapsulation mechanism (KEM) is a set of algorithms that can be used by two participants to establish a shared secret key over a public channel. +The shared secret key can then be used with symmetric-key cryptographic algorithms. + +In a KEM, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. +The public encapsulation key is made available to a second participant that needs to establish secure communication with the first participant. +The second participant uses the encapsulation key to generate one copy of a shared secret, and some associated encapsulation data. +The encapsulation data is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. + +Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between the participants. +However, some KEM algorithms result in a pseudo-random shared secret, which is suitable to be used directly as a cryptographic key. + +Applications can use the resulting keys for different use cases. +For example: + +* Encrypting and authenticating a single non-interactive message. +* Securing an interactive communication channel. + +.. _encapsulation-algorithms: + +Elliptic Curve Integrated Encryption Scheme +------------------------------------------- + +The Elliptic Curve Integrated Encryption Scheme (ECIES) was fist proposed by Shoup, then improved by Ballare and Rogaway. + +The original specification permitted a number of variants. +The |API| uses the version specified in :cite-title:`SEC1`. + +The full ECIES scheme uses an elliptic-curve key agreement between the recipient's static public key and an ephemeral private key, to establish encryption and authentication keys for secure transmission of arbitrary-length messages to the recipient. + +An application using ECIES must select all of the following parameters: + +* The elliptic curve for the initial key agreement. +* The KDF to derive the symmetric keys, and any label used in that derivation. +* The encryption and MAC algorithms. +* The additional data to include when computing the authentication. + +The |API| presents the key-agreement step of ECIES as a key encapsulation. +The key derivation, encryption, and authentication steps are left to the application. + +.. rationale:: + + Although it is possible to implement this in an application using key generation and key agreement, using the encapsulation functions enables an easy migration to other key encapsulation mechanisms, such as ML-KEM. + +.. admonition:: Implementation note + + It is possible that some applications may need to use alternative versions of ECIES to interoperate with legacy systems. + + While the application can implement this using key agreement functions, an implementation can choose to add these as a convenience with an :scterm:`implementation defined` algorithm identifier. + +.. macro:: PSA_ALG_ECIES_SEC1 + :definition: ((psa_algorithm_t)0x0b000100) + + .. summary:: + The Elliptic Curve Integrated Encryption Scheme (ECIES). + + This encapsulation scheme is defined by :cite-title:`SEC1` §5.1 under the name Elliptic Curve Integrated Encryption Scheme. + + A call to `psa_encapsulate()` carries out steps 1 to 4 of the ECIES encryption process described in `[SEC1]` §5.1.3: + + * The elliptic curve to use is determined by the key. + * The public key part of the input key is used as :math:`Q_V`. + * Cofactor ECDH is used to perform the key agreement. + * The shared secret :math:`Z` is output as the shared output key. + * The ephemeral public key :math:`\overline{R}` is output as the encapsulation data. + + A call to `psa_decapsulate()` carries out steps 2 to 5 of the ECIES decryption process described in `[SEC1]` §5.1.4: + + * The elliptic curve to use is determined by the key. + * The encapsulation data is decoded as :math:`\overline{R}`. + * The private key of the input key is used as :math:`d_V`. + * Cofactor ECDH is used to perform the key agreement. + * The shared secret :math:`Z` is output as the shared output key. + + The encapsulation provided by `PSA_ALG_ECIES_SEC1` is not authenticated. + When used in a full ECIES scheme, the authentication of the encrypted message implicitly confirms that the derived keys were identical. + + The shared output key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. + It must be used as an input to a key derivation operation to produce additional cryptographic keys. + + .. 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` + +Encapsulation functions +----------------------- + +.. function:: psa_encapsulate + + .. summary:: + Use a public key to generate a new shared secret key and associated encapsulation data. + + .. param:: psa_key_id_t key + Identifier of the key to use for the encapsulation. + It must be a public key or an asymmetric key pair. + It must permit the 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 output 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 shared output key. + `PSA_KEY_ID_NULL` on failure. + .. param:: uint8_t * encapsulation + Buffer where the encapsulated data is to be written. + .. param:: size_t encapsulation_size + Size of the ``encapsulation`` buffer in bytes. + This must be appropriate for the selected algorithm and key: + + * A sufficient output size is :code:`PSA_ENCAPSULATION_SIZE(type, bits, alg)`, where ``type`` and ``bits`` are the type and bit-size of ``key``. + * `PSA_ENCAPSULATION_MAX_SIZE` evaluates to the maximum output size of any supported encapsulation algorithm. + .. param:: size_t * encapsulation_length + On success, the number of bytes that make up the encapsulated data value. + + .. return:: psa_status_t + + .. retval:: PSA_SUCCESS + Success. + The bytes of ``encapsulation`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared output key. + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + * ``key`` is not supported for use 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. + * ``key`` is not a public key or an asymmetric key pair, that is compatible with ``alg``. + * The output key attributes in ``attributes`` are not valid: + + - The key type is not valid for the encapsulation shared secret. + - The key size is nonzero, and is not the size of the shared output. + - 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. + `PSA_ENCAPSULATION_SIZE()` or `PSA_ENCAPSULATION_MAX_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()`. + + 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 of the shared secret is dependent on the encapsulation algorithm and the type and size of ``key``. + + 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 ``encapsulation`` data is sent to the other participant, who uses the decapsulation key to extract another copy of the shared secret key. + +.. function:: psa_decapsulate + + .. summary:: + Use a private key to decapsulate a shared secret key from encapsulation data. + + .. param:: psa_key_id_t key + Identifier of the key to use for the operation. It must be an asymmetric key pair. + It 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 + The encapsulation data received from the other participant. + .. param:: size_t encapsulation_length + Size of the ``encapsulation`` buffer in bytes. + .. param:: const psa_key_attributes_t * attributes + The attributes for the output 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 shared output key. + `PSA_KEY_ID_NULL` on failure. + + .. return:: psa_status_t + + .. retval:: PSA_SUCCESS + Success. + ``output_key`` contains the identifier for the shared output key. + + In some algorithms, decapsulation failure is implicit, resulting in an incorrect output key, instead of reporting an error status. + + .. todo:: + What should the result be for an explicit decapsulation failure? - INVALID_SIGNATURE, or INVALID_ARGUMENT (as per the detection of incorrect-length encapsulation data)? + .. retval:: PSA_ERROR_NOT_SUPPORTED + The following conditions can result in this error: + + * ``alg`` is not supported or is not an encapsulation algorithm. + * ``key`` is not supported for use 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. + * ``key`` is not an asymmetric key pair, that is compatible with ``alg``. + * The output key attributes in ``attributes`` are not valid: + + - The key type is not valid for the encapsulation shared secret. + - The key size is nonzero, and is not the size of the shared output. + - 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 and key. + For example, the implementation can detect that it is an incorrect length. + .. 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_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 of the shared secret is dependent on the encapsulation algorithm and the type and size of ``key``. + + 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. + + .. warning:: + A successful result from `psa_decapsulate()` does not indicate that the output key is identical to the key produce by the call to `psa_encapsulate()`: + + * Some encapsulation algorithms do not authenticate the encapsulation data. + * Some encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. + + It is recommended that application uses the output key in a way that will confirm that the derived keys are identical. + +Support macros +-------------- + +.. macro:: PSA_ENCAPSULATION_SIZE + :definition: /* implementation-defined value */ + + .. summary:: + Sufficient encapsulation buffer size for `psa_encapsulate()`, in bytes. + + .. param:: key_type + A key type that is compatible with algorithm ``alg``. + .. param:: key_bits + The size of the key in bits. + .. param:: alg + An encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + + .. return:: + A sufficient output buffer size for the specified algorithm, 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. + + See also `PSA_ENCAPSULATION_MAX_SIZE`. + +.. macro:: PSA_ENCAPSULATION_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_SIZE()`. diff --git a/doc/crypto/api/ops/rng.rst b/doc/crypto/api/ops/rng.rst index ffb2202c..c2f6dfe9 100644 --- a/doc/crypto/api/ops/rng.rst +++ b/doc/crypto/api/ops/rng.rst @@ -2,7 +2,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto - :seq: 30 + :seq: 31 Other cryptographic services ============================ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index a1784f9a..26a87111 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,29 @@ 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/kem_encoding.* + :name: fig-encapsulation-encoding + + Encapsulation algorithm encoding + +The defined values for ENCAPS-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, ENCAPS-TYPE, Algorithm identifier, Algorithm value + ECIES (SEC1), ``0x01``, `PSA_ALG_ECIES_SEC1`, ``0x0b000100`` + .. _key-type-encoding: Key type encoding diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 8d5597c6..a0e60ab2 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -33,6 +33,10 @@ Changes to the API See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`. +* Added key encapsulation functions, `psa_encapsulate()` and `psa_decapsulate()`. + + - Added `PSA_ALG_ECIES_SEC1` as an encapsulation algorithm that implements the key agreement steps of ECIES. + Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index 11d1ea2d..c60e9923 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -84,6 +84,9 @@ Algorithm macros #define PSA_ALG_IS_ECDSA(alg) \ (((alg) & ~0x000001ff) == 0x06000600) + #define PSA_ALG_IS_ENCAPSULATION(alg) \ + (((alg) & 0x7f000000) == 0x0b000000) + #define PSA_ALG_IS_FFDH(alg) \ (((alg) & 0x7fff0000) == 0x09010000) diff --git a/doc/crypto/figure/encoding/kem_encoding.json b/doc/crypto/figure/encoding/kem_encoding.json new file mode 100644 index 00000000..4c47ad57 --- /dev/null +++ b/doc/crypto/figure/encoding/kem_encoding.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "0", "bits": 8 }, + { "name": "ENCAPS-TYPE", "bits": 8 }, + { "name": "0", "bits": 6 }, + { "name": "0", "bits": 1 }, + { "name": "0", "bits": 1 }, + { "name": "0x0B", "bits": 7 }, + { "name": "0", "bits": 1 } + ], + "options": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "vspace": 52, + "hspace": 600 + } +} diff --git a/doc/crypto/figure/encoding/kem_encoding.json.license b/doc/crypto/figure/encoding/kem_encoding.json.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/kem_encoding.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/kem_encoding.pdf b/doc/crypto/figure/encoding/kem_encoding.pdf new file mode 100644 index 0000000000000000000000000000000000000000..4359e3479161fe80e8220c41af879470e8553c2c GIT binary patch literal 8159 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 literal 0 HcmV?d00001 diff --git a/doc/crypto/figure/encoding/kem_encoding.pdf.license b/doc/crypto/figure/encoding/kem_encoding.pdf.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/kem_encoding.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/kem_encoding.svg b/doc/crypto/figure/encoding/kem_encoding.svg new file mode 100644 index 00000000..571df999 --- /dev/null +++ b/doc/crypto/figure/encoding/kem_encoding.svg @@ -0,0 +1,2 @@ + +07815162122232430310ENCAPS-TYPE0000x0B0 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/kem_encoding.svg.license b/doc/crypto/figure/encoding/kem_encoding.svg.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/kem_encoding.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/overview/functionality.rst b/doc/crypto/overview/functionality.rst index c3a6a9b1..05f0f196 100644 --- a/doc/crypto/overview/functionality.rst +++ b/doc/crypto/overview/functionality.rst @@ -41,6 +41,8 @@ Keys are created using one of the *key creation functions*: * `psa_key_derivation_output_key()` * `psa_key_derivation_output_key_custom()` * `psa_key_agreement()` +* `psa_encapsulate()` +* `psa_decapsulate()` * `psa_pake_get_shared_key()` * `psa_copy_key()` @@ -269,6 +271,7 @@ This specification defines interfaces for the following types of asymmetric cryp * Asymmetric encryption (also known as public key encryption). See :secref:`pke`. * Asymmetric signature. See :secref:`sign`. * Two-way key agreement (also known as key establishment). See :secref:`key-agreement`. +* Key encapsulation. See :secref:`encapsulation`. * Password-authenticated key exchange (PAKE). See :secref:`pake`. For asymmetric encryption, the API provides *single-part* functions. @@ -277,6 +280,8 @@ For asymmetric signature, the API provides single-part functions. For key agreement, the API provides single-part functions and an additional input method for a key derivation operation. +For key encapsulation, the API provides single-part functions. + For PAKE, the API provides a *multi-part* operation. From f929caeb93fa6d07adb25379ed5606df2c3a4060 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 21 Oct 2024 23:15:51 +0100 Subject: [PATCH 02/19] typo --- doc/crypto/api/ops/pake.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/ops/pake.rst b/doc/crypto/api/ops/pake.rst index eb02d3a8..4274b973 100644 --- a/doc/crypto/api/ops/pake.rst +++ b/doc/crypto/api/ops/pake.rst @@ -1022,7 +1022,7 @@ Multi-part PAKE operations The shared secret is retrieved as a key. Its location, policy, and type are taken from ``attributes``. - The size of the returned key is always the bit-size of the PAKE shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the PAKE algorithm and cipher suite. + The size of the returned key is always the bit-size of the PAKE shared secret, rounded up to a whole number of bytes. The size of the shared secret is dependent on the PAKE algorithm and cipher suite. This is the final call in a PAKE operation, which retrieves the shared secret as a key. It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. From 597699db8364ee1f8563cbcf6791043b477adb73 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 22 Oct 2024 16:37:50 +0100 Subject: [PATCH 03/19] Terminology alignment: * Use "key-encapsulation algorithm" --- doc/crypto/api/keys/types.rst | 8 +-- doc/crypto/api/ops/algorithms.rst | 8 +-- doc/crypto/api/ops/key-encapsulation.rst | 86 +++++++++++++----------- doc/crypto/appendix/encodings.rst | 12 ++-- doc/crypto/appendix/history.rst | 2 +- doc/crypto/overview/functionality.rst | 2 +- 6 files changed, 61 insertions(+), 57 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 894c4a95..7f1c7f83 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -797,7 +797,7 @@ The curve type affects the key format, the key derivation procedure, and the alg * - Curve type - Compatible algorithms * - Weierstrass - - Weierstrass curve key-pairs can be used in asymmetric signature, key agreement, and key encapsulation algorithms. + - Weierstrass curve key-pairs can be used in asymmetric signature, key agreement, and key-encapsulation algorithms. `PSA_ALG_DETERMINISTIC_ECDSA` @@ -810,7 +810,7 @@ The curve type affects the key format, the key derivation procedure, and the alg `PSA_ALG_ECIES_SEC1` * - Montgomery - - Montgomery curve key-pairs can be used in key agreement and key encapsulation algorithms. + - Montgomery curve key-pairs can be used in key agreement and key-encapsulation algorithms. `PSA_ALG_ECDH` @@ -926,7 +926,7 @@ The curve type affects the key format, the key derivation procedure, and the alg * - Curve type - Compatible algorithms * - Weierstrass - - Weierstrass curve public keys can be used in asymmetric signature and key encapsulation algorithms. + - Weierstrass curve public keys can be used in asymmetric signature and key-encapsulation algorithms. `PSA_ALG_DETERMINISTIC_ECDSA` @@ -937,7 +937,7 @@ The curve type affects the key format, the key derivation procedure, and the alg `PSA_ALG_ECIES_SEC1` * - Montgomery - - Montgomery curve public keys can only be used in key encapsulation algorithms. + - Montgomery curve public keys can only be used in key-encapsulation algorithms. `PSA_ALG_ECIES_SEC1` diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index dab241f8..4e0a16dc 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -23,7 +23,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope * :secref:`sign` * :secref:`asymmetric-encryption-algorithms` * :secref:`key-agreement-algorithms` -* :secref:`encapsulation-algorithms` +* :secref:`key-encapsulation-algorithms` * :secref:`pake` @@ -198,15 +198,15 @@ Algorithm categories :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is an encapsulation algorithm. + Whether the specified algorithm is a key-encapsulation algorithm. .. param:: alg An algorithm identifier: a value of type `psa_algorithm_t`. .. return:: - ``1`` if ``alg`` is an encapsulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + ``1`` if ``alg`` is a key-encapsulation 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 encapsulation algorithms. + See :secref:`key-encapsulation-algorithms` for a list of defined key-encapsulation algorithms. Support macros -------------- diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 630e8dc2..086cb6eb 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -4,21 +4,22 @@ .. header:: psa/crypto :seq: 29 -.. _encapsulation: +.. _key-encapsulation: Key encapsulation ================= -A key-encapsulation mechanism (KEM) is a set of algorithms that can be used by two participants to establish a shared secret key over a public channel. +A key-encapsulation algorithm can be used by two participants to establish a shared secret key over a public channel. The shared secret key can then be used with symmetric-key cryptographic algorithms. +Key-encapsulation algorithms are often referred to as 'key encapsulation mechanisms' or KEMs. -In a KEM, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. +In a key-encapsulation algorithm, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. The public encapsulation key is made available to a second participant that needs to establish secure communication with the first participant. The second participant uses the encapsulation key to generate one copy of a shared secret, and some associated encapsulation data. The encapsulation data is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between the participants. -However, some KEM algorithms result in a pseudo-random shared secret, which is suitable to be used directly as a cryptographic key. +However, some key-encapsulation algorithms result in a pseudo-random shared secret, which is suitable to be used directly as a cryptographic key. Applications can use the resulting keys for different use cases. For example: @@ -26,12 +27,12 @@ For example: * Encrypting and authenticating a single non-interactive message. * Securing an interactive communication channel. -.. _encapsulation-algorithms: +.. _key-encapsulation-algorithms: Elliptic Curve Integrated Encryption Scheme ------------------------------------------- -The Elliptic Curve Integrated Encryption Scheme (ECIES) was fist proposed by Shoup, then improved by Ballare and Rogaway. +The Elliptic Curve Integrated Encryption Scheme (ECIES) was first proposed by Shoup, then improved by Ballare and Rogaway. The original specification permitted a number of variants. The |API| uses the version specified in :cite-title:`SEC1`. @@ -45,18 +46,18 @@ An application using ECIES must select all of the following parameters: * The encryption and MAC algorithms. * The additional data to include when computing the authentication. -The |API| presents the key-agreement step of ECIES as a key encapsulation. +The |API| presents the key-agreement step of ECIES as a key-encapsulation algorithm. The key derivation, encryption, and authentication steps are left to the application. .. rationale:: - Although it is possible to implement this in an application using key generation and key agreement, using the encapsulation functions enables an easy migration to other key encapsulation mechanisms, such as ML-KEM. + Although it is possible to implement this in an application using key generation and key agreement, using the key-encapsulation functions enables an easy migration to other key-encapsulation algorithms, such as ML-KEM. .. admonition:: Implementation note It is possible that some applications may need to use alternative versions of ECIES to interoperate with legacy systems. - While the application can implement this using key agreement functions, an implementation can choose to add these as a convenience with an :scterm:`implementation defined` algorithm identifier. + While the application can implement this using key agreement functions, an implementation can choose to add these as a convenience with an :scterm:`implementation defined` key-encapsulation algorithm identifier. .. macro:: PSA_ALG_ECIES_SEC1 :definition: ((psa_algorithm_t)0x0b000100) @@ -64,7 +65,7 @@ The key derivation, encryption, and authentication steps are left to the applica .. summary:: The Elliptic Curve Integrated Encryption Scheme (ECIES). - This encapsulation scheme is defined by :cite-title:`SEC1` §5.1 under the name Elliptic Curve Integrated Encryption Scheme. + This key-encapsulation algorithm is defined by :cite-title:`SEC1` §5.1 under the name Elliptic Curve Integrated Encryption Scheme. A call to `psa_encapsulate()` carries out steps 1 to 4 of the ECIES encryption process described in `[SEC1]` §5.1.3: @@ -101,8 +102,8 @@ The key derivation, encryption, and authentication steps are left to the applica * `PSA_ECC_FAMILY_BRAINPOOL_P_R1` * `PSA_ECC_FAMILY_MONTGOMERY` -Encapsulation functions ------------------------ +Key-encapsulation functions +--------------------------- .. function:: psa_encapsulate @@ -114,15 +115,15 @@ Encapsulation functions It must be a public key or an asymmetric key pair. It must permit the 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. + The key-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 output 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. + All key-encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + Key-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 key-encapsulation algorithms for more information. The following attributes must be set for keys used in cryptographic operations: @@ -136,7 +137,7 @@ Encapsulation functions The following attributes are optional: - * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. + * If the key size is nonzero, it must be equal to the size of the shared secret. .. note:: This is an input parameter: it is not updated with the final key attributes. @@ -151,7 +152,7 @@ Encapsulation functions This must be appropriate for the selected algorithm and key: * A sufficient output size is :code:`PSA_ENCAPSULATION_SIZE(type, bits, alg)`, where ``type`` and ``bits`` are the type and bit-size of ``key``. - * `PSA_ENCAPSULATION_MAX_SIZE` evaluates to the maximum output size of any supported encapsulation algorithm. + * `PSA_ENCAPSULATION_MAX_SIZE` evaluates to the maximum output size of any supported key-encapsulation algorithm. .. param:: size_t * encapsulation_length On success, the number of bytes that make up the encapsulated data value. @@ -163,17 +164,17 @@ Encapsulation functions .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: - * ``alg`` is not supported or is not an encapsulation algorithm. + * ``alg`` is not supported or is not a key-encapsulation algorithm. * ``key`` is not supported for use 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. + * ``alg`` is not a key-encapsulation algorithm. * ``key`` is not a public key or an asymmetric key pair, that is compatible with ``alg``. * The output key attributes in ``attributes`` are not valid: - - The key type is not valid for the encapsulation shared secret. + - The key type is not valid for the shared output key. - The key size is nonzero, and is not the size of the shared output. - The key lifetime is invalid. - The key identifier is not valid for the key lifetime. @@ -191,11 +192,12 @@ Encapsulation functions 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 of the shared secret is dependent on the encapsulation algorithm and the type and size of ``key``. + 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 of the shared secret is dependent on the key-encapsulation algorithm and the type and size of ``key``. 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. + For some key-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 key-encapsulation algorithms for more information. The ``encapsulation`` data is sent to the other participant, who uses the decapsulation key to extract another copy of the shared secret key. @@ -205,11 +207,12 @@ Encapsulation functions Use a private key to decapsulate a shared secret key from encapsulation data. .. param:: psa_key_id_t key - Identifier of the key to use for the operation. It must be an asymmetric key pair. + Identifier of the key to use for the decapsulation. + It must be an asymmetric key pair. It 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 + The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + .. param:: const uint8_t * encapsulation The encapsulation data received from the other participant. .. param:: size_t encapsulation_length Size of the ``encapsulation`` buffer in bytes. @@ -218,9 +221,9 @@ Encapsulation functions 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. + All key-encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + Key-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 key-encapsulation algorithms for more information. The following attributes must be set for keys used in cryptographic operations: @@ -234,7 +237,7 @@ Encapsulation functions The following attributes are optional: - * If the key size is nonzero, it must be equal to the size of the encapsulation shared secret. + * If the key size is nonzero, it must be equal to the size of the key-encapsulation shared secret. .. note:: This is an input parameter: it is not updated with the final key attributes. @@ -256,17 +259,17 @@ Encapsulation functions .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: - * ``alg`` is not supported or is not an encapsulation algorithm. + * ``alg`` is not supported or is not a key-encapsulation algorithm. * ``key`` is not supported for use 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. + * ``alg`` is not a key-encapsulation algorithm. * ``key`` is not an asymmetric key pair, that is compatible with ``alg``. * The output key attributes in ``attributes`` are not valid: - - The key type is not valid for the encapsulation shared secret. + - The key type is not valid for the shared output key. - The key size is nonzero, and is not the size of the shared output. - The key lifetime is invalid. - The key identifier is not valid for the key lifetime. @@ -283,17 +286,18 @@ Encapsulation functions 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 of the shared secret is dependent on the encapsulation algorithm and the type and size of ``key``. + 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 of the shared secret is dependent on the key-encapsulation algorithm and the type and size of ``key``. 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. + For some key-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 key-encapsulation algorithms for more information. .. warning:: A successful result from `psa_decapsulate()` does not indicate that the output key is identical to the key produce by the call to `psa_encapsulate()`: - * Some encapsulation algorithms do not authenticate the encapsulation data. - * Some encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. + * Some key-encapsulation algorithms do not authenticate the encapsulation data. + * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. It is recommended that application uses the output key in a way that will confirm that the derived keys are identical. @@ -311,7 +315,7 @@ Support macros .. param:: key_bits The size of the key in bits. .. param:: alg - An encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + A key-encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. .. return:: A sufficient output buffer size for the specified algorithm, 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. @@ -324,7 +328,7 @@ Support macros :definition: /* implementation-defined value */ .. summary:: - Sufficient output buffer size for `psa_encapsulate()`, 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 key-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. diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 26a87111..99ce7591 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -84,7 +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` + Encapsulation, ``0x0B``, See :secref:`key-encapsulation-encoding` .. rationale:: @@ -417,22 +417,22 @@ 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: +.. _key-encapsulation-encoding: Encapsulation algorithm encoding ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The algorithm identifier for encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-encapsulation-encoding`. +The algorithm identifier for key-encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-key-encapsulation-encoding`. .. figure:: /figure/encoding/kem_encoding.* - :name: fig-encapsulation-encoding + :name: fig-key-encapsulation-encoding Encapsulation algorithm encoding -The defined values for ENCAPS-TYPE are shown in :numref:`table-encapsulation-type`. +The defined values for ENCAPS-TYPE are shown in :numref:`table-key-encapsulation-type`. .. csv-table:: Encapsulation algorithm sub-type values - :name: table-encapsulation-type + :name: table-key-encapsulation-type :header-rows: 1 :align: left :widths: auto diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index a0e60ab2..e7d3dd61 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -35,7 +35,7 @@ Changes to the API * Added key encapsulation functions, `psa_encapsulate()` and `psa_decapsulate()`. - - Added `PSA_ALG_ECIES_SEC1` as an encapsulation algorithm that implements the key agreement steps of ECIES. + - Added `PSA_ALG_ECIES_SEC1` as a key-encapsulation algorithm that implements the key agreement steps of ECIES. Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/overview/functionality.rst b/doc/crypto/overview/functionality.rst index 05f0f196..27acef04 100644 --- a/doc/crypto/overview/functionality.rst +++ b/doc/crypto/overview/functionality.rst @@ -271,7 +271,7 @@ This specification defines interfaces for the following types of asymmetric cryp * Asymmetric encryption (also known as public key encryption). See :secref:`pke`. * Asymmetric signature. See :secref:`sign`. * Two-way key agreement (also known as key establishment). See :secref:`key-agreement`. -* Key encapsulation. See :secref:`encapsulation`. +* Key encapsulation. See :secref:`key-encapsulation`. * Password-authenticated key exchange (PAKE). See :secref:`pake`. For asymmetric encryption, the API provides *single-part* functions. From cbe08943460b078d57754ddf5bb6c85ffd9f3f27 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 22 Oct 2024 16:39:32 +0100 Subject: [PATCH 04/19] Clarify explicit/implicit decapsulation failure: * Permit INVALID_SIGNATURE error for authentication failure * Include probablistic failure as additional reason for non-guarantee (e.g. ML-KEM) * Add note to NOT report padding errors in a distinct manner --- doc/crypto/api/ops/key-encapsulation.rst | 30 +++++++++++++++++------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 086cb6eb..07dfb599 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -83,7 +83,7 @@ The key derivation, encryption, and authentication steps are left to the applica * Cofactor ECDH is used to perform the key agreement. * The shared secret :math:`Z` is output as the shared output key. - The encapsulation provided by `PSA_ALG_ECIES_SEC1` is not authenticated. + The encapsulation data produced by `PSA_ALG_ECIES_SEC1` is not authenticated. When used in a full ECIES scheme, the authentication of the encrypted message implicitly confirms that the derived keys were identical. The shared output key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. @@ -252,10 +252,9 @@ Key-encapsulation functions Success. ``output_key`` contains the identifier for the shared output key. - In some algorithms, decapsulation failure is implicit, resulting in an incorrect output key, instead of reporting an error status. - - .. todo:: - What should the result be for an explicit decapsulation failure? - INVALID_SIGNATURE, or INVALID_ARGUMENT (as per the detection of incorrect-length encapsulation data)? + .. note:: + In some key-encapsulation algorithms, decapsulation failure is not reported with a explicit error code. + Instead, an incorrect, pseudo-random key is output. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: @@ -276,8 +275,14 @@ Key-encapsulation functions - 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 and key. + * ``encapsulation`` is obviously invalid for the selected algorithm and key. For example, the implementation can detect that it is an incorrect length. + .. retval:: PSA_ERROR_INVALID_SIGNATURE + Authentication of the encapsulation data fails. + + .. note:: + Some key-encapsulation algorithms do not report an authentication failure explicitly. + Instead, an incorrect, pseudo-random key is output. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -294,12 +299,21 @@ Key-encapsulation functions Refer to the documentation of individual key-encapsulation algorithms for more information. .. warning:: - A successful result from `psa_decapsulate()` does not indicate that the output key is identical to the key produce by the call to `psa_encapsulate()`: + A :code:`PSA_SUCCESS` result from `psa_decapsulate()` does not guarantee that the output key is identical to the key produce by the call to `psa_encapsulate()`. For example: * Some key-encapsulation algorithms do not authenticate the encapsulation data. + Manipulated encapsulation data will not be detected during decapsulation. * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. + This prevents disclosing information to an attacker that has manipulated the encapsulation data. + * Some key-encapsulation algorithms are probablistic, and cannot guarantee that decapsulation will result in an identical key value. + + It is strongly recommended that application uses the output key in a way that will confirm that the derived keys are identical. + + .. admonition:: Implementation note + + For key-encapsulation algorithms which involve data padding when computing the encapsulation data, the decapsulation algorithm **must not** report a distinct error status if invalid padding is detected. - It is recommended that application uses the output key in a way that will confirm that the derived keys are identical. + Instead, it is recommended that the decapsulation fails implicitly when invalid padding is detected, returning a pseudo-random key. Support macros -------------- From b5840cde2acc19e94d9487e281fe7026e928f02b Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 24 Oct 2024 20:36:01 +0100 Subject: [PATCH 05/19] Reallocate the algorithm category for key-encapsulation Leave 0x0b for key-wrapping, and use 0x0c for encapsulation. --- doc/crypto/api.db/psa/crypto.h | 10 ++-- doc/crypto/api/keys/policy.rst | 4 +- doc/crypto/api/ops/algorithms.rst | 2 +- doc/crypto/api/ops/key-encapsulation.rst | 9 ++-- doc/crypto/appendix/encodings.rst | 48 +++++++++---------- doc/crypto/appendix/specdef_values.rst | 6 +-- doc/crypto/figure/encoding/kem_encoding.json | 2 +- doc/crypto/figure/encoding/kem_encoding.pdf | Bin 8159 -> 7966 bytes doc/crypto/figure/encoding/kem_encoding.svg | 2 +- 9 files changed, 42 insertions(+), 41 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 2f11a93e..508b5ef0 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -76,7 +76,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_ECDH ((psa_algorithm_t)0x09020000) #define PSA_ALG_ECDSA(hash_alg) /* specification-defined value */ #define PSA_ALG_ECDSA_ANY ((psa_algorithm_t) 0x06000600) -#define PSA_ALG_ECIES_SEC1 ((psa_algorithm_t)0x0b000100) +#define PSA_ALG_ECIES_SEC1 ((psa_algorithm_t)0x0c000100) #define PSA_ALG_ED25519PH ((psa_algorithm_t) 0x0600090B) #define PSA_ALG_ED448PH ((psa_algorithm_t) 0x06000915) #define PSA_ALG_FFDH ((psa_algorithm_t)0x09010000) @@ -95,7 +95,6 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */ #define PSA_ALG_IS_ECDH(alg) /* specification-defined value */ #define PSA_ALG_IS_ECDSA(alg) /* specification-defined value */ -#define PSA_ALG_IS_ENCAPSULATION(alg) /* specification-defined value */ #define PSA_ALG_IS_FFDH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH_AND_SIGN(alg) /* specification-defined value */ @@ -109,6 +108,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_KEY_DERIVATION(alg) /* specification-defined value */ #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \ /* specification-defined value */ +#define PSA_ALG_IS_KEY_ENCAPSULATION(alg) /* specification-defined value */ #define PSA_ALG_IS_MAC(alg) /* specification-defined value */ #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */ @@ -329,10 +329,10 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007) #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) -#define PSA_KEY_USAGE_DECAPSULATE ((psa_key_usage_t)0x00020000) +#define PSA_KEY_USAGE_DECAPSULATE ((psa_key_usage_t)0x00080000) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) -#define PSA_KEY_USAGE_ENCAPSULATE ((psa_key_usage_t)0x00010000) +#define PSA_KEY_USAGE_ENCAPSULATE ((psa_key_usage_t)0x00040000) #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) @@ -507,7 +507,7 @@ psa_status_t psa_copy_key(psa_key_id_t source_key, psa_status_t psa_crypto_init(void); psa_status_t psa_decapsulate(psa_key_id_t key, psa_algorithm_t alg, - conts uint8_t * encapsulation, + const uint8_t * encapsulation, size_t encapsulation_length, const psa_key_attributes_t * attributes, psa_key_id_t * output_key); diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 15a8281a..68d7f067 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -266,7 +266,7 @@ 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) + :definition: ((psa_key_usage_t)0x00040000) .. summary:: Permission to encapsulate new keys. @@ -278,7 +278,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. * `psa_encapsulate()` .. macro:: PSA_KEY_USAGE_DECAPSULATE - :definition: ((psa_key_usage_t)0x00020000) + :definition: ((psa_key_usage_t)0x00080000) .. summary:: Permission to decapsulate an encapsulated key. diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 4e0a16dc..4897255e 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -194,7 +194,7 @@ 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 +.. macro:: PSA_ALG_IS_KEY_ENCAPSULATION :definition: /* specification-defined value */ .. summary:: diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 07dfb599..5fece8cf 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -60,7 +60,7 @@ The key derivation, encryption, and authentication steps are left to the applica While the application can implement this using key agreement functions, an implementation can choose to add these as a convenience with an :scterm:`implementation defined` key-encapsulation algorithm identifier. .. macro:: PSA_ALG_ECIES_SEC1 - :definition: ((psa_algorithm_t)0x0b000100) + :definition: ((psa_algorithm_t)0x0c000100) .. summary:: The Elliptic Curve Integrated Encryption Scheme (ECIES). @@ -92,6 +92,7 @@ The key derivation, encryption, and authentication steps are left to the applica .. subsection:: Compatible key types | :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` + | :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(family)` (encapsulaton only) where ``family`` is a Weierstrass or Montgomery Elliptic curve family. That is, one of the following values: @@ -115,7 +116,7 @@ Key-encapsulation functions It must be a public key or an asymmetric key pair. It must permit the usage `PSA_KEY_USAGE_ENCAPSULATE`. .. param:: psa_algorithm_t alg - The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. param:: const psa_key_attributes_t * attributes The attributes for the output key. This function uses the attributes as follows: @@ -211,7 +212,7 @@ Key-encapsulation functions It must be an asymmetric key pair. It must permit the usage `PSA_KEY_USAGE_DECAPSULATE`. .. param:: psa_algorithm_t alg - The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. param:: const uint8_t * encapsulation The encapsulation data received from the other participant. .. param:: size_t encapsulation_length @@ -329,7 +330,7 @@ Support macros .. param:: key_bits The size of the key in bits. .. param:: alg - A key-encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_ENCAPSULATION(alg)` is true. + A key-encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. return:: A sufficient output buffer size for the specified algorithm, 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. diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 99ce7591..ffbc81a6 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -83,8 +83,8 @@ The CAT field in an algorithm identifier takes the values shown in :numref:`tabl Asymmetric signature, ``0x06``, See :secref:`sign-encoding` Asymmetric encryption, ``0x07``, See :secref:`pke-encoding` Key agreement, ``0x09``, See :secref:`ka-encoding` + Key encapsulation, ``0x0C``, See :secref:`key-encapsulation-encoding` PAKE, ``0x0A``, See :secref:`pake-encoding` - Encapsulation, ``0x0B``, See :secref:`key-encapsulation-encoding` .. rationale:: @@ -387,6 +387,29 @@ A combined key agreement is constructed by a bitwise OR of the standalone key ag The underlying standalone key agreement algorithm can be extracted from the KA-TYPE field, and the key derivation algorithm from the KDF-TYPE and HASH-TYPE fields. +.. _key-encapsulation-encoding: + +Key-encapsulation algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The algorithm identifier for key-encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-key-encapsulation-encoding`. + +.. figure:: /figure/encoding/kem_encoding.* + :name: fig-key-encapsulation-encoding + + Encapsulation algorithm encoding + +The defined values for ENCAPS-TYPE are shown in :numref:`table-key-encapsulation-type`. + +.. csv-table:: Encapsulation algorithm sub-type values + :name: table-key-encapsulation-type + :header-rows: 1 + :align: left + :widths: auto + + Encapsulation algorithm, ENCAPS-TYPE, Algorithm identifier, Algorithm value + ECIES (SEC1), ``0x01``, `PSA_ALG_ECIES_SEC1`, ``0x0C000100`` + .. _pake-encoding: PAKE algorithm encoding @@ -417,29 +440,6 @@ 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. -.. _key-encapsulation-encoding: - -Encapsulation algorithm encoding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The algorithm identifier for key-encapsulation algorithms defined in this specification are encoded as shown in :numref:`fig-key-encapsulation-encoding`. - -.. figure:: /figure/encoding/kem_encoding.* - :name: fig-key-encapsulation-encoding - - Encapsulation algorithm encoding - -The defined values for ENCAPS-TYPE are shown in :numref:`table-key-encapsulation-type`. - -.. csv-table:: Encapsulation algorithm sub-type values - :name: table-key-encapsulation-type - :header-rows: 1 - :align: left - :widths: auto - - Encapsulation algorithm, ENCAPS-TYPE, Algorithm identifier, Algorithm value - ECIES (SEC1), ``0x01``, `PSA_ALG_ECIES_SEC1`, ``0x0b000100`` - .. _key-type-encoding: Key type encoding diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index c60e9923..1702167b 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -84,9 +84,6 @@ Algorithm macros #define PSA_ALG_IS_ECDSA(alg) \ (((alg) & ~0x000001ff) == 0x06000600) - #define PSA_ALG_IS_ENCAPSULATION(alg) \ - (((alg) & 0x7f000000) == 0x0b000000) - #define PSA_ALG_IS_FFDH(alg) \ (((alg) & 0x7fff0000) == 0x09010000) @@ -124,6 +121,9 @@ Algorithm macros #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \ (((alg) & 0x7f800000) == 0x08800000) + #define PSA_ALG_IS_KEY_ENCAPSULATION(alg) \ + (((alg) & 0x7f000000) == 0x0c000000) + #define PSA_ALG_IS_MAC(alg) \ (((alg) & 0x7f000000) == 0x03000000) diff --git a/doc/crypto/figure/encoding/kem_encoding.json b/doc/crypto/figure/encoding/kem_encoding.json index 4c47ad57..369fbf98 100644 --- a/doc/crypto/figure/encoding/kem_encoding.json +++ b/doc/crypto/figure/encoding/kem_encoding.json @@ -5,7 +5,7 @@ { "name": "0", "bits": 6 }, { "name": "0", "bits": 1 }, { "name": "0", "bits": 1 }, - { "name": "0x0B", "bits": 7 }, + { "name": "0x0C", "bits": 7 }, { "name": "0", "bits": 1 } ], "options": { diff --git a/doc/crypto/figure/encoding/kem_encoding.pdf b/doc/crypto/figure/encoding/kem_encoding.pdf index 4359e3479161fe80e8220c41af879470e8553c2c..e5b135139bb509a3b09fa0af9523bd6704f554a4 100644 GIT binary patch delta 5657 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 QlF2}!WW2muM%rZm1I<;IyZ`_I delta 5874 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 -07815162122232430310ENCAPS-TYPE0000x0B0 \ No newline at end of file +07815162122232430310ENCAPS-TYPE0000x0C0 \ No newline at end of file From 387f6acbaa5d8108d1e3d6d1315ed957739b9829 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 18:17:38 +0000 Subject: [PATCH 06/19] Use 'ciphertext' instead of 'encapsulation data' Fixing terminology for encapsulation API. This includes updating the ciphertext buffer sizing macros to be PSA_ENCAPSULATE_CIPHERTEXT_[MAX_]SIZE. --- doc/crypto/api/ops/key-encapsulation.rst | 80 ++++++++++++------------ 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 5fece8cf..8a4d2818 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -15,8 +15,8 @@ Key-encapsulation algorithms are often referred to as 'key encapsulation mechani In a key-encapsulation algorithm, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. The public encapsulation key is made available to a second participant that needs to establish secure communication with the first participant. -The second participant uses the encapsulation key to generate one copy of a shared secret, and some associated encapsulation data. -The encapsulation data is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. +The second participant uses the encapsulation key to generate one copy of a shared secret, and some ciphertext. +The ciphertext is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between the participants. However, some key-encapsulation algorithms result in a pseudo-random shared secret, which is suitable to be used directly as a cryptographic key. @@ -73,17 +73,17 @@ The key derivation, encryption, and authentication steps are left to the applica * The public key part of the input key is used as :math:`Q_V`. * Cofactor ECDH is used to perform the key agreement. * The shared secret :math:`Z` is output as the shared output key. - * The ephemeral public key :math:`\overline{R}` is output as the encapsulation data. + * The ephemeral public key :math:`\overline{R}` is output as the ciphertext. A call to `psa_decapsulate()` carries out steps 2 to 5 of the ECIES decryption process described in `[SEC1]` §5.1.4: * The elliptic curve to use is determined by the key. - * The encapsulation data is decoded as :math:`\overline{R}`. + * The ciphertext is decoded as :math:`\overline{R}`. * The private key of the input key is used as :math:`d_V`. * Cofactor ECDH is used to perform the key agreement. * The shared secret :math:`Z` is output as the shared output key. - The encapsulation data produced by `PSA_ALG_ECIES_SEC1` is not authenticated. + The ciphertext produced by `PSA_ALG_ECIES_SEC1` is not authenticated. When used in a full ECIES scheme, the authentication of the encrypted message implicitly confirms that the derived keys were identical. The shared output key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. @@ -109,7 +109,7 @@ Key-encapsulation functions .. function:: psa_encapsulate .. summary:: - Use a public key to generate a new shared secret key and associated encapsulation data. + Use a public key to generate a new shared secret key and associated ciphertext. .. param:: psa_key_id_t key Identifier of the key to use for the encapsulation. @@ -146,22 +146,22 @@ Key-encapsulation functions .. param:: psa_key_id_t * output_key On success, an identifier for the newly created shared output key. `PSA_KEY_ID_NULL` on failure. - .. param:: uint8_t * encapsulation - Buffer where the encapsulated data is to be written. + .. param:: uint8_t * ciphertext + Buffer where the ciphertext output is to be written. .. param:: size_t encapsulation_size - Size of the ``encapsulation`` buffer in bytes. + Size of the ``ciphertext`` buffer in bytes. This must be appropriate for the selected algorithm and key: - * A sufficient output size is :code:`PSA_ENCAPSULATION_SIZE(type, bits, alg)`, where ``type`` and ``bits`` are the type and bit-size of ``key``. - * `PSA_ENCAPSULATION_MAX_SIZE` evaluates to the maximum output size of any supported key-encapsulation algorithm. - .. param:: size_t * encapsulation_length - On success, the number of bytes that make up the encapsulated data value. + * A sufficient ciphertext size is :code:`PSA_ENCAPSULATE_CIPHERTEXT_SIZE(type, bits, alg)`, where ``type`` and ``bits`` are the type and bit-size of ``key``. + * `PSA_ENCAPSULATE_CIPHERTEXT_MAX_SIZE` evaluates to the maximum ciphertext size of any supported key-encapsulation algorithm. + .. param:: size_t * ciphertext_length + On success, the number of bytes that make up the ciphertext value. .. return:: psa_status_t .. retval:: PSA_SUCCESS Success. - The bytes of ``encapsulation`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared output key. + The bytes of ``ciphertext`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared output key. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: @@ -183,8 +183,8 @@ Key-encapsulation functions - 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. - `PSA_ENCAPSULATION_SIZE()` or `PSA_ENCAPSULATION_MAX_SIZE` can be used to determine a sufficient buffer size. + The size of the ``ciphertext`` buffer is too small. + `PSA_ENCAPSULATE_CIPHERTEXT_SIZE()` or `PSA_ENCAPSULATE_CIPHERTEXT_MAX_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 @@ -200,12 +200,12 @@ Key-encapsulation functions For some key-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 key-encapsulation algorithms for more information. - The ``encapsulation`` data is sent to the other participant, who uses the decapsulation key to extract another copy of the shared secret key. + The output ``ciphertext`` is to be sent to the other participant, who uses the decapsulation key to extract another copy of the shared secret key. .. function:: psa_decapsulate .. summary:: - Use a private key to decapsulate a shared secret key from encapsulation data. + Use a private key to decapsulate a shared secret key from a ciphertext. .. param:: psa_key_id_t key Identifier of the key to use for the decapsulation. @@ -213,10 +213,10 @@ Key-encapsulation functions It must permit the usage `PSA_KEY_USAGE_DECAPSULATE`. .. param:: psa_algorithm_t alg The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. - .. param:: const uint8_t * encapsulation - The encapsulation data received from the other participant. + .. param:: const uint8_t * ciphertext + The ciphertext received from the other participant. .. param:: size_t encapsulation_length - Size of the ``encapsulation`` buffer in bytes. + Size of the ``ciphertext`` buffer in bytes. .. param:: const psa_key_attributes_t * attributes The attributes for the output key. This function uses the attributes as follows: @@ -276,10 +276,10 @@ Key-encapsulation functions - 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 obviously invalid for the selected algorithm and key. - For example, the implementation can detect that it is an incorrect length. + * ``ciphertext`` is obviously invalid for the selected algorithm and key. + For example, the implementation can detect that it has an incorrect length. .. retval:: PSA_ERROR_INVALID_SIGNATURE - Authentication of the encapsulation data fails. + Authentication of the ciphertext fails. .. note:: Some key-encapsulation algorithms do not report an authentication failure explicitly. @@ -302,49 +302,49 @@ Key-encapsulation functions .. warning:: A :code:`PSA_SUCCESS` result from `psa_decapsulate()` does not guarantee that the output key is identical to the key produce by the call to `psa_encapsulate()`. For example: - * Some key-encapsulation algorithms do not authenticate the encapsulation data. - Manipulated encapsulation data will not be detected during decapsulation. + * Some key-encapsulation algorithms do not authenticate the ciphertext. + Manipulated ciphertext will not be detected during decapsulation. * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. - This prevents disclosing information to an attacker that has manipulated the encapsulation data. + This prevents disclosing information to an attacker that has manipulated the ciphertext. * Some key-encapsulation algorithms are probablistic, and cannot guarantee that decapsulation will result in an identical key value. It is strongly recommended that application uses the output key in a way that will confirm that the derived keys are identical. .. admonition:: Implementation note - For key-encapsulation algorithms which involve data padding when computing the encapsulation data, the decapsulation algorithm **must not** report a distinct error status if invalid padding is detected. + For key-encapsulation algorithms which involve data padding when computing the ciphertext, the decapsulation algorithm **must not** report a distinct error status if invalid padding is detected. Instead, it is recommended that the decapsulation fails implicitly when invalid padding is detected, returning a pseudo-random key. Support macros -------------- -.. macro:: PSA_ENCAPSULATION_SIZE +.. macro:: PSA_ENCAPSULATE_CIPHERTEXT_SIZE :definition: /* implementation-defined value */ .. summary:: - Sufficient encapsulation buffer size for `psa_encapsulate()`, in bytes. + Sufficient ciphertext buffer size for `psa_encapsulate()`, in bytes. .. param:: key_type - A key type that is compatible with algorithm ``alg``. + A key type that is compatible with algorithm ``alg``. .. param:: key_bits - The size of the key in bits. + The size of the key in bits. .. param:: alg - A key-encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. + A key-encapsulation algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. return:: - A sufficient output buffer size for the specified algorithm, 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. + A sufficient ciphertext buffer size for the specified algorithm, 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 ciphertext 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 ciphertext might be smaller in any given call. - See also `PSA_ENCAPSULATION_MAX_SIZE`. + See also `PSA_ENCAPSULATE_CIPHERTEXT_MAX_SIZE`. -.. macro:: PSA_ENCAPSULATION_MAX_SIZE +.. macro:: PSA_ENCAPSULATE_CIPHERTEXT_MAX_SIZE :definition: /* implementation-defined value */ .. summary:: - Sufficient output buffer size for `psa_encapsulate()`, for any of the supported key types and key-encapsulation algorithms. + Sufficient ciphertext buffer size for `psa_encapsulate()`, for any of the supported key types and key-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 ciphertext 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_SIZE()`. + See also `PSA_ENCAPSULATE_CIPHERTEXT_SIZE()`. From 7e5b410dae82d0f10c1929ecfde54ede5a918617 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 18:22:39 +0000 Subject: [PATCH 07/19] Consistent hyphenation of "key-establishment xxx" --- doc/crypto/api/keys/management.rst | 2 +- doc/crypto/api/ops/key-encapsulation.rst | 4 ++-- doc/crypto/appendix/history.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index abf7fb39..7b72ef67 100644 --- a/doc/crypto/api/keys/management.rst +++ b/doc/crypto/api/keys/management.rst @@ -18,7 +18,7 @@ New keys can be created in the following ways: * `psa_generate_key()` and `psa_generate_key_custom()` create a key from randomly generated data. * `psa_key_derivation_output_key()` and `psa_key_derivation_output_key_custom()` create a key from data generated by a pseudorandom derivation process. See :secref:`kdf`. * `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`. -* `psa_encapsulate()` and `psa_decapsulate()` create a shared secret key using a key encapsulation mechanism. +* `psa_encapsulate()` and `psa_decapsulate()` create a shared secret key using a key-encapsulation mechanism. * `psa_pake_get_shared_key()` creates a key from the shared secret result of a password-authenticated key exchange. See :secref:`pake`. * `psa_copy_key()` duplicates an existing key with a different lifetime or with a more restrictive usage policy. diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 8a4d2818..f1015b86 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -11,7 +11,7 @@ Key encapsulation A key-encapsulation algorithm can be used by two participants to establish a shared secret key over a public channel. The shared secret key can then be used with symmetric-key cryptographic algorithms. -Key-encapsulation algorithms are often referred to as 'key encapsulation mechanisms' or KEMs. +Key-encapsulation algorithms are often referred to as 'key-encapsulation mechanisms' or KEMs. In a key-encapsulation algorithm, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. The public encapsulation key is made available to a second participant that needs to establish secure communication with the first participant. @@ -238,7 +238,7 @@ Key-encapsulation functions The following attributes are optional: - * If the key size is nonzero, it must be equal to the size of the key-encapsulation shared secret. + * If the key size is nonzero, it must be equal to the size of the shared secret. .. note:: This is an input parameter: it is not updated with the final key attributes. diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index e7d3dd61..0056c395 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -33,7 +33,7 @@ Changes to the API See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`. -* Added key encapsulation functions, `psa_encapsulate()` and `psa_decapsulate()`. +* Added key-encapsulation functions, `psa_encapsulate()` and `psa_decapsulate()`. - Added `PSA_ALG_ECIES_SEC1` as a key-encapsulation algorithm that implements the key agreement steps of ECIES. From a1faff325a17a21345f439c6c1dea2c4ccd98290 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 18:28:58 +0000 Subject: [PATCH 08/19] Dehyphenate pseduorandom, and qualify as 'uniformly' when appropriate --- doc/crypto/api/ops/key-encapsulation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index f1015b86..c7aa4253 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -19,7 +19,7 @@ The second participant uses the encapsulation key to generate one copy of a shar The ciphertext is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between the participants. -However, some key-encapsulation algorithms result in a pseudo-random shared secret, which is suitable to be used directly as a cryptographic key. +However, some key-encapsulation algorithms result in a uniformly pseudorandom shared secret, which is suitable to be used directly as a cryptographic key. Applications can use the resulting keys for different use cases. For example: @@ -123,7 +123,7 @@ Key-encapsulation functions * The key type. All key-encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. - Key-encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Key-encapsulation algorithms that produce a uniformly pseudorandom shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. Refer to the documentation of individual key-encapsulation algorithms for more information. The following attributes must be set for keys used in cryptographic operations: @@ -223,7 +223,7 @@ Key-encapsulation functions * The key type. All key-encapsulation algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. - Key-encapsulation algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + Key-encapsulation algorithms that produce a uniformly pseudorandom shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. Refer to the documentation of individual key-encapsulation algorithms for more information. The following attributes must be set for keys used in cryptographic operations: @@ -255,7 +255,7 @@ Key-encapsulation functions .. note:: In some key-encapsulation algorithms, decapsulation failure is not reported with a explicit error code. - Instead, an incorrect, pseudo-random key is output. + Instead, an incorrect, pseudorandom key is output. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: @@ -283,7 +283,7 @@ Key-encapsulation functions .. note:: Some key-encapsulation algorithms do not report an authentication failure explicitly. - Instead, an incorrect, pseudo-random key is output. + Instead, an incorrect, pseudorandom key is output. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -304,7 +304,7 @@ Key-encapsulation functions * Some key-encapsulation algorithms do not authenticate the ciphertext. Manipulated ciphertext will not be detected during decapsulation. - * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudo-random key value. + * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudorandom key value. This prevents disclosing information to an attacker that has manipulated the ciphertext. * Some key-encapsulation algorithms are probablistic, and cannot guarantee that decapsulation will result in an identical key value. @@ -314,7 +314,7 @@ Key-encapsulation functions For key-encapsulation algorithms which involve data padding when computing the ciphertext, the decapsulation algorithm **must not** report a distinct error status if invalid padding is detected. - Instead, it is recommended that the decapsulation fails implicitly when invalid padding is detected, returning a pseudo-random key. + Instead, it is recommended that the decapsulation fails implicitly when invalid padding is detected, returning a pseudorandom key. Support macros -------------- From 742cedb19975485eda10c198f3bc073d0568daca Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 18:31:20 +0000 Subject: [PATCH 09/19] Be clear about key sizes being in bits --- doc/crypto/api/ops/key-encapsulation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index c7aa4253..bceb208c 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -138,7 +138,7 @@ Key-encapsulation functions The following attributes are optional: - * If the key size is nonzero, it must be equal to the size of the shared secret. + * If the key size is nonzero, it must be equal to the size, in bits, of the shared secret. .. note:: This is an input parameter: it is not updated with the final key attributes. @@ -238,7 +238,7 @@ Key-encapsulation functions The following attributes are optional: - * If the key size is nonzero, it must be equal to the size of the shared secret. + * If the key size is nonzero, it must be equal to the size, in bits, of the shared secret. .. note:: This is an input parameter: it is not updated with the final key attributes. From c894eaed9e3ea3737e92f64c0d20e922ae0f8640 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 18:33:18 +0000 Subject: [PATCH 10/19] Add missing error status codes --- doc/crypto/api/ops/key-encapsulation.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index bceb208c..94b60897 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -186,8 +186,13 @@ Key-encapsulation functions The size of the ``ciphertext`` buffer is too small. `PSA_ENCAPSULATE_CIPHERTEXT_SIZE()` or `PSA_ENCAPSULATE_CIPHERTEXT_MAX_SIZE` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE + .. retval:: PSA_ERROR_STORAGE_FAILURE + .. retval:: PSA_ERROR_DATA_CORRUPT + .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_BAD_STATE The library requires initializing by a call to `psa_crypto_init()`. @@ -285,8 +290,13 @@ Key-encapsulation functions Some key-encapsulation algorithms do not report an authentication failure explicitly. Instead, an incorrect, pseudorandom key is output. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE + .. retval:: PSA_ERROR_STORAGE_FAILURE + .. retval:: PSA_ERROR_DATA_CORRUPT + .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_BAD_STATE The library requires initializing by a call to `psa_crypto_init()`. From e8cc973deb6aaa41e0e94831c8c732b868ac2df5 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 23:22:31 +0000 Subject: [PATCH 11/19] Terminology: use 'shared secret key' consistently --- doc/crypto/api/ops/key-encapsulation.rst | 36 ++++++++++++------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 94b60897..d9e47262 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -72,7 +72,7 @@ The key derivation, encryption, and authentication steps are left to the applica * The elliptic curve to use is determined by the key. * The public key part of the input key is used as :math:`Q_V`. * Cofactor ECDH is used to perform the key agreement. - * The shared secret :math:`Z` is output as the shared output key. + * The octet string :math:`Z` is output as the shared secret key. * The ephemeral public key :math:`\overline{R}` is output as the ciphertext. A call to `psa_decapsulate()` carries out steps 2 to 5 of the ECIES decryption process described in `[SEC1]` §5.1.4: @@ -81,12 +81,12 @@ The key derivation, encryption, and authentication steps are left to the applica * The ciphertext is decoded as :math:`\overline{R}`. * The private key of the input key is used as :math:`d_V`. * Cofactor ECDH is used to perform the key agreement. - * The shared secret :math:`Z` is output as the shared output key. + * The octet string :math:`Z` is output as the shared secret key. The ciphertext produced by `PSA_ALG_ECIES_SEC1` is not authenticated. When used in a full ECIES scheme, the authentication of the encrypted message implicitly confirms that the derived keys were identical. - The shared output key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. + The shared secret key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. It must be used as an input to a key derivation operation to produce additional cryptographic keys. .. subsection:: Compatible key types @@ -144,7 +144,7 @@ Key-encapsulation functions 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 shared output key. + On success, an identifier for the newly created shared secret key. `PSA_KEY_ID_NULL` on failure. .. param:: uint8_t * ciphertext Buffer where the ciphertext output is to be written. @@ -161,13 +161,13 @@ Key-encapsulation functions .. retval:: PSA_SUCCESS Success. - The bytes of ``ciphertext`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared output key. + The bytes of ``ciphertext`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared secret key. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: * ``alg`` is not supported or is not a key-encapsulation algorithm. * ``key`` is not supported for use with ``alg``. - * The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. + * The output key attributes in ``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: @@ -175,8 +175,8 @@ Key-encapsulation functions * ``key`` is not a public key or an asymmetric key pair, that is compatible with ``alg``. * The output key attributes in ``attributes`` are not valid: - - The key type is not valid for the shared output key. - - The key size is nonzero, and is not the size of the shared output. + - The key type is not valid for the shared secret. + - 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. @@ -201,8 +201,8 @@ Key-encapsulation functions 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 of the shared secret is dependent on the key-encapsulation algorithm and the type and size of ``key``. - It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. - For some key-encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. + It is recommended that the shared secret key is used as an input to a key derivation operation to produce additional cryptographic keys. + For some key-encapsulation algorithms, the shared secret key is also suitable for use as a key in cryptographic operations such as encryption. Refer to the documentation of individual key-encapsulation algorithms for more information. The output ``ciphertext`` is to be sent to the other participant, who uses the decapsulation key to extract another copy of the shared secret key. @@ -249,14 +249,14 @@ Key-encapsulation functions 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 shared output key. + On success, an identifier for the newly created shared secret key. `PSA_KEY_ID_NULL` on failure. .. return:: psa_status_t .. retval:: PSA_SUCCESS Success. - ``output_key`` contains the identifier for the shared output key. + ``output_key`` contains the identifier for the shared secret key. .. note:: In some key-encapsulation algorithms, decapsulation failure is not reported with a explicit error code. @@ -266,7 +266,7 @@ Key-encapsulation functions * ``alg`` is not supported or is not a key-encapsulation algorithm. * ``key`` is not supported for use with ``alg``. - * The output key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location. + * The output key attributes in ``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: @@ -274,8 +274,8 @@ Key-encapsulation functions * ``key`` is not an asymmetric key pair, that is compatible with ``alg``. * The output key attributes in ``attributes`` are not valid: - - The key type is not valid for the shared output key. - - The key size is nonzero, and is not the size of the shared output. + - The key type is not valid for the shared secret. + - 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. @@ -305,8 +305,8 @@ Key-encapsulation functions 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 of the shared secret is dependent on the key-encapsulation algorithm and the type and size of ``key``. - It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. - For some key-encapsulation algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. + It is recommended that the shared secret key is used as an input to a key derivation operation to produce additional cryptographic keys. + For some key-encapsulation algorithms, the shared secret key is also suitable for use as a key in cryptographic operations such as encryption. Refer to the documentation of individual key-encapsulation algorithms for more information. .. warning:: @@ -318,7 +318,7 @@ Key-encapsulation functions This prevents disclosing information to an attacker that has manipulated the ciphertext. * Some key-encapsulation algorithms are probablistic, and cannot guarantee that decapsulation will result in an identical key value. - It is strongly recommended that application uses the output key in a way that will confirm that the derived keys are identical. + It is strongly recommended that the application uses the output key in a way that will confirm that the derived keys are identical. .. admonition:: Implementation note From 37e3986c9ad64ca90ad1ab5ca1251bf3af0e867a Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 23:29:47 +0000 Subject: [PATCH 12/19] Clarifying the particpants in a KEM --- doc/crypto/api/ops/key-encapsulation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index d9e47262..de284558 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -13,19 +13,19 @@ A key-encapsulation algorithm can be used by two participants to establish a sha The shared secret key can then be used with symmetric-key cryptographic algorithms. Key-encapsulation algorithms are often referred to as 'key-encapsulation mechanisms' or KEMs. -In a key-encapsulation algorithm, one participant generates a key-pair: a private decapsulation key, and a public encapsulation key. -The public encapsulation key is made available to a second participant that needs to establish secure communication with the first participant. -The second participant uses the encapsulation key to generate one copy of a shared secret, and some ciphertext. -The ciphertext is transferred to the first participant, who uses the private decapsulation key to compute another copy of the shared secret. +In a key-encapsulation algorithm, participant A generates a key-pair: a private decapsulation key, and a public encapsulation key. +The public encapsulation key is made available to participant B, who needs to establish secure communication with the participant A. +Participant B uses the encapsulation key to generate one copy of a shared secret, and some ciphertext. +The ciphertext is transferred to participant A, who uses the private decapsulation key to compute another copy of the shared secret. -Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between the participants. +Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between participants A and B. However, some key-encapsulation algorithms result in a uniformly pseudorandom shared secret, which is suitable to be used directly as a cryptographic key. Applications can use the resulting keys for different use cases. For example: -* Encrypting and authenticating a single non-interactive message. -* Securing an interactive communication channel. +* Encrypting and authenticating a single non-interactive message from participant B to participant A. +* Securing an interactive communication channel between participants A and B. .. _key-encapsulation-algorithms: @@ -161,7 +161,7 @@ Key-encapsulation functions .. retval:: PSA_SUCCESS Success. - The bytes of ``ciphertext`` contain the data to be sent to the other participant and ``output_key`` contains the identifier for the shared secret key. + The bytes of ``ciphertext`` contain the data to be sent to the other participant, and ``output_key`` contains the identifier for the shared secret key. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: From 4803420f46dede9ea9f079daafd9145f69d0d7e9 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 23:34:16 +0000 Subject: [PATCH 13/19] Clarified the security of ECIES authentication --- doc/crypto/api/ops/key-encapsulation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index de284558..c7fb6d1b 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -84,7 +84,7 @@ The key derivation, encryption, and authentication steps are left to the applica * The octet string :math:`Z` is output as the shared secret key. The ciphertext produced by `PSA_ALG_ECIES_SEC1` is not authenticated. - When used in a full ECIES scheme, the authentication of the encrypted message implicitly confirms that the derived keys were identical. + In the full ECIES scheme, the authentication of the encrypted message using a key derived from the shared secret provides assurance that the message has not been manipulated. The shared secret key that is produced by `PSA_ALG_ECIES_SEC1` is not suitable for use as an encryption key. It must be used as an input to a key derivation operation to produce additional cryptographic keys. From 3cec851c8070af80afd44b73f9f4033a372b5f36 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 31 Oct 2024 23:49:06 +0000 Subject: [PATCH 14/19] Improved description of potential for mismatched KEM key values --- doc/crypto/api/ops/key-encapsulation.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index c7fb6d1b..f41fade5 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -309,16 +309,19 @@ Key-encapsulation functions For some key-encapsulation algorithms, the shared secret key is also suitable for use as a key in cryptographic operations such as encryption. Refer to the documentation of individual key-encapsulation algorithms for more information. + If the key-encapsulation protocol is executed correctly then, with overwhelming probability, the two copies of the shared secret are identical. + However, the protocol does not protect one participant against the other participant executing it incorrectly, or against a third party modifying data in transit. + .. warning:: - A :code:`PSA_SUCCESS` result from `psa_decapsulate()` does not guarantee that the output key is identical to the key produce by the call to `psa_encapsulate()`. For example: + A :code:`PSA_SUCCESS` result from `psa_decapsulate()` does not guarantee that the output key is identical to the key produced by the call to `psa_encapsulate()`. For example, :code:`PSA_SUCCESS` can be returned with a mismatched shared secret key value in the following situations: - * Some key-encapsulation algorithms do not authenticate the ciphertext. - Manipulated ciphertext will not be detected during decapsulation. - * Some key-encapsulation algorithms report authentication failure implicitly, by returning a pseudorandom key value. - This prevents disclosing information to an attacker that has manipulated the ciphertext. - * Some key-encapsulation algorithms are probablistic, and cannot guarantee that decapsulation will result in an identical key value. + * The key-encapsulation algorithm does not authenticate the ciphertext. + Manipulated or corrupted ciphertext will not be detected during decapsulation. + * The key-encapsulation algorithm reports authentication failure implicitly, by returning a pseudorandom key value. + This is done to prevent disclosing information to an attacker that has manipulated the ciphertext. + * The key-encapsulation algorithm is probablistic, and will *extremely* rarely result in non-identical key values. - It is strongly recommended that the application uses the output key in a way that will confirm that the derived keys are identical. + It is strongly recommended that the application uses the output key in a way that will confirm that the shared secret keys are identical. .. admonition:: Implementation note From 680933fde4dea308cb7428957edb4c2b6f889eff Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 1 Nov 2024 11:37:02 +0000 Subject: [PATCH 15/19] Improve wording in encapsulation usage flags --- doc/crypto/api/keys/policy.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 68d7f067..8b40d71f 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -269,26 +269,29 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. :definition: ((psa_key_usage_t)0x00040000) .. summary:: - Permission to encapsulate new keys. + Permission to perform key encapsulation with the key. - This flag is required to encapsulate new keys to send to a counter party. + This flag is required to use the key in a key-encapsulation operation. - This flag must be present on public keys used with the following APIs: + This flag must be present on keys used with the following APIs: * `psa_encapsulate()` + For a key pair, this concerns the public key. + .. macro:: PSA_KEY_USAGE_DECAPSULATE :definition: ((psa_key_usage_t)0x00080000) .. summary:: - Permission to decapsulate an encapsulated key. + Permission to perform key decapsulation with the key. - This flag is required to decapsulate the data obtained from a counter party. + This flag is required to use the key in a key-decapsulation operation. - This flag must be present on private keys used with the following APIs: + This flag must be present on keys used with the following APIs: * `psa_decapsulate()` + For a key pair, this concerns the private key. .. function:: psa_set_key_usage_flags From be852a75673e419c1316ca726a1607373a2b0aae Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 1 Nov 2024 11:44:00 +0000 Subject: [PATCH 16/19] More missing error status codes * Errors related to invalid key handles or policy failure * Errors related to creating a persistent key --- doc/crypto/api/ops/key-encapsulation.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index f41fade5..6b8aeab2 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -162,6 +162,15 @@ Key-encapsulation functions .. retval:: PSA_SUCCESS Success. The bytes of ``ciphertext`` contain the data to be sent to the other participant, and ``output_key`` contains the identifier for the shared secret key. + .. retval:: PSA_ERROR_INVALID_HANDLE + ``key`` is not a valid key identifier. + .. retval:: PSA_ERROR_NOT_PERMITTED + The following conditions can result in this error: + + * ``key`` does not have the `PSA_KEY_USAGE_ENCAPSULATE` flag, or it does not permit the requested algorithm. + * The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy. + .. retval:: PSA_ERROR_ALREADY_EXISTS + This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: @@ -261,6 +270,15 @@ Key-encapsulation functions .. note:: In some key-encapsulation algorithms, decapsulation failure is not reported with a explicit error code. Instead, an incorrect, pseudorandom key is output. + .. retval:: PSA_ERROR_INVALID_HANDLE + ``key`` is not a valid key identifier. + .. retval:: PSA_ERROR_NOT_PERMITTED + The following conditions can result in this error: + + * ``key`` does not have the `PSA_KEY_USAGE_DECAPSULATE` flag, or it does not permit the requested algorithm. + * The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy. + .. retval:: PSA_ERROR_ALREADY_EXISTS + This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: From ec3e51116598cfcd1cc5a9d21111dfcdf609e8d6 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 1 Nov 2024 11:49:52 +0000 Subject: [PATCH 17/19] Fixup: missed some of the ciphertext-related changes --- doc/crypto/api.db/psa/crypto.h | 14 +++++++------- doc/crypto/api/ops/key-encapsulation.rst | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 508b5ef0..ea84e7cc 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -223,8 +223,8 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22) #define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b) #define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42) -#define PSA_ENCAPSULATION_MAX_SIZE /* implementation-defined value */ -#define PSA_ENCAPSULATION_SIZE(key_type, key_bits, alg) \ +#define PSA_ENCAPSULATE_CIPHERTEXT_MAX_SIZE /* implementation-defined value */ +#define PSA_ENCAPSULATE_CIPHERTEXT_SIZE(key_type, key_bits, alg) \ /* implementation-defined value */ #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148) #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150) @@ -507,8 +507,8 @@ psa_status_t psa_copy_key(psa_key_id_t source_key, psa_status_t psa_crypto_init(void); psa_status_t psa_decapsulate(psa_key_id_t key, psa_algorithm_t alg, - const uint8_t * encapsulation, - size_t encapsulation_length, + const uint8_t * ciphertext, + size_t ciphertext_length, const psa_key_attributes_t * attributes, psa_key_id_t * output_key); psa_status_t psa_destroy_key(psa_key_id_t key); @@ -516,9 +516,9 @@ psa_status_t psa_encapsulate(psa_key_id_t key, psa_algorithm_t alg, const psa_key_attributes_t * attributes, psa_key_id_t * output_key, - uint8_t * encapsulation, - size_t encapsulation_size, - size_t * encapsulation_length); + uint8_t * ciphertext, + size_t ciphertext_size, + size_t * ciphertext_length); psa_status_t psa_export_key(psa_key_id_t key, uint8_t * data, size_t data_size, diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 6b8aeab2..fe4e5c28 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -148,7 +148,7 @@ Key-encapsulation functions `PSA_KEY_ID_NULL` on failure. .. param:: uint8_t * ciphertext Buffer where the ciphertext output is to be written. - .. param:: size_t encapsulation_size + .. param:: size_t ciphertext_size Size of the ``ciphertext`` buffer in bytes. This must be appropriate for the selected algorithm and key: @@ -229,7 +229,7 @@ Key-encapsulation functions The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. param:: const uint8_t * ciphertext The ciphertext received from the other participant. - .. param:: size_t encapsulation_length + .. param:: size_t ciphertext_length Size of the ``ciphertext`` buffer in bytes. .. param:: const psa_key_attributes_t * attributes The attributes for the output key. From ac0282a33165df0e9d7be30017f50815ba63358e Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 1 Nov 2024 11:51:05 +0000 Subject: [PATCH 18/19] Suggestion: use USAGE_ENCRYPT/DECRYPT instead of adding USAGE_ENCAPSULATE/DECAPSULATE --- doc/crypto/api.db/psa/crypto.h | 2 -- doc/crypto/api/keys/policy.rst | 40 ++++-------------------- doc/crypto/api/ops/key-encapsulation.rst | 8 ++--- 3 files changed, 10 insertions(+), 40 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index ea84e7cc..bd6ba5e5 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -329,10 +329,8 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007) #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) -#define PSA_KEY_USAGE_DECAPSULATE ((psa_key_usage_t)0x00080000) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) -#define PSA_KEY_USAGE_ENCAPSULATE ((psa_key_usage_t)0x00040000) #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 8b40d71f..45b83ea6 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -96,8 +96,6 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. - `PSA_KEY_USAGE_VERIFY_HASH` - `PSA_KEY_USAGE_DERIVE` - `PSA_KEY_USAGE_VERIFY_DERIVATION` - - `PSA_KEY_USAGE_ENCAPSULATE` - - `PSA_KEY_USAGE_DECAPSULATE` .. typedef:: uint32_t psa_key_usage_t @@ -153,15 +151,16 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. :definition: ((psa_key_usage_t)0x00000100) .. summary:: - Permission to encrypt a message with the key. + Permission to encrypt a message, or perform key encapsulation, with the key. - This flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, or in an asymmetric encryption operation. The flag must be present on keys used with the following APIs: + This flag is required to use the key in a symmetric encryption operation, in an AEAD encryption-and-authentication operation, in an asymmetric encryption operation, or in a key-encapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_encrypt()` * `psa_cipher_encrypt_setup()` * `psa_aead_encrypt()` * `psa_aead_encrypt_setup()` * `psa_asymmetric_encrypt()` + * `psa_encapsulate()` For a key pair, this concerns the public key. @@ -169,15 +168,16 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`. :definition: ((psa_key_usage_t)0x00000200) .. summary:: - Permission to decrypt a message with the key. + Permission to decrypt a message, or perform key decapsulation, with the key. - This flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, or in an asymmetric decryption operation. The flag must be present on keys used with the following APIs: + This flag is required to use the key in a symmetric decryption operation, in an AEAD decryption-and-verification operation, in an asymmetric decryption operation, or in a key-decapsulation operation. The flag must be present on keys used with the following APIs: * `psa_cipher_decrypt()` * `psa_cipher_decrypt_setup()` * `psa_aead_decrypt()` * `psa_aead_decrypt_setup()` * `psa_asymmetric_decrypt()` + * `psa_decapsulate()` For a key pair, this concerns the private key. @@ -265,34 +265,6 @@ 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)0x00040000) - - .. summary:: - Permission to perform key encapsulation with the key. - - This flag is required to use the key in a key-encapsulation operation. - - This flag must be present on keys used with the following APIs: - - * `psa_encapsulate()` - - For a key pair, this concerns the public key. - -.. macro:: PSA_KEY_USAGE_DECAPSULATE - :definition: ((psa_key_usage_t)0x00080000) - - .. summary:: - Permission to perform key decapsulation with the key. - - This flag is required to use the key in a key-decapsulation operation. - - This flag must be present on keys used with the following APIs: - - * `psa_decapsulate()` - - For a key pair, this concerns the private key. - .. function:: psa_set_key_usage_flags .. summary:: diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index fe4e5c28..6af220b4 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -114,7 +114,7 @@ Key-encapsulation functions .. param:: psa_key_id_t key Identifier of the key to use for the encapsulation. It must be a public key or an asymmetric key pair. - It must permit the usage `PSA_KEY_USAGE_ENCAPSULATE`. + It must permit the usage `PSA_KEY_USAGE_ENCRYPT`. .. param:: psa_algorithm_t alg The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. param:: const psa_key_attributes_t * attributes @@ -167,7 +167,7 @@ Key-encapsulation functions .. retval:: PSA_ERROR_NOT_PERMITTED The following conditions can result in this error: - * ``key`` does not have the `PSA_KEY_USAGE_ENCAPSULATE` flag, or it does not permit the requested algorithm. + * ``key`` does not have the `PSA_KEY_USAGE_ENCRYPT` flag, or it does not permit the requested algorithm. * The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy. .. retval:: PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. @@ -224,7 +224,7 @@ Key-encapsulation functions .. param:: psa_key_id_t key Identifier of the key to use for the decapsulation. It must be an asymmetric key pair. - It must permit the usage `PSA_KEY_USAGE_DECAPSULATE`. + It must permit the usage `PSA_KEY_USAGE_DECRYPT`. .. param:: psa_algorithm_t alg The key-encapsulation algorithm to use: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_KEY_ENCAPSULATION(alg)` is true. .. param:: const uint8_t * ciphertext @@ -275,7 +275,7 @@ Key-encapsulation functions .. retval:: PSA_ERROR_NOT_PERMITTED The following conditions can result in this error: - * ``key`` does not have the `PSA_KEY_USAGE_DECAPSULATE` flag, or it does not permit the requested algorithm. + * ``key`` does not have the `PSA_KEY_USAGE_DECRYPT` flag, or it does not permit the requested algorithm. * The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy. .. retval:: PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. From e99d9e07c9facaa09a29550824356f399a0c455c Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 4 Nov 2024 15:40:10 +0000 Subject: [PATCH 19/19] Improve description of key encapsulation --- doc/crypto/api/ops/key-encapsulation.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 6af220b4..8fd3af80 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -13,10 +13,13 @@ A key-encapsulation algorithm can be used by two participants to establish a sha The shared secret key can then be used with symmetric-key cryptographic algorithms. Key-encapsulation algorithms are often referred to as 'key-encapsulation mechanisms' or KEMs. -In a key-encapsulation algorithm, participant A generates a key-pair: a private decapsulation key, and a public encapsulation key. -The public encapsulation key is made available to participant B, who needs to establish secure communication with the participant A. -Participant B uses the encapsulation key to generate one copy of a shared secret, and some ciphertext. -The ciphertext is transferred to participant A, who uses the private decapsulation key to compute another copy of the shared secret. +In a key-encapsulation algorithm, participants A and B establish a shared secret as follows: + +1. Participant A generates a key-pair: a private decapsulation key, and a public encapsulation key. +#. The public encapsulation key is made available to participant B. +#. Participant B uses the encapsulation key to generate one copy of a shared secret, and some ciphertext. +#. The ciphertext is transferred to participant A. +#. Participant A uses the private decapsulation key to compute another copy of the shared secret. Typically, the shared secret is used as input to a key-derivation function, to create keys for secure communication between participants A and B. However, some key-encapsulation algorithms result in a uniformly pseudorandom shared secret, which is suitable to be used directly as a cryptographic key.