2.3 Module Lattice-based signatures

2.3.1 Module Lattice-based signature keys

The Crypto API supports Module Lattice-based digital signatures (ML-DSA), as defined in FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204].

PSA_KEY_TYPE_ML_DSA_KEY_PAIR (macro)

ML-DSA key pair: both the private and public key.

Added in version 1.3.

#define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002)

The bit size used in the attributes of an ML-DSA key is a measure of the security strength of the ML-DSA parameter set in [FIPS204]:

  • ML-DSA-44 : key_bits = 128

  • ML-DSA-65 : key_bits = 192

  • ML-DSA-87 : key_bits = 256

See also §4 in [FIPS204].

Compatible algorithms

Key format

An ML-DSA key pair is the \((pk,sk)\) pair of public key and secret key, which are generated from a secret 32-byte seed, \(\xi\). See [FIPS204] §5.1.

In calls to psa_import_key() and psa_export_key(), the key-pair data format is the 32-byte seed \(\xi\).

Rationale

The formats for X.509 handling of ML-DSA keys are specified in Internet X.509 Public Key Infrastructure - Algorithm Identifiers for the Module-Lattice-Based Digital Signature Algorithm (ML-DSA) [LAMPS-MLDSA]. This permits a choice of three formats for the decapsulation key material, incorporating one, or both, of the seed value \(\xi\) and the expanded secret key \(sk\).

The Crypto API only supports the recommended format from [LAMPS-MLDSA], which is the bytes of the seed \(\xi\), but without the ASN.1 encoding prefix. This suits the constrained nature of Crypto API implementations, where interoperation with expanded secret-key formats is not required.

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

Implementation note

An implementation can optionally compute and store the \((pk,sk)\) values, to accelerate operations that use the key. It is recommended that an implementation retains the seed \(\xi\) with the key pair, in order to export the key, or copy the key to a different location.

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, \(\xi\). The key pair \((pk, sk)\) is generated from the seed as defined by ML-DSA.KeyGen_internal() in [FIPS204] §6.1.

Implementation note

It is :an implementation choice whether the seed \(\xi\) is expanded to \((pk, sk)\) at the point of derivation, or only just before the key is used.

PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY (macro)

ML-DSA public key.

Added in version 1.3.

#define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)

The bit size used in the attributes of an ML-DSA public key is the same as the corresponding private key. See PSA_KEY_TYPE_ML_DSA_KEY_PAIR.

Compatible algorithms

Key format

An ML-DSA public key is the \(pk\) output of ML-DSA.KeyGen(), defined in [FIPS204] §5.1.

In calls to psa_import_key(), psa_export_key(), and psa_export_public_key(), the public-key data format is \(pk\).

Rationale

This format is the same as that specified for X.509 in Internet X.509 Public Key Infrastructure - Algorithm Identifiers for the Module-Lattice-Based Digital Signature Algorithm (ML-DSA) [LAMPS-MLDSA].

The size of the public key depends on the ML-DSA parameter set as follows:

Parameter set

Public-key size in bytes

ML-DSA-44

1312

ML-DSA-65

1952

ML-DSA-87

2592

PSA_KEY_TYPE_IS_ML_DSA (macro)

Whether a key type is an ML-DSA key, either a key pair or a public key.

Added in version 1.3.

#define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */

Parameters

type

A key type: a value of type psa_key_type_t.

2.3.2 Module Lattice-based signature algorithms

These algorithms extend those defined in PSA Certified Crypto API [PSA-CRYPT] §10.7 Asymmetric signature, for use with the signature functions.

The ML-DSA signature and verification scheme is defined in FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204]. ML-DSA has three parameter sets which provide differing security strengths.

ML-DSA keys are large: 1.2–2.5kB for the public key, and triple that for the key pair. ML-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 2.4kB and 4.6kB, depending on the selected parameter set.

See [FIPS204] §4 for details on the parameter sets, and the key and generated signature sizes.

The generation of an ML-DSA key depends on the full parameter specification. The encoding of each parameter set into the key attributes is described in Module Lattice-based signature keys.

