Struct MLKEM 

pub struct MLKEM<const PK_LEN: usize, const SK_LEN: usize, const CT_LEN: usize, const SS_LEN: usize, PK: MLKEMPublicKeyTrait<k, PK_LEN> + MLKEMPublicKeyInternalTrait<k, PK_LEN>, SK: MLKEMPrivateKeyTrait<k, PK, SK_LEN, PK_LEN> + MLKEMPrivateKeyInternalTrait<k, PK, SK_LEN, PK_LEN>, const k: usize, const eta: i16, const du: i16, const dv: i16, const LAMBDA: i16> { /* private fields */ }

The core internal implementation of the ML-KEM algorithm. This needs to be public for the compiler to be able to find it, but you shouldn’t ever need to use this directly. Please use the named public types.

Implementations

impl<const PK_LEN: usize, const SK_LEN: usize, const CT_LEN: usize, const SS_LEN: usize, PK: MLKEMPublicKeyTrait<k, PK_LEN> + MLKEMPublicKeyInternalTrait<k, PK_LEN>, SK: MLKEMPrivateKeyTrait<k, PK, SK_LEN, PK_LEN> + MLKEMPrivateKeyInternalTrait<k, PK, SK_LEN, PK_LEN>, const k: usize, const eta1: i16, const du: i16, const dv: i16, const LAMBDA: i16> MLKEM<PK_LEN, SK_LEN, CT_LEN, SS_LEN, PK, SK, k, eta1, du, dv, LAMBDA>

pub fn keygen_from_os_rng() -> Result<(PK, SK), KEMError>

Should still be ok in FIPS mode

pub fn encaps_internal( ek: &PK, A_hat: Option<&Matrix<k, k>>, m: [u8; 32], ) -> ([u8; 32], [u8; CT_LEN])

Algorithm 17 ML-KEM.Encaps_internal(ek, 𝑚) Uses the encapsulation key and randomness to generate a key and an associated ciphertext. Input: encapsulation key ek ∈ 𝔹384𝑘+32 . Input: randomness 𝑚 ∈ 𝔹32 . Output: shared secret key 𝐾 ∈ 𝔹32 . Output: ciphertext 𝑐 ∈ 𝔹32(𝑑𝑢𝑘+𝑑𝑣).

This function also takes an Option for the public matrix A. If you don’t know what it is, just provide None. This is to enable performance optimizations when the same public key is used for multiple encapsulations and the intermediate value called the public matrix A_hat can be re-used for multiple encapsulations. A_hat can be obtained from MLKEMPublicKeyTrait::A_hat. Alternatively, you can use a MLKEMPublicKeyExpanded with MLKEM::encaps_for_expanded_key. If you specify None, the function will compute A_hat internally and everything will work fine.

Unlike the more public function exposed by KEM::encaps, this returns the shared secret as raw bytes instead of wrapped in an appropriately-set KeyMaterialTrait, so you’re on your own for handling it properly.

Note: this is an internal function that allows the caller to specify the encapsulation randomness (which is the message m to be encrypted by the underlying PKE scheme). This function should not be used directly unless you really have a good reason. KEM::encaps should be used in 99.9% of cases. The reason this is exposed publicly is: A) for unit testing that requires access to the deterministically reproducible function, and B) for operational environments that wish to provide randomness from their own source instead of the built-in RNG in bc-rust. If you think you will be clever and invent some scheme that uses a deterministic KEM, then you will almost certainly end up with security problems. Please don’t do this.

pub fn decaps_from_seed( seed: &KeyMaterial<64>, ct: &[u8], ) -> Result<KeyMaterial<SS_LEN>, KEMError>

Alternative initialization of the streaming signer where you have your private key as a seed and you want to delay its expansion as late as possible for memory-usage reasons.

Trait Implementations

impl<const PK_LEN: usize, const SK_LEN: usize, const CT_LEN: usize, const SS_LEN: usize, PK: MLKEMPublicKeyTrait<k, PK_LEN> + MLKEMPublicKeyInternalTrait<k, PK_LEN>, SK: MLKEMPrivateKeyTrait<k, PK, SK_LEN, PK_LEN> + MLKEMPrivateKeyInternalTrait<k, PK, SK_LEN, PK_LEN>, const k: usize, const eta: i16, const du: i16, const dv: i16, const LAMBDA: i16> KEM<PK, SK, PK_LEN, SK_LEN, CT_LEN, SS_LEN> for MLKEM<PK_LEN, SK_LEN, CT_LEN, SS_LEN, PK, SK, k, eta, du, dv, LAMBDA>

