Enum EncapsulationPublicKey 

pub enum EncapsulationPublicKey {
    X25519(X25519PublicKey),
    MLKEM(MLKEMPublicKey),
}

A public key used for key encapsulation mechanisms (KEM).

EncapsulationPublicKey is an enum representing different types of public keys that can be used for key encapsulation, including:

• X25519: Curve25519-based key exchange
• ML-KEM: Module Lattice-based Key Encapsulation Mechanism at various security levels

These public keys are used to encrypt (encapsulate) shared secrets that can only be decrypted (decapsulated) by the corresponding private key holder.

Variants

X25519(X25519PublicKey)

An X25519 public key

MLKEM(MLKEMPublicKey)

An ML-KEM public key (post-quantum)

Implementations

impl EncapsulationPublicKey

pub fn encapsulation_scheme(&self) -> EncapsulationScheme

Returns the encapsulation scheme associated with this public key.

Returns

The encapsulation scheme (X25519, MLKEM512, MLKEM768, or MLKEM1024) that corresponds to this public key.

Example

use bc_components::{EncapsulationScheme, X25519PrivateKey};

// Generate a keypair
let private_key = X25519PrivateKey::new();
let public_key = private_key.public_key();

// Convert to encapsulation public key
let encapsulation_public_key =
    bc_components::EncapsulationPublicKey::X25519(public_key);

// Check the scheme
assert_eq!(
    encapsulation_public_key.encapsulation_scheme(),
    EncapsulationScheme::X25519
);

pub fn encapsulate_new_shared_secret( &self, ) -> (SymmetricKey, EncapsulationCiphertext)

Encapsulates a new shared secret using this public key.

This method performs the encapsulation operation for key exchange. It generates a new shared secret and encapsulates it using this public key.

The encapsulation process differs based on the key type:

• For X25519: Generates an ephemeral private/public key pair, derives a shared secret using Diffie-Hellman, and returns the shared secret along with the ephemeral public key
• For ML-KEM: Uses the KEM encapsulation algorithm to generate and encapsulate a random shared secret

Returns

A tuple containing:

• The generated shared secret as a SymmetricKey
• The encapsulation ciphertext that can be sent to the private key holder

Example

use bc_components::EncapsulationScheme;

// Generate a key pair using the default scheme (X25519)
let (private_key, public_key) = EncapsulationScheme::default().keypair();

// Encapsulate a new shared secret
let (shared_secret, ciphertext) =
    public_key.encapsulate_new_shared_secret();

// The private key holder can recover the same shared secret
let recovered_secret =
    private_key.decapsulate_shared_secret(&ciphertext).unwrap();
assert_eq!(shared_secret, recovered_secret);

Trait Implementations

impl AsRef<EncapsulationPublicKey> for PublicKeys

fn as_ref(&self) -> &EncapsulationPublicKey

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for EncapsulationPublicKey

fn clone(&self) -> EncapsulationPublicKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EncapsulationPublicKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Encrypter for EncapsulationPublicKey

Implementation of the Encrypter trait for EncapsulationPublicKey.

This allows EncapsulationPublicKey to be used with the generic encryption interface defined by the Encrypter trait.

fn encapsulation_public_key(&self) -> EncapsulationPublicKey

Returns the encapsulation public key for this encrypter.

fn encapsulate_new_shared_secret( &self, ) -> (SymmetricKey, EncapsulationCiphertext)

Encapsulates a new shared secret for the recipient.

impl From<EncapsulationPublicKey> for CBOR

Conversion from EncapsulationPublicKey to CBOR for serialization.

fn from(public_key: EncapsulationPublicKey) -> Self

Converts to this type from the input type.

impl Hash for EncapsulationPublicKey

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for EncapsulationPublicKey

fn eq(&self, other: &EncapsulationPublicKey) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<CBOR> for EncapsulationPublicKey

Conversion from CBOR to EncapsulationPublicKey for deserialization.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self, Error>

Performs the conversion.

impl Eq for EncapsulationPublicKey

impl StructuralPartialEq for EncapsulationPublicKey