Trait Encaps 

pub trait Encaps {
    type SharedSecretKey;
    type CipherText;

    // Required method
    fn try_encaps_with_rng(
        &self,
        rng: &mut impl CryptoRngCore,
    ) -> Result<(Self::SharedSecretKey, Self::CipherText), &'static str>;

    // Provided methods
    fn try_encaps(
        &self,
    ) -> Result<(Self::SharedSecretKey, Self::CipherText), &'static str> { ... }
    fn encaps_from_seed(
        &self,
        seed: &[u8; 32],
    ) -> (Self::SharedSecretKey, Self::CipherText) { ... }
}

The Encaps trait defines methods for generating shared secrets and ciphertexts using an encapsulation key.

Required Associated Types

type SharedSecretKey

The shared secret key type generated during encapsulation

type CipherText

The ciphertext type transmitted from the encapsulating party to the decapsulating party

Required Methods

fn try_encaps_with_rng( &self, rng: &mut impl CryptoRngCore, ) -> Result<(Self::SharedSecretKey, Self::CipherText), &'static str>

Generates a shared secret and ciphertext from an encapsulation key specific to this security parameter set.
This function utilizes a provided random number generator and is intended to operate in constant time.

Errors

Returns an error when the random number generator fails or an internal error condition arises.

Examples

use rand_core::OsRng;
use fips203::ml_kem_512;  // Could also be ml_kem_768 or ml_kem_1024.
use fips203::traits::{KeyGen, SerDes, Decaps, Encaps};

let (ek1, dk1) = ml_kem_512::KG::try_keygen_with_rng(&mut OsRng)?;  // Party 1 generates both encaps and decaps keys
let ek1_bytes = ek1.into_bytes();  // Party 1 serializes the encaps key

let ek2_bytes = ek1_bytes;  // Party 1 sends encaps bytes to party 2

let ek2 = ml_kem_512::EncapsKey::try_from_bytes(ek2_bytes)?;  // Party 2 deserializes the encaps key
let (ssk2, ct2) = ek2.try_encaps_with_rng(&mut OsRng)?;  // Party 2 generates shared secret and ciphertext
let ct2_bytes = ct2.into_bytes();  // Party 2 serializes the ciphertext

let ct1_bytes = ct2_bytes;  // Party 2 sends the ciphertext to party 1

let ct1 = ml_kem_512::CipherText::try_from_bytes(ct1_bytes)?;  // Party 1 deserializes the ciphertext
let ssk1 = dk1.try_decaps(&ct1)?;  // Party 1 runs decaps to generate the shared secret

assert_eq!(ssk1, ssk2);  // Each party has the same shared secret

Provided Methods

fn try_encaps( &self, ) -> Result<(Self::SharedSecretKey, Self::CipherText), &'static str>

Generates a shared secret and ciphertext from an encapsulation key specific to this security parameter set.
This function utilizes the OS default random number generator and is intended to operate in constant time outside of rho which crosses the trust boundary in the clear.

Errors

Returns an error when the random number generator fails or an internal error condition arises.

Examples

use rand_core::OsRng;
use fips203::ml_kem_512;  // Could also be ml_kem_768 or ml_kem_1024.
use fips203::traits::{KeyGen, SerDes, Decaps, Encaps};

let (ek1, dk1) = ml_kem_512::KG::try_keygen_with_rng(&mut OsRng)?;  // Party 1 generates both encaps and decaps keys
let ek1_bytes = ek1.into_bytes();  // Party 1 serializes the encaps key

let ek2_bytes = ek1_bytes;  // Party 1 sends encaps bytes to party 2

let ek2 = ml_kem_512::EncapsKey::try_from_bytes(ek2_bytes)?;  // Party 2 deserializes the encaps key
let (ssk2, ct2) = ek2.try_encaps()?;  // Party 2 generates shared secret and ciphertext
let ct2_bytes = ct2.into_bytes();  // Party 2 serializes the ciphertext

let ct1_bytes = ct2_bytes;  // Party 2 sends the ciphertext to party 1

let ct1 = ml_kem_512::CipherText::try_from_bytes(ct1_bytes)?;  // Party 1 deserializes the ciphertext
let ssk1 = dk1.try_decaps(&ct1)?;  // Party 1 runs decaps to generate the shared secret

assert_eq!(ssk1, ssk2);  // Each party has the same shared secret

fn encaps_from_seed( &self, seed: &[u8; 32], ) -> (Self::SharedSecretKey, Self::CipherText)

Generates a shared secret and ciphertext from an encapsulation key specific to this security parameter set.
This function utilizes a provided seed (rather than a random number generator) and is intended to operate in constant time.

Errors

Returns an error when the random number generator fails or an internal error condition arises.

Examples

use rand_core::OsRng;
use fips203::ml_kem_512;  // Could also be ml_kem_768 or ml_kem_1024.
use fips203::traits::{KeyGen, SerDes, Decaps, Encaps};

let (ek1, dk1) = ml_kem_512::KG::try_keygen_with_rng(&mut OsRng)?;  // Party 1 generates both encaps and decaps keys
let ek1_bytes = ek1.into_bytes();  // Party 1 serializes the encaps key

let ek2_bytes = ek1_bytes;  // Party 1 sends encaps bytes to party 2

let ek2 = ml_kem_512::EncapsKey::try_from_bytes(ek2_bytes)?;  // Party 2 deserializes the encaps key
let (ssk2, ct2) = ek2.encaps_from_seed(&[1u8; 32]);  // Party 2 generates shared secret and ciphertext
let ct2_bytes = ct2.into_bytes();  // Party 2 serializes the ciphertext

let ct1_bytes = ct2_bytes;  // Party 2 sends the ciphertext to party 1

let ct1 = ml_kem_512::CipherText::try_from_bytes(ct1_bytes)?;  // Party 1 deserializes the ciphertext
let ssk1 = dk1.try_decaps(&ct1)?;  // Party 1 runs decaps to generate the shared secret

assert_eq!(ssk1, ssk2);  // Each party has the same shared secret

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Encaps for fips203::ml_kem_512::EncapsKey

type CipherText = CipherText<CT_LEN>

type SharedSecretKey = SharedSecretKey

impl Encaps for fips203::ml_kem_768::EncapsKey

type CipherText = CipherText<CT_LEN>

type SharedSecretKey = SharedSecretKey

impl Encaps for fips203::ml_kem_1024::EncapsKey

type CipherText = CipherText<CT_LEN>

type SharedSecretKey = SharedSecretKey