Beta

2.2 Module Lattice-based key encapsulation

2.2.1 Module Lattice-based key-encapsulation keys

The Crypto API supports Module Lattice-based key ecapsulation (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 key attribute size 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

Warning

The key format may change in a final version of this API. The standardization of exchange formats for ML-KEM public and private keys is in progress, but final documents have not been published. See Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) [LAMPS-MLKEM].

The current proposed format is based on the expected outcome of that process.

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 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 values as the private key, for the following reasons:

  • ML-KEM decapsulation keys are 1.5–3.0 kB in size, but can be recomputed efficiently from the initial 64-byte seed-pair.

  • There is no need to validate an imported ML-KEM key pair — every 64-byte pair of seed values is valid.

  • It is better for the standard to choose a single format to improve interoperability.

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 implementation defined 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 key attribute size 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

Warning

The key format may change in a final version of this API. The standardization of exchange formats for ML-KEM public and private keys is in progress, but final documents have not been published. See Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) [LAMPS-MLKEM].

The current proposed format is based on the expected outcome of that process.

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

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)