Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
athoelke wants to merge 13 commits into from
Closed

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
3263b68
Define key types and algorithms for FIPS 204 ML-DSA
athoelke Sep 23, 2024
01fa88c
Use the seed as the ML-DSA key pair export format.
athoelke Sep 25, 2024
a6993f9
Do not group ML-DSA keys and ML-KEM keys together.
athoelke Sep 25, 2024
ac438ff
Fix spelling
athoelke Sep 25, 2024
a747d19
Treat hedged/deterministic ML-DSA verification algorithms as equivale…
athoelke Sep 25, 2024
2345aae
Provide rationale for distinct hedged/deterministic algorithms
athoelke Sep 25, 2024
b757c94
Reflect the algorithm distinction between ML-DSA and HashML-DSA
athoelke Sep 25, 2024
30915a4
Correct algorithm summary text
athoelke Sep 25, 2024
809eb45
fixup: missing change in example macro implementations
athoelke Sep 26, 2024
ce5a8fd
Add FIPS204 recommendations for algorithm selection
athoelke Sep 26, 2024
70d06a7
Clarification on ML-DSA deterministic vs hedged
athoelke Sep 30, 2024
c724f7a
Add warning about ongoing standardization of ML-DSA key formats
athoelke Oct 1, 2024
229d018
Provide reference to IETF LAMPS draft for ML-DSA key formats
athoelke Oct 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions doc/crypto/api.db/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand All @@ -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 */
Expand All @@ -92,12 +96,14 @@ 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_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_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 */
Expand All @@ -108,9 +114,12 @@ 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_PURE_ML_DSA(alg) /* specification-defined value */
#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */
#define PSA_ALG_IS_RANDOMIZED_ML_DSA(alg) /* specification-defined value */
#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \
PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg)
#define PSA_ALG_IS_RSA_OAEP(alg) /* specification-defined value */
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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 */
Expand All @@ -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)
Expand Down
117 changes: 117 additions & 0 deletions doc/crypto/api/keys/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1165,6 +1165,123 @@ 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-keys:

Module Lattice keys
-------------------

The |API| supports Module Lattice cryptography as defined in :cite-title:`FIPS203` and :cite-title:`FIPS204`.

There are two related, but separate, algorithms:

* A key encapsulation method, ML-KEM.
* A signature method, ML-DSA.

These algorithms have distinct asymmetric key types.

.. 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`

Copy link
Contributor

@MarcusJGStreets MarcusJGStreets Sep 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to add a note on hedged versus deterministic here. Perhaps:

.. admonition:: Note

FIPS 204 defines the "hedged" and deterministic versions. The hedged version provides message secrecy and some protection against side-channels. FIPS 204 recommends that users should use the hedged version if either of these issues are a concern. The deterministic variant should only be used if the implementation does not include any source of randomness.

.. admonition:: Implementation note

FIPS 204 recommends that implementations use an approved random number generator to provide the random value in the hedged version. However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant.

Copy link
Contributor Author

@athoelke athoelke Sep 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that putting it here, with the key types is the right place - these should be with the algorithms. Perhaps this text would work well in the ML-DSA algorithm overview where it discusses Hedged and Deterministic variants?

I would leave the warning (from the last commit) in the description of PSA_ALG_DETERMINISTIC_ML_DSA.

.. subsection:: Key format

.. todo::
Decide if the default ML-DSA key-pair format is the 32-byte seed :math:`\xi`, or the :math:`(pk,sk)` tuple (which is 3.8kB - 7.4kB in size).

The seed cannot be recomputed from the (pk, sk) pair.
If the seed is the default format, then importing a (pk, sk) pair results in a key that cannot be exported in the default format.

I suspect this means that the default export format should be the (pk, sk) pair.
The API permits implementation storage as a seed (for internally generated keys), and the API could provide an alternative format or format option to export/import the seed instead of the (pk, sk) pair (for an implementation and key-pair that still retain the generating seed).

An ML-DSA key pair is the :math:`(pk,sk)` pair of public key and secret key.

The data format for import and export of the key-pair is the concatenation of the public key and secret keys, :math:`pk\ ||\ sk`, where :math:`pk` and :math:`sk` are the octet strings returned by the ``ML-DSA.KeyGen()`` operation defined in `[FIPS204]` §5.1.

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

See `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.

.. subsection:: Key derivation

:issue:`TBD`

.. todo::

As ML-DSA keys are generated from a 32-byte seed, it would be very straight-forward to enable key-derivation of an ML-DSA key pair as part of a KDF.

However, this is not described anywhere as an expected use case with ML-DSA.

.. 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

An ML-DSA public key is the :math:`pk` output of the ``ML-DSA.KeyGen()`` operation 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
Expand Down
2 changes: 2 additions & 0 deletions doc/crypto/api/ops/algorithms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()`
Expand Down
15 changes: 14 additions & 1 deletion doc/crypto/api/ops/hash.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
Loading