Encapsulation and ECIES (v2)

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)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)
@@ -107,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 */
@@ -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_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)
 #define PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE /* implementation-defined value */
@@ -498,7 +503,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,
+                             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);
+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 * 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,

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:

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
 

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
 

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.
 

doc/crypto/api/keys/policy.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <[email protected]>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. header:: psa/crypto
@@ -86,7 +86,16 @@ 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`
 
 .. typedef:: uint32_t psa_key_usage_t
 
@@ -142,31 +151,33 @@ 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.
 
 .. macro:: PSA_KEY_USAGE_DECRYPT
     :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.
 

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,16 +926,23 @@ 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`
 
                     `PSA_ALG_ECDSA`
 
                     `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`
 

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:`key-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_KEY_ENCAPSULATION
+    :definition: /* specification-defined value */
+
+    .. summary::
+        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 a key-encapsulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
+
+    See :secref:`key-encapsulation-algorithms` for a list of defined key-encapsulation algorithms.
+
 Support macros
 --------------
 

doc/crypto/api/ops/index.rst

@@ -18,5 +18,6 @@ Cryptographic operation reference
     signature
     pk-encryption
     key-agreement
+    key-encapsulation
     pake
     rng