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:
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:
Draw 32 bytes of output as the seed value \(d\).
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_PUBLIC_KEY
(encapsulation only)