Crate kem 

RustCrypto: Key Encapsulation Mechanisms (KEMs)

About

This crate provides a common set of traits for key encapsulation mechanisms—algorithms for non-interactively establishing secrets between peers.

This is intended to be implemented by libraries which produce or contain implementations of key encapsulation mechanisms, and used by libraries which want to produce or consume encapsulated secrets while generically supporting any compatible backend.

License

Licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

There are two roles in a KEM:

• Encapsulator: the holder of the public key (a.k.a. encapsulation key), which provides an operation that simultaneously generates both the plaintext and ciphertext of a random “shared key” whose ciphertext (a.k.a. encapsulation) can be sent to the party with the decapsulator key.
• Decapsulator: holder secret/private key (a.k.a. decapsulation key), which can be used to decrypt the encrypted (a.k.a. encapsulated) “shared key” which was randomly generated by the encapsulator.

The following example illustrates the workflow of using this crate’s traits with a hypothetical KEM named K :

// NOTE: requires the `getrandom` feature is enabled

use kem::{Decapsulate, Encapsulate, Kem};

// Generate a decapsulation/encapsulation keypair. The first one is the secret one.
let (dk, ek) = K::generate_keypair();

// Encapsulator:
//
// Randomly generates and encapsulates/encrypts a shared key which can be decrypted by the
// holder of the decapsulation key, obtaining the ciphertext and plaintext of the shared key.
let (ct, k_send) = ek.encapsulate();

// Decapsulator:
//
// Decapsulates the encrypted/encapsulated shared key, obtaining its plaintext.
let k_recv = dk.decapsulate(&ct);

// We've now established a shared key.
assert_eq!(k_send, k_recv);

Serialization

The KeyInit and KeyExport traits can be used to load and store encoded decapsulation and encapsulation keys from their byte serialization.

Decapsulation keys are often initialized from a compact representation known as a Seed. The FromSeed trait provides an extension to the Kem trait for initializing keypairs from a seed value. We recommend the KeyInit and KeyExport trait impls on decapsulation keys operate on seed values when there is a choice of multiple key formats (e.g. expanded decapsulation keys).

Re-exports

pub use common;

Modules

consts

Structs

InvalidKey

Error type for TryKeyInit for cases where the provided bytes do not correspond to a valid key.

Traits

Decapsulate

Decapsulator for encapsulated keys, with an associated Encapsulator bounded by the Encapsulate trait.

Decapsulator

Decapsulator with an associated encapsulation key which can be used for encrypting shared keys that this decapsulator can decrypt.

Encapsulate

Encapsulator for shared secrets.

FromSeed

Initialize a KEM from a Seed.

Generate

Secure random generation.

Kem

Key encapsulation mechanism.

KeyExport

Serialize a key to a byte array.

KeyInit

Types which can be initialized from a key.

KeySizeUser

Types which use key for initialization.

TryDecapsulate

Decapsulator for encapsulated keys with failure handling, with an associated Encapsulator bounded by the Encapsulate trait.

TryKeyInit

Types which can be fallibly initialized from a key.

Type Aliases

Ciphertext

Ciphertext message (a.k.a. “encapsulated key”) produced by Encapsulate::encapsulate which is an encrypted SharedKey that can be decrypted using Decapsulate::decapsulate.

DecapsulationKey

KEM decryption key (i.e. private key) which can decrypt encrypted shared secret ciphertexts which were encrypted by EncapsulationKey<K>.

EncapsulationKey

KEM encryption key (i.e. public key) which encrypts shared secrets into ciphertexts which can be decrypted by DecapsulationKey<K>.

Key

Key used by KeySizeUser implementors.

Seed

Seed value which can be used to deterministically initialize a KEM keypair.

SharedKey

Shared key: plaintext produced after decapsulation by Decapsulate::decapsulate which is also returned by Encapsulate::encapsulate, which is the shared secret resulting from the key encapsulation algorithm.