FIPS 204 - API for Module Lattice-based signatures (ML-DSA)

doc/crypto/api.db/psa/crypto.h

@@ -72,6 +72,9 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)
 #define PSA_ALG_CTR ((psa_algorithm_t)0x04c01000)
 #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) /* specification-defined value */
+#define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \
+    /* specification-defined value */
+#define PSA_ALG_DETERMINISTIC_ML_DSA ((psa_algorithm_t) 0x06004500)
 #define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t)0x04404400)
 #define PSA_ALG_ECDH ((psa_algorithm_t)0x09020000)
 #define PSA_ALG_ECDSA(hash_alg) /* specification-defined value */
@@ -82,6 +85,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_FULL_LENGTH_MAC(mac_alg) /* specification-defined value */
 #define PSA_ALG_GCM ((psa_algorithm_t)0x05500200)
 #define PSA_ALG_GET_HASH(alg) /* specification-defined value */
+#define PSA_ALG_HASH_ML_DSA(hash_alg) /* specification-defined value */
 #define PSA_ALG_HKDF(hash_alg) /* specification-defined value */
 #define PSA_ALG_HKDF_EXPAND(hash_alg) /* specification-defined value */
 #define PSA_ALG_HKDF_EXTRACT(hash_alg) /* specification-defined value */
@@ -92,12 +96,16 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */
 #define PSA_ALG_IS_CIPHER(alg) /* specification-defined value */
 #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */
+#define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(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_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 */
 #define PSA_ALG_IS_HASH_EDDSA(alg) /* specification-defined value */
+#define PSA_ALG_IS_HASH_ML_DSA(alg) /* specification-defined value */
+#define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) /* specification-defined value */
 #define PSA_ALG_IS_HKDF(alg) /* specification-defined value */
 #define PSA_ALG_IS_HKDF_EXPAND(alg) /* specification-defined value */
 #define PSA_ALG_IS_HKDF_EXTRACT(alg) /* specification-defined value */
@@ -108,6 +116,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \
     /* specification-defined value */
 #define PSA_ALG_IS_MAC(alg) /* specification-defined value */
+#define PSA_ALG_IS_ML_DSA(alg) /* specification-defined value */
 #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */
 #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */
 #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */
@@ -140,6 +149,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)
 #define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002)
 #define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003)
+#define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400)
 #define PSA_ALG_NONE ((psa_algorithm_t)0)
 #define PSA_ALG_OFB ((psa_algorithm_t)0x04c01200)
 #define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)
@@ -156,6 +166,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011)
 #define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)
 #define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)
+#define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016)
 #define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015)
 #define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005)
 #define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008)
@@ -297,6 +308,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */
+#define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_SPAKE2P(type) /* specification-defined value */
@@ -307,6 +319,8 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) /* specification-defined value */
 #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \
     /* specification-defined value */
+#define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
+#define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
 #define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000)
 #define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203)
 #define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205)

doc/crypto/api/keys/types.rst

@@ -1165,6 +1165,136 @@ The curve type affects the key format, the key derivation procedure, and the alg
     .. return:: psa_ecc_family_t
         The elliptic curve family id, if ``type`` is a supported elliptic curve key. Unspecified if ``type`` is not a supported elliptic curve key.
 
