Struct DecapsulationKey 

pub struct DecapsulationKey<Id = AlgorithmId>
where
    Id: AlgorithmIdentifier,
{ /* private fields */ }

A serializable decapulsation key usable with KEMs. This can be randomly generated with DecapsulationKey::generate.

Implementations

impl<Id> DecapsulationKey<Id>

where Id: AlgorithmIdentifier,

pub fn new( alg: &'static Algorithm<Id>, bytes: &[u8], ) -> Result<DecapsulationKey<Id>, KeyRejected>

Creates a new KEM decapsulation key from raw bytes. This method MUST NOT be used to generate a new decapsulation key, rather it MUST be used to construct DecapsulationKey previously serialized to raw bytes.

alg is the Algorithm to be associated with the generated DecapsulationKey.

bytes is a slice of raw bytes representing a DecapsulationKey.

Security Considerations

This function performs size validation but does not fully validate key material integrity. Invalid key bytes (e.g., corrupted or tampered data) may be accepted by this function but will cause Self::decapsulate to fail. Only use bytes that were previously obtained from Self::key_bytes on a validly generated key.

Limitations

The DecapsulationKey returned by this function will NOT provide the associated EncapsulationKey via Self::encapsulation_key. The EncapsulationKey must be serialized and restored separately using EncapsulationKey::key_bytes and EncapsulationKey::new.

Errors

Returns KeyRejected::too_small() if bytes.len() < alg.decapsulate_key_size().

Returns KeyRejected::too_large() if bytes.len() > alg.decapsulate_key_size().

Returns KeyRejected::unexpected_error() if the underlying cryptographic operation fails.

pub fn generate( alg: &'static Algorithm<Id>, ) -> Result<DecapsulationKey<Id>, Unspecified>

Generate a new KEM decapsulation key for the given algorithm.

Errors

error::Unspecified when operation fails due to internal error.

pub fn algorithm(&self) -> &'static Algorithm<Id>

Return the algorithm associated with the given KEM decapsulation key.

pub fn key_bytes(&self) -> Result<DecapsulationKeyBytes<'static>, Unspecified>

Returns the raw bytes of the DecapsulationKey.

The returned bytes can be used with Self::new to reconstruct the DecapsulationKey.

Errors

Returns Unspecified if the key bytes cannot be retrieved from the underlying cryptographic implementation.

pub fn encapsulation_key(&self) -> Result<EncapsulationKey<Id>, Unspecified>

Returns the EncapsulationKey associated with this DecapsulationKey.

Errors

Returns Unspecified in the following cases:

• The DecapsulationKey was constructed from raw bytes using Self::new, as the underlying key representation does not include the public key component. In this case, the EncapsulationKey must be serialized and restored separately.
• An internal error occurs while extracting the public key.

pub fn decapsulate( &self, ciphertext: Ciphertext<'_>, ) -> Result<SharedSecret, Unspecified>

Performs the decapsulate operation using this DecapsulationKey on the given ciphertext.

ciphertext is the ciphertext generated by the encapsulate operation using the EncapsulationKey associated with this DecapsulationKey.

Errors

Returns Unspecified in the following cases:

• The ciphertext is malformed or was not generated for this key’s algorithm.
• The DecapsulationKey was constructed from invalid bytes (e.g., corrupted or tampered key material passed to Self::new). Note that Self::new only validates the size of the key bytes, not their cryptographic validity.
• An internal cryptographic error occurs.

Trait Implementations

impl<Id> Debug for DecapsulationKey<Id>

where Id: AlgorithmIdentifier,

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

Formats the value using the given formatter.

impl<Id> Send for DecapsulationKey<Id>

where Id: AlgorithmIdentifier,

impl<Id> Sync for DecapsulationKey<Id>

where Id: AlgorithmIdentifier,