2.2 Module Lattice-based key encapsulation

2.2.1 Module Lattice-based key-encapsulation keys

The Crypto API supports Module Lattice-based key encapsulation (ML-KEM) as defined in FIPS Publication 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard [FIPS203].

PSA_KEY_TYPE_ML_KEM_KEY_PAIR (macro)

ML-KEM key pair: both the decapsulation and encapsulation key.

Added in version 1.3.

#define PSA_KEY_TYPE_ML_KEM_KEY_PAIR ((psa_key_type_t)0x7004)

The Crypto API treats decapsulation keys as private keys and encapsulation keys as public keys.

The bit size used in the attributes of an ML-KEM key is specified by the numeric part of the parameter-set identifier defined in [FIPS203]. The parameter-set identifier refers to the key strength, and not to the actual size of the key. The following values for the key_bits key attribute are used to select a specific ML-KEM parameter set:

  • ML-KEM-512 : key_bits = 512

  • ML-KEM-768 : key_bits = 768

  • ML-KEM-1024 : key_bits = 1024

See also §8 in [FIPS203].

Compatible algorithms

Key format

An ML-KEM key pair is the \((ek,dk)\) pair of encapsulation key and decapsulation key, which are generated from two secret 32-byte seeds, \(d\) and \(z\). See [FIPS203] §7.1.

In calls to psa_import_key() and psa_export_key(), the key-pair data format is the concatenation of the two seed values: \(d\ ||\ z\).

Rationale

The formats for X.509 handling of ML-KEM keys are specified in Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) [LAMPS-MLKEM]. This permits a choice of three formats for the decapsulation key material, incorporating one, or both, of the seed values \(d\ ||\ z\) and the expanded decapsulation key \(dk\).

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

See PSA_KEY_TYPE_ML_KEM_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 \(dk\) value, which also contains the encapsulation key \(ek\), to accelerate operations that use the key. It is recommended that an implementation retains the seed pair \((d,z)\) with the decapsulation key, 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 construct an ML-KEM key pair using the following process:

  1. Draw 32 bytes of output as the seed value \(d\).

  2. Draw 32 bytes of output as the seed value \(z\).

The key pair \((ek,dk)\) is generated from the seed as defined by ML-KEM.KeyGen_internal() in [FIPS203] §6.1.

Implementation note

It is an implementation choice whether the seed-pair \((d,z)\) is expanded to \((ek,dk)\) at the point of derivation, or only just before the key is used.

PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY (macro)

ML-KEM public (encapsulation) key.

Added in version 1.3.

#define PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY ((psa_key_type_t)0x4004)

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

Compatible algorithms

Key format

An ML-KEM public key is the \(ek\) output of ML-KEM.KeyGen(), defined in [FIPS203] §7.1.

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

Rationale

This format is the same as that specified for X.509 in Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) [LAMPS-MLKEM].

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

Parameter set

Public-key size in bytes

ML-KEM-512

800

ML-KEM-768

1184

ML-KEM-1024

1568

PSA_KEY_TYPE_IS_ML_KEM (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_KEM(type) /* specification-defined value */

Parameters

type

A key type: a value of type psa_key_type_t.

2.2.2 Module Lattice-based key-encapsulation algorithm

These algorithms extend those defined in PSA Certified Crypto API [PSA-CRYPT] §10.10 Key encapsulation, for use with the key-encapsulation functions.

Note

The key-encapsulation functions, psa_encapsulate() and psa_decapsulate(), were introduced in version 1.3 of the Crypto API.

ML-KEM is defined in FIPS Publication 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard [FIPS203]. ML-KEM has three parameter sets which provide differing security strengths.

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

See [FIPS203] §8 for details on the parameter sets.

PSA_ALG_ML_KEM (macro)

Module Lattice-based key-encapsulation mechanism (ML-KEM).

Added in version 1.3.

#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0c000200)

This is the ML-KEM key-encapsulation algorithm, defined by [FIPS203]. ML-KEM requires an ML-KEM key, which determines the ML-KEM parameter set for the operation.

When using ML-KEM, the size of the encapsulation data returned by a call to psa_encapsulate() is as follows:

Parameter set

Encapsulation data size in bytes

ML-KEM-512

768

ML-KEM-768

1088

ML-KEM-1024

1568

The 32-byte shared output key that is produced by ML-KEM is pseudorandom. Although it can be used directly as an encryption key, it is recommended to use the output key as an input to a key-derivation operation to produce additional cryptographic keys.

Compatible key types

PSA_KEY_TYPE_ML_KEM_KEY_PAIR
PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY (encapsulation only)