Encapsulation

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
@@ -250,6 +250,31 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
 
     If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key derivation operation, then it permits calling `psa_key_derivation_verify_bytes()` or `psa_key_derivation_verify_key()` at the end of the operation.
 
+.. macro:: PSA_KEY_USAGE_ENCAPSULATE
+    :definition: ((psa_key_usage_t)0x00010000)
+
+    .. summary::
+        Permission to encapsulate new keys.
+
+    This flag is required to encapsulate new keys to send to a counter party.
+
+    This flag must be present on public keys used with the following APIs:
+
+    *   `psa_encapsulate()`
+
+.. macro:: PSA_KEY_USAGE_DECAPSULATE
+    :definition: ((psa_key_usage_t)0x00020000)
+
+    .. summary::
+        Permission to decapsulate an encapsulated key.
+
+    This flag is required to decapsulate a key buffer obtained from a counter party.
+
+    This flag must be present on private keys used with the following APIs:
+
+    *   `psa_decapsulate()`
+
+
 .. function:: psa_set_key_usage_flags
 
     .. summary::

doc/crypto/api/keys/types.rst

@@ -1482,6 +1482,80 @@ SPAKE2+ keys
     .. return:: psa_ecc_family_t
         The elliptic curve family id, if ``type`` is a supported SPAKE2+ key. Unspecified if ``type`` is not a supported SPAKE2+ key.
 
+
+Module Lattice-based Key Encapsulation keys
+-------------------------------------------
+
+
+The |API| supports Module Lattice-based Key Encapsulation as defined in :cite:`FIPS203`. 
+
+.. macro:: PSA_KEY_TYPE_ML_KEM_KEY_PAIR
+    :definition: ((psa_key_type_t)0x7004)
+
+    .. summary::
+        ML-KEM key pair: contains both the decapsulation and encapsulation keys.
+
+    The |API| treats decapsulation keys as private keys and encapsulation keys as public keys. 
+
+    The key attribute size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in :CITE:`FIPS203`.
+
+    The parameter set identifiers refer to the key strength, and not to the actual size of the key, the key and ciphertext sizes are given in the following table. 
+
+    .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM
+       :header-rows: 1
+
+       * - Key Attribute Size
+         - Parameter Set
+         - Encapsulation key
+         - Decapsulation key 
+         - Ciphertext
+
+       * - 512
+         - ML-KEM-512
+         - 800
+         - 1632
+         - 768
+
+       * - 768
+         - ML-KEM-768
+         - 1184
+         - 2400
+         - 1088
+
+       * - 1024
+         - ML-KEM-1024
+         - 1568
+         - 3168
+         - 1568
+
+    In all cases the shared secret produced is 32-bytes, 256-bits long.
+    The shared secret can be used directly or passed to a PRF to derive further keys. 
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_ML_KEM`
+
+.. macro:: PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY
+    :definition: ((psa_key_type_t)0x4004)
+
+    .. summary::
+        ML-KEM public key.
+
+    The size of an ML-KEM key is the numeric part of the parameter set identifier.
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_ML_KEM` (encapsulation only)
+
+.. macro:: PSA_KEY_TYPE_IS_ML_KEM
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether a key type is an ML-KEM key. This includes both key pairs and public keys.
+
+    .. param:: type
+        A key type: a value of type `psa_key_type_t`.
+
 Attribute accessors
 -------------------
 

doc/crypto/api/ops/algorithms.rst

@@ -24,6 +24,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope
 *   :secref:`asymmetric-encryption-algorithms`
 *   :secref:`key-agreement-algorithms`
 *   :secref:`pake`
+*   :secref:`encapsulation-algorithms`
 
 
 Algorithm encoding
@@ -193,6 +194,20 @@ Algorithm categories
         ``1`` if ``alg`` is a password-authenticated key exchange (PAKE) algorithm, ``0`` otherwise.
         This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
 
+.. macro:: PSA_ALG_IS_ENCAPSULATION
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether the specified algorithm is an encapsulation algorithm.
+
+    .. param:: alg
+        An algorithm identifier: a value of type `psa_algorithm_t`.
+
+    .. return::
+        ``1`` if ``alg`` is an encapsuulation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
+
+    See :secref:`encapsulation-algorithms` for a list of defined key derivation algorithms.
+
 Support macros
 --------------