Module kem

Keys and protocol functions for standard key encapsulation mechanisms (KEMs).

A KEM allows the holder of a PublicKey to create a shared secret with the holder of the corresponding SecretKey. This is done by calling the function encapsulate on the PublicKey to produce a SharedSecret and Ciphertext. The Ciphertext is then sent to the recipient who can now call SecretKey::decapsulate(ct: Ciphertext) to construct the same SharedSecret.

Supported KEMs

The NIST standardized Kyber1024 and Kyber768 KEMs are currently supported.

Serialization

PublicKeys and SecretKeys have serialization functions that encode the KEM protocol. Calls to PublicKey::deserialize() and SecretKey::deserialize() will use this to ensure the key is used for the correct KEM protocol.

Example

Basic usage:

let mut rng = rand::rng();
// Generate a Kyber1024 key pair
let kp = KeyPair::generate(KeyType::Kyber1024, &mut rng);

// The sender computes the shared secret and the ciphertext to send
let (ss_for_sender, ct) = kp.public_key.encapsulate(&mut rng).expect("encapsulation succeeds");

// Once the recipient receives the ciphertext, they use it with the
// secret key to construct the (same) shared secret.
let ss_for_recipient = kp.secret_key.decapsulate(&ct).expect("decapsulation succeeds");
assert_eq!(ss_for_recipient, ss_for_sender);

Serialization:

let mut rng = rand::rng();
// Generate a Kyber1024 key pair
let kp = KeyPair::generate(KeyType::Kyber1024, &mut rng);

let pk_for_wire = kp.public_key.serialize();
// serialized form has an extra byte to encode the protocol
assert_eq!(pk_for_wire.len(), 1568 + 1);

let kp_reconstituted = PublicKey::deserialize(pk_for_wire.as_ref()).expect("deserialized correctly");
assert_eq!(kp_reconstituted.key_type(), KeyType::Kyber1024);

Structs

Key

KeyPair

A public/secret key pair for a KEM protocol.

Enums

KeyType

Designates a supported KEM protocol

Public

Secret

Traits

KeyKind

Type Aliases

PublicKey

A KEM public key with the ability to encapsulate a shared secret.

SecretKey

A KEM secret key with the ability to decapsulate a shared secret.

SerializedCiphertext