dcrypt_api/traits/
kem.rs

1// File: crates/api/src/traits/kem.rs
2
3//! Trait definition for Key Encapsulation Mechanisms (KEM) with enhanced type safety
4//!
5//! This module provides a type-safe interface for key encapsulation mechanisms,
6//! which are used for secure key exchange in public-key cryptography.
7
8use super::serialize::{Serialize, SerializeSecret};
9use crate::Result;
10use rand::{CryptoRng, RngCore};
11use zeroize::Zeroize;
12
13/// Trait for Key Encapsulation Mechanism (KEM) with domain-specific types.
14///
15/// # Security Design
16///
17/// This trait enforces strong type safety and clear contracts for serialization,
18/// preventing common security vulnerabilities.
19pub trait Kem {
20    /// Public key type with appropriate constraints.
21    ///
22    /// # Security Note
23    /// Implements `Serialize` to guarantee safe `from_bytes` and `to_bytes` methods.
24    type PublicKey: Clone + Serialize;
25
26    /// Secret key type with security guarantees.
27    ///
28    /// # Security Note
29    /// - Implements `Zeroize` for secure memory cleanup.
30    /// - Implements `SerializeSecret` to guarantee safe `from_bytes` and `to_bytes_zeroizing` methods.
31    type SecretKey: Zeroize + Clone + SerializeSecret;
32
33    /// Shared secret type with security guarantees.
34    ///
35    /// # Security Note
36    /// - Implements `Zeroize` for secure memory cleanup.
37    /// - Implements `SerializeSecret` for secure serialization.
38    /// - Should be converted to application keys immediately after generation.
39    type SharedSecret: Zeroize + Clone + SerializeSecret;
40
41    /// Ciphertext type for the encapsulated key.
42    ///
43    /// # Security Note
44    /// Implements `Serialize` for safe `from_bytes` and `to_bytes` methods.
45    type Ciphertext: Clone + Serialize;
46
47    /// Keypair type for efficient storage of related keys. It is an intermediate type
48    /// and does not require a serialization contract itself.
49    type KeyPair: Clone;
50
51    /// Returns the KEM algorithm name.
52    fn name() -> &'static str;
53
54    /// Generate a new keypair.
55    ///
56    /// # Security Requirements
57    /// - Must use the provided CSPRNG for all randomness.
58    /// - Keys must be generated according to the algorithm specification.
59    fn keypair<R: CryptoRng + RngCore>(rng: &mut R) -> Result<Self::KeyPair>;
60
61    /// Extract public key from keypair.
62    fn public_key(keypair: &Self::KeyPair) -> Self::PublicKey;
63
64    /// Extract secret key from keypair.
65    ///
66    /// # Security Note
67    /// The returned secret key should be protected and zeroized after use.
68    fn secret_key(keypair: &Self::KeyPair) -> Self::SecretKey;
69
70    /// Encapsulate a shared secret using the recipient's public key.
71    ///
72    /// # Security Requirements
73    /// - Must validate the public key internally.
74    /// - Must use fresh randomness from the provided RNG.
75    /// - Must be resistant to side-channel attacks.
76    fn encapsulate<R: CryptoRng + RngCore>(
77        rng: &mut R,
78        public_key: &Self::PublicKey,
79    ) -> Result<(Self::Ciphertext, Self::SharedSecret)>;
80
81    /// Decapsulate a shared secret using the private key.
82    ///
83    /// # Security Requirements
84    /// - Must be constant-time.
85    /// - Should use implicit rejection for IND-CCA2 security where applicable.
86    /// - Must not leak information about the secret key.
87    fn decapsulate(
88        secret_key: &Self::SecretKey,
89        ciphertext: &Self::Ciphertext,
90    ) -> Result<Self::SharedSecret>;
91}
dcrypt_api/traits/kem.rs

dcrypt_api/traits/
kem.rs