fn keygen() -> Result<(PK, SK), KEMError>

Generates a fresh key pair.

fn encaps(pk: &PK) -> Result<(KeyMaterial<SS_LEN>, [u8; CT_LEN]), KEMError>

Performs an encapsulation against the given public key, using the library’s default internal RNG. Returns (shared_secret_key, ciphertext) The derived shared secret key is returned as a KeyMaterial with the SecurityStrength set to the security level of the ML-KEM parameter set.

Algorithm 20 ML-KEM.Encaps(ek) Uses the encapsulation key to generate a shared secret key and an associated ciphertext. Checked input: encapsulation key ek ∈ 𝔹384𝑘+32 . Output: shared secret key 𝐾 ∈ 𝔹32 . Output: ciphertext 𝑐 ∈ 𝔹32(𝑑𝑢𝑘+𝑑𝑣).

fn decaps(sk: &SK, ct: &[u8]) -> Result<KeyMaterial<SS_LEN>, KEMError>

Performs a decapsulation of the given ciphertext. Returns the shared secret key. The derived shared secret key is returned as a KeyMaterial with the SecurityStrength set to the security level of the ML-KEM parameter set. As ML-KEM is an implicitly-rejecting KEM, this returns an error only if the ciphertext is invalid (ie the wrong length).

impl<const PK_LEN: usize, const SK_LEN: usize, const CT_LEN: usize, const SS_LEN: usize, PK: MLKEMPublicKeyTrait<k, PK_LEN> + MLKEMPublicKeyInternalTrait<k, PK_LEN>, SK: MLKEMPrivateKeyTrait<k, PK, SK_LEN, PK_LEN> + MLKEMPrivateKeyInternalTrait<k, PK, SK_LEN, PK_LEN>, const k: usize, const eta1: i16, const du: i16, const dv: i16, const LAMBDA: i16> MLKEMTrait<PK_LEN, SK_LEN, CT_LEN, SS_LEN, PK, SK, k, eta1, du, dv, LAMBDA> for MLKEM<PK_LEN, SK_LEN, CT_LEN, SS_LEN, PK, SK, k, eta1, du, dv, LAMBDA>

fn keygen_from_seed(seed: &KeyMaterial<64>) -> Result<(PK, SK), KEMError>

Imports a secret key from a seed.

fn keygen_from_seed_and_encoded( seed: &KeyMaterial<64>, encoded_sk: &[u8; SK_LEN], ) -> Result<(PK, SK), KEMError>

Imports a secret key from both a seed and an encoded_sk.

This is a convenience function to expand the key from seed and compare it against the provided encoded_sk using a constant-time equality check. If everything checks out, the secret key is returned fully populated with pk and seed. If the provided key and derived key don’t match, an error is returned.

fn keypair_consistency_check(pk: &PK, sk: &SK) -> Result<(), KEMError>

Given a public key and a secret key, check that the public key matches the secret key. This is a sanity check that the public key was generated correctly from the secret key.

At the current time, this is only possible if sk either contains a public key (in which case the two pk’s are encoded and compared for byte equality), or if sk contains a seed (in which case a keygen_from_seed is run and then the pk’s compared).

Returns either () or KEMError::ConsistencyCheckFailed.

fn encaps_for_expanded_key( pk: &MLKEMPublicKeyExpanded<k, PK, PK_LEN>, ) -> Result<(KeyMaterial<SS_LEN>, [u8; CT_LEN]), KEMError>

Same as KEM::encaps, but acts on an MLKEMPublicKeyExpanded.

fn decaps_with_expanded_key( sk: &MLKEMPrivateKeyExpanded<k, PK, SK, SK_LEN, PK_LEN>, ct: &[u8], ) -> Result<KeyMaterial<SS_LEN>, KEMError>

Same as KEM::decaps, but acts on an MLKEMPrivateKeyExpanded.