Module Latice Keys

doc/crypto/api/keys/policy.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. 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

@@ -129,7 +129,7 @@ Symmetric keys
     It is :scterm:`implementation defined` whether an HMAC key that is longer than the hash block size is supported.
 
     If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key.
-
+   
     .. note::
 
         :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes.
@@ -408,6 +408,7 @@ Symmetric keys
         | `PSA_ALG_STREAM_CIPHER`
         | `PSA_ALG_CHACHA20_POLY1305`
 
+
 .. macro:: PSA_KEY_TYPE_XCHACHA20
     :definition: ((psa_key_type_t)0x2007)
 
@@ -425,7 +426,6 @@ Symmetric keys
         | `PSA_ALG_STREAM_CIPHER`
         | `PSA_ALG_XCHACHA20_POLY1305`
 
-
 .. _asymmetric-keys:
 
 RSA keys
@@ -502,7 +502,7 @@ Elliptic Curve keys
     .. summary::
         Elliptic curve key pair: both the private and public key.
 
-    The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details.
+    The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:``q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details.
 
     .. param:: curve
         A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used.
@@ -920,6 +920,143 @@ Diffie Hellman keys
     .. return:: psa_dh_family_t
         The Diffie-Hellman group family id, if ``type`` is a supported Diffie-Hellman key. Unspecified if ``type`` is not a supported Diffie-Hellman key.
 
+Module Lattice keys
+-------------------
+
+PSA supports Module Lattice Cryptography as defined in :cite:`FIPS203` and :cite:`FIPS204`. 
+
+There are two related, but separate algorithms a key encapsulation method, ML-KEM and a signature method ML-DSA. 
+
+.. macro:: PSA_KEY_TYPE_MLKEM_KEY_PAIR
+    :definition: ((psa_key_type_t)0xy001)
+
+    .. summary::
+        MLKEM key pair: contains both the decapsulation and encapsulation keys.
+        PSA Crypto treats decapsulation keys as private keys and encapsulation keys as public keys. 
+
+        The size of an ML-KEM key is specified by the numeric part of the parameter set identifier defined in FIPS 203.
+
+        The parameter sets refer to the key strength, the actual size of the key
+
+        .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM
+           :header-rows: 1
+
+           * - Size
+             - Parameter Set
+             - Encapsulation key
+             - Decapsulation key 
+             - Ciphertext
+
+           * - 512
+             - ML-KEM-512
+             - 800
+             - 1632
+             - 768
+
+           * - 768
+             - ML-KEM-768
+             - 1184
+             - 2400
+             - 1088
+
+           * - 1024
+             - ML-KEM-1024
+             - 1568
+             - 3168
+             - 1568
+
+        In all cases the shared secret produced is 32-bytes, 256-bits long.
+        The shared secret can be used directly or passed to a PRF to derive further keys. 
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_MLKEM`
+
+.. macro:: PSA_KEY_TYPE_ML_KEM _PUBLIC_KEY
+    :definition: ((psa_key_type_t)0x4001)
+
+    .. summary::
+        ML-KEM public key.
+
+    The size of an ML-KEM key is the numeric part of the parameter set identifier.
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_MLKEM` (encapsulation only)
+        | 
+.. macro:: PSA_KEY_TYPE_IS_MLKEM
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether a key type is an ML-KEM key. This includes both key pairs and public keys.
+
+    .. param:: type
+        A key type: a value of type `psa_key_type_t`.
+
+.. macro:: PSA_KEY_TYPE_MLDSA_KEY_PAIR
+    :definition: ((psa_key_type_t)0xy001)
+
+    .. summary::
+        An ML_DSA key pair: contains both the public and private keys.
+
+        The size of an ML-DSA key is specified by the numeric part of the parameter set identifier defined in FIPS 203.
+
+        The parameter sets refer to the dimensions of the matrix A, and do not directly define key size.
+
+        .. list-table:: Sizes (in bytes) of keys and cipher texts for ML-KEM
+           :header-rows: 1
+
+           * - Size
+             - Parameter Set
+             - Private key
+             - Public key 
+             - Signature
+
+           * - 44
+             - ML-DSA-44
+             - 2560
+             - 1312
+             - 2420
+
+           * - 65
+             - ML-DSA-65
+             - 4032
+             - 1952
+             - 3309
+
+           * - 87
+             - ML-DSA-87
+             - 4896
+             - 2592
+             - 4627
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_MLDSA_SIGN`
+
+.. macro:: PSA_KEY_TYPE_MLDSA_PUBLIC_KEY
+    :definition: ((psa_key_type_t)0xy001)
+
+    .. summary::
+        A ML-DSA public key.
+
+        The size of an ML-DSA key is specified by the numeric part of the parameter set identifier defined in FIPS 203.
+
+        The parameter sets refer to the key strength, the actual size of the key 
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_MLDSA_SIGN` (verification only)
+
+.. macro:: PSA_KEY_TYPE_IS_MLDSA
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether a key type is an ML-SIG key. This includes both key pairs and public keys.
+
+    .. param:: type
+        A key type: a value of type `psa_key_type_t`.
+
 Attribute accessors
 -------------------
 

doc/crypto/api/ops/algorithms.rst

@@ -23,6 +23,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope
 *   :secref:`sign-algorithms`
 *   :secref:`asymmetric-encryption-algorithms`
 *   :secref:`key-agreement-algorithms`
+*   :secref:`encapsulation-algorithms`
 
 
 Algorithm encoding
@@ -227,3 +228,4 @@ Algorithm categories
     *   `PSA_ALG_TLS12_PRF()`
     *   `PSA_ALG_TLS12_PSK_TO_MS()`
     *   `PSA_ALG_PBKDF2_HMAC()`
+    *   `PSA_ALG_MLDSA_SIGN`