Module kem

Expand description

Key-Encapsulation Mechanisms (KEMs), including support for Kyber Round 3 Submission.

§Example

Note that this example uses the Kyber-512 Round 3 algorithm, but other algorithms can be used in the exact same way by substituting kem::<desired_algorithm_here> for kem::KYBER512_R3.

use aws_lc_rs::{
    kem::{Ciphertext, DecapsulationKey, EncapsulationKey},
    kem::{ML_KEM_512}
};

// Alice generates their (private) decapsulation key.
let decapsulation_key = DecapsulationKey::generate(&ML_KEM_512)?;

// Alices computes the (public) encapsulation key.
let encapsulation_key = decapsulation_key.encapsulation_key()?;

let encapsulation_key_bytes = encapsulation_key.key_bytes()?;

// Alice sends the encapsulation key bytes to bob through some
// protocol message.
let encapsulation_key_bytes = encapsulation_key_bytes.as_ref();

// Bob constructs the (public) encapsulation key from the key bytes provided by Alice.
let retrieved_encapsulation_key = EncapsulationKey::new(&ML_KEM_512, encapsulation_key_bytes)?;

// Bob executes the encapsulation algorithm to to produce their copy of the secret, and associated ciphertext.
let (ciphertext, bob_secret) = retrieved_encapsulation_key.encapsulate()?;

// Alice receives ciphertext bytes from bob
let ciphertext_bytes = ciphertext.as_ref();

// Bob sends Alice the ciphertext computed from the encapsulation algorithm, Alice runs decapsulation to derive their
// copy of the secret.
let alice_secret = decapsulation_key.decapsulate(Ciphertext::from(ciphertext_bytes))?;

// Alice and Bob have now arrived to the same secret
assert_eq!(alice_secret.as_ref(), bob_secret.as_ref());

Structs§

Algorithm: A KEM algorithm
Ciphertext: A set of encrypted bytes produced by EncapsulationKey::encapsulate, and used as an input to DecapsulationKey::decapsulate.
DecapsulationKey: A serializable decapulsation key usable with KEMs. This can be randomly generated with DecapsulationKey::generate.
EncapsulationKey: A serializable encapsulation key usable with KEM algorithms. Constructed from either a DecapsulationKey or raw bytes.
EncapsulationKeyBytes: Serialized bytes
SharedSecret: The cryptographic shared secret output from the KEM encapsulate / decapsulate process.

Enums§

AlgorithmId: Identifier for a KEM algorithm.

Constants§

ML_KEM_512: NIST FIPS 203 ML-KEM-512 algorithm.
ML_KEM_768: NIST FIPS 203 ML-KEM-768 algorithm.
ML_KEM_1024: NIST FIPS 203 ML-KEM-1024 algorithm.

Traits§