+.. _ml-dsa-keys:
+
+Module Lattice-based Signature keys
+-----------------------------------
+
+The |API| supports Module Lattice-based digital signatures (ML-DSA), as defined in :cite-title:`FIPS204`.
+
+.. macro:: PSA_KEY_TYPE_ML_DSA_KEY_PAIR
+    :definition: ((psa_key_type_t)0x7002)
+
+    .. summary::
+        ML-DSA key pair: both the private and public key.
+
+    The key attribute size of an ML-DSA key is the numeric ML-DSA parameter-set identifier defined in `[FIPS204]`.
+    The values are based on the dimensions of the matrix :math:`A`, and do not directly define the key size in bytes:
+
+    *   ML-DSA-44 : ``key_bits = 44``
+    *   ML-DSA-65 : ``key_bits = 65``
+    *   ML-DSA-87 : ``key_bits = 87``
+
+    See also §4 in `[FIPS204]`.
+
+    .. subsection:: Compatible algorithms
+
+        .. hlist::
+
+            *   `PSA_ALG_ML_DSA`
+            *   `PSA_ALG_HASH_ML_DSA`
+            *   `PSA_ALG_DETERMINISTIC_ML_DSA`
+            *   `PSA_ALG_DETERMINISTIC_HASH_ML_DSA`
+
+    .. subsection:: Key format
+
+        .. warning::
+
+            The key format may change in a final version of this API.
+            The standardization of exchange formats for ML-DSA public and private keys is in progress, but final documents have not been published.
+            See :cite-title:`LAMPS-MLDSA`.
+
+            The current proposed format is based on the current expected outcome of that process.
+
+        An ML-DSA key pair is the :math:`(pk,sk)` pair of public key and secret key, which are generated from a secret 32-byte seed, :math:`\xi`. See `[FIPS204]` §5.1.
+
+        The data format for import and export of the key pair is the 32-byte seed :math:`\xi`.
+
+        .. rationale::
+
+            The IETF working group responsible for defining the format of the ML-DSA keys in *SubjectPublicKeyInfo* and *OneAsymmetricKey* structures is discussing the formats at present (September 2024), with the current consensus to using just the seed value as the private key, for the following reasons:
+
+            *   ML-DSA key-pairs are several kB in size, but can be recomputed efficiently from the initial 32-byte seed.
+            *   There is no need to validate an imported ML-DSA private key --- every 32-byte seed values is valid.
+            *   The public key cannot be derived from the secret key, so a key pair must store both the secret key and the public key.
+                The size of the key pair depends on the ML-DSA parameter set as follows:
+
+                .. csv-table::
+                    :align: left
+                    :header-rows: 1
+
+                    Parameter set, Key-pair size in bytes
+                    ML-DSA-44, 3872
+                    ML-DSA-65, 5984
+                    ML-DSA-87, 7488
+
+            *   It is better for the standard to choose a single format to improve interoperability.
+
+        See `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
+
+        .. admonition:: Implementation note
+
+            An implementation can optionally compute and store the :math:`(pk,sk)` values, to accelerate operations that use the key.
+            It is recommended that an implementation retains the seed :math:`\xi` with the key pair, in order to export the key, or copy the key to a different location.
+
+    .. subsection:: Key derivation
+
+        A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the 32-byte ML-DSA key-pair seed, :math:`xi`.
+        The key-pair :math:`(pk, sk)` is generated from the seed as defined by ``ML-DSA.KeyGen_internal()`` in `[FIPS204]` §6.1.
+
+        .. admonition:: Implementation note
+
+            It is :scterm:`implementation defined` whether the seed :math:`xi` is expanded to :math:`(pk, sk)` at the point of derivation, or only just before the key is used.
+
+.. macro:: PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY
+    :definition: ((psa_key_type_t)0x4002)
+
+    .. summary::
+        ML-DSA public key.
+
+    The key attribute size of an ML-DSA public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ML_DSA_KEY_PAIR`.
+
+    .. subsection:: Compatible algorithms
+
+        .. hlist::
+
+            *   `PSA_ALG_ML_DSA`
+            *   `PSA_ALG_HASH_ML_DSA`
+            *   `PSA_ALG_DETERMINISTIC_ML_DSA`
+            *   `PSA_ALG_DETERMINISTIC_HASH_ML_DSA`
+
+    .. subsection:: Key format
+
+        .. warning::
+
+            The key format may change in a final version of this API.
+            The standardization of exchange formats for ML-DSA public and private keys is in progress, but final documents have not been published.
+            See :cite-title:`LAMPS-MLDSA`.
+
+            The current proposed format is based on the current expected outcome of that process.
+
+        An ML-DSA public key is the :math:`pk` output of ``ML-DSA.KeyGen()``, defined in `[FIPS204]` §5.1.
+
+        The size of the public key depends on the ML-DSA parameter set as follows:
+
+        .. csv-table::
+            :align: left
+            :header-rows: 1
+
+            Parameter set, Public-key size in bytes
+            ML-DSA-44, 1312
+            ML-DSA-65, 1952
+            ML-DSA-87, 2592
+
+.. macro:: PSA_KEY_TYPE_IS_ML_DSA
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether a key type is an ML-DSA key, either a key pair or a public key.
+
+    .. param:: type
+        A key type: a value of type `psa_key_type_t`.
+
 .. _dh-keys:
 
 Diffie Hellman keys

doc/crypto/api/ops/algorithms.rst

@@ -233,7 +233,9 @@ Support macros
     The following composite algorithms require a hash algorithm:
 
     *   `PSA_ALG_DETERMINISTIC_ECDSA()`
+    *   `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`
     *   `PSA_ALG_ECDSA()`
+    *   `PSA_ALG_HASH_ML_DSA()`
     *   `PSA_ALG_HKDF()`
     *   `PSA_ALG_HKDF_EXPAND()`
     *   `PSA_ALG_HKDF_EXTRACT()`

doc/crypto/api/ops/hash.rst

@@ -178,13 +178,26 @@ Hash algorithms
 
     SHA3-512 is defined in :cite:`FIPS202`.
 
+.. macro:: PSA_ALG_SHAKE128_256
+    :definition: ((psa_algorithm_t)0x02000016)
+
+    .. summary::
+        The first 256 bits (32 bytes) of the SHAKE128 output.
+
+    This can be used as pre-hashing for ML-DSA (see `PSA_ALG_HASH_ML_DSA()`).
+
+    SHAKE128 is defined in :cite:`FIPS202`.
+
+    .. note::
+        For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-256 is recommended. SHA3-256 has the same output size, and a theoretically higher security strength.
+
 .. macro:: PSA_ALG_SHAKE256_512
     :definition: ((psa_algorithm_t)0x02000015)
 
     .. summary::
         The first 512 bits (64 bytes) of the SHAKE256 output.
 
-    This is the prehashing for Ed448ph (see `PSA_ALG_ED448PH`).
+    This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`), and can be used as pre-hashing for ML-DSA (see `PSA_ALG_HASH_ML_DSA()`).
 
     SHAKE256 is defined in :cite:`FIPS202`.