[FIPS204] defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. Four algorithms are defined to support these variants: PSA_ALG_ML_DSA, PSA_ALG_DETERMINISTIC_ML_DSA, PSA_ALG_HASH_ML_DSA(), and PSA_ALG_DETERMINISTIC_HASH_ML_DSA().

Hedged and deterministic signatures

Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs.

Signature verification does not distinguish between a hedged and a deterministic signature. Either hedged or deterministic algorithms can be used when verifying a signature.

When computing a signature, the key’s permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key’s permitted-algorithm policy.

Note

The hedged version provides message secrecy and some protection against side-channels. [FIPS204] 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.

Implementation note

[FIPS204] 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.

Rationale

The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in [FIPS204].

However, the Crypto API gives distinct algorithm identifiers for the hedged and deterministic variants, to enable an application use case to require a specific variant.

Pure and pre-hashed algorithms

The pre-hashed signature computation HashML-DSA generates distinct signatures to a pure signature ML-DSA, with the same key and message hashing algorithm.

An ML-DSA signature can only be verified with an ML-DSA algorithm. A HashML-DSA signature can only be verified with a HashML-DSA algorithm.

Contexts

All ML-DSA algorithms can be used with contexts, which enables domain-separation when signatures are made of different message structures with the same key. Context values are arbitrary strings between zero and 255 bytes in length.

  • The signature functions without a context parameter provide a zero-length context when computing or verifying ML-DSA signatures.

  • To provide a context, use the psa_xxxx_with_context() signature functions with a context parameter, such as psa_sign_message_with_context().

PSA_ALG_ML_DSA (macro)

Module lattice-based digital signature algorithm without pre-hashing (ML-DSA).

Added in version 1.3.

#define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400)

This algorithm can only be used with the message signature and verify functions. For example, psa_sign_message() or psa_verify_message_with_context().

This is the pure ML-DSA digital signature algorithm, defined by FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204], using hedging. ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation.

This algorithm is randomized: each invocation returns a different, equally valid signature. See the notes on hedged signatures.

This algorithm has a context parameter. See the notes on ML-DSA contexts.

When PSA_ALG_ML_DSA is used as a permitted algorithm in a key policy, this permits:

Note

To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (PSA_ALG_HASH_ML_DSA() and PSA_ALG_DETERMINISTIC_HASH_ML_DSA()) can also be used with psa_sign_hash() and psa_verify_hash().

The signature produced by HashML-DSA is distinct from that produced by ML-DSA.

Compatible key types

PSA_KEY_TYPE_ML_DSA_KEY_PAIR
PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY (signature verification only)

PSA_ALG_DETERMINISTIC_ML_DSA (macro)

Deterministic module lattice-based digital signature algorithm without pre-hashing (ML-DSA).

Added in version 1.3.

#define PSA_ALG_DETERMINISTIC_ML_DSA ((psa_algorithm_t) 0x06004500)

This algorithm can only be used with the message signature and verify functions. For example, psa_sign_message() or psa_verify_message_with_context().

This is the pure ML-DSA digital signature algorithm, defined by FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204], without hedging. ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation.

This algorithm is deterministic: each invocation with the same inputs returns an identical signature.

Warning

It is recommended to use the hedged PSA_ALG_ML_DSA algorithm instead, when supported by the implementation. See the notes on deterministic signatures.

This algorithm has a context parameter. See the notes on ML-DSA contexts.

When PSA_ALG_DETERMINISTIC_ML_DSA is used as a permitted algorithm in a key policy, this permits:

Note

To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (PSA_ALG_HASH_ML_DSA() and PSA_ALG_DETERMINISTIC_HASH_ML_DSA()) can also be used with psa_sign_hash() and psa_verify_hash().

The signature produced by HashML-DSA is distinct from that produced by ML-DSA.

Compatible key types

PSA_KEY_TYPE_ML_DSA_KEY_PAIR
PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY (signature verification only)

PSA_ALG_HASH_ML_DSA (macro)

Module lattice-based digital signature algorithm with pre-hashing (HashML-DSA).

Added in version 1.3.

#define PSA_ALG_HASH_ML_DSA(hash_alg) /* specification-defined value */

Parameters

hash_alg

A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true. This includes PSA_ALG_ANY_HASH when specifying the algorithm in a key policy.

Returns

The corresponding HashML-DSA signature algorithm, using hash_alg to pre-hash the message.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

This is the pre-hashed ML-DSA digital signature algorithm, defined by FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204], using hedging. ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation.

Note

For the pre-hashing, [FIPS204] §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set.

This algorithm is randomized: each invocation returns a different, equally valid signature. See the notes on hedged signatures.

This algorithm has a context parameter. See the notes on ML-DSA contexts.

When PSA_ALG_HASH_ML_DSA() is used as a permitted algorithm in a key policy, this permits:

Note

The signature produced by HashML-DSA is distinct from that produced by ML-DSA.

Usage

This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:

  • Call psa_sign_message() or psa_sign_message_with_context() with the message.

  • Calculate the hash of the message with psa_hash_compute(), or with a multi-part hash operation, using the hash_alg hash algorithm. Note that hash_alg can be extracted from the signature algorithm using PSA_ALG_GET_HASH(sig_alg). Then sign the calculated hash either with psa_sign_hash() or, if the protocol requires the use of a non-zero-length context, with psa_sign_hash_with_context().

Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature function, or psa_verify_message_with_context() or psa_verify_hash_with_context() if a non-zero-=length context has been used.

Compatible key types

PSA_KEY_TYPE_ML_DSA_KEY_PAIR
PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY (signature verification only)

PSA_ALG_DETERMINISTIC_HASH_ML_DSA (macro)

Deterministic module lattice-based digital signature algorithm with pre-hashing (HashML-DSA).

Added in version 1.3.

#define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \
    /* specification-defined value */

Parameters

hash_alg

A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true. This includes PSA_ALG_ANY_HASH when specifying the algorithm in a key policy.

Returns

The corresponding deterministic HashML-DSA signature algorithm, using hash_alg to pre-hash the message.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

This is the pre-hashed ML-DSA digital signature algorithm, defined by FIPS Publication 204: Module-Lattice-Based Digital Signature Standard [FIPS204], without hedging. ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation.

Note

For the pre-hashing, [FIPS204] §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set.

This algorithm is deterministic: each invocation with the same inputs returns an identical signature.

Warning

It is recommended to use the hedged PSA_ALG_HASH_ML_DSA() algorithm instead, when supported by the implementation. See the notes on deterministic signatures.

This algorithm has a context parameter. See the notes on ML-DSA contexts.

When PSA_ALG_DETERMINISTIC_HASH_ML_DSA() is used as a permitted algorithm in a key policy, this permits:

Note

The signature produced by HashML-DSA is distinct from that produced by ML-DSA.

Usage

See PSA_ALG_HASH_ML_DSA() for example usage.

Compatible key types

PSA_KEY_TYPE_ML_DSA_KEY_PAIR
PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY (signature verification only)

PSA_ALG_IS_ML_DSA (macro)

Whether the specified algorithm is ML-DSA, without pre-hashing.

Added in version 1.3.

#define PSA_ALG_IS_ML_DSA(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a pure ML-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

Note

Use PSA_ALG_IS_HASH_ML_DSA() to determine if an algorithm identifier is a HashML-DSA algorithm.

PSA_ALG_IS_HASH_ML_DSA (macro)

Whether the specified algorithm is HashML-DSA.

Added in version 1.3.

#define PSA_ALG_IS_HASH_ML_DSA(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a HashML-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

Note

Use PSA_ALG_IS_ML_DSA() to determine if an algorithm identifier is a pre-hashed ML-DSA algorithm.

PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA (macro)

Whether the specified algorithm is deterministic HashML-DSA.

Added in version 1.3.

#define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \
    /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a deterministic HashML-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

See also PSA_ALG_IS_HASH_ML_DSA() and PSA_ALG_IS_HEDGED_HASH_ML_DSA().

PSA_ALG_IS_HEDGED_HASH_ML_DSA (macro)

Whether the specified algorithm is hedged HashML-DSA.

Added in version 1.3.

#define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a hedged HashML-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

See also PSA_ALG_IS_HASH_ML_DSA() and PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA().