Module libsignal_protocol::kem

source ·
Expand description

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:

// Generate a Kyber1024 key pair
let kp = KeyPair::generate(KeyType::Kyber1024);

// The sender computes the shared secret and the ciphertext to send
let (ss_for_sender, ct) = kp.public_key.encapsulate();

// 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:

// Generate a Kyber1024 key pair
let kp = KeyPair::generate(KeyType::Kyber1024);

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§

Traits§

Type Aliases§