dcrypt_api/traits/
kem.rs

1//! Trait definition for Key Encapsulation Mechanisms (KEM) with enhanced type safety
2//!
3//! This module provides a type-safe interface for key encapsulation mechanisms,
4//! which are used for secure key exchange in public-key cryptography.
5//!
6//! # Security Improvements
7//! 
8//! This trait has been hardened by removing direct byte access:
9//! - No `AsMut<[u8]>` - prevents key tampering and corruption
10//! - No `AsRef<[u8]>` - prevents accidental key exposure
11//! - All byte access must go through explicit, auditable methods
12
13use crate::Result;
14use rand::{CryptoRng, RngCore};
15use zeroize::Zeroize;
16
17/// Trait for Key Encapsulation Mechanism (KEM) with domain-specific types
18/// 
19/// # Security Design
20/// 
21/// Types are opaque - no direct byte access is provided to prevent:
22/// - Key manipulation attacks (no `AsMut`)
23/// - Accidental key leakage (no `AsRef`)
24/// - Timing side channels through direct memory access
25pub trait Kem {
26    /// Public key type with appropriate constraints
27    /// 
28    /// # Security Note
29    /// No direct byte access. Keys are opaque types that can only be
30    /// used through KEM operations or explicit serialization methods.
31    type PublicKey: Clone;
32
33    /// Secret key type with security guarantees
34    /// 
35    /// # Security Note
36    /// - Must implement `Zeroize` for secure cleanup
37    /// - No direct byte access prevents accidental exposure
38    /// - Can only be used through KEM operations
39    type SecretKey: Zeroize + Clone;
40
41    /// Shared secret type with security guarantees
42    /// 
43    /// # Security Note
44    /// - Must implement `Zeroize` for secure cleanup  
45    /// - No direct byte access prevents leakage
46    /// - Should be converted to application keys immediately
47    type SharedSecret: Zeroize + Clone;
48
49    /// Ciphertext type for the encapsulated key
50    /// 
51    /// # Security Note
52    /// No direct byte access prevents tampering.
53    /// Modifications would invalidate the encapsulation.
54    type Ciphertext: Clone;
55
56    /// Keypair type for efficient storage of related keys
57    type KeyPair: Clone;
58
59    /// Returns the KEM algorithm name
60    fn name() -> &'static str;
61
62    /// Generate a new keypair
63    /// 
64    /// # Security Requirements
65    /// - Must use the provided CSPRNG for all randomness
66    /// - Keys must be generated according to the algorithm specification
67    fn keypair<R: CryptoRng + RngCore>(rng: &mut R) -> Result<Self::KeyPair>;
68
69    /// Extract public key from keypair
70    fn public_key(keypair: &Self::KeyPair) -> Self::PublicKey;
71
72    /// Extract secret key from keypair
73    /// 
74    /// # Security Note
75    /// The returned secret key should be protected and zeroized after use
76    fn secret_key(keypair: &Self::KeyPair) -> Self::SecretKey;
77
78    /// Encapsulate a shared secret using the recipient's public key
79    /// 
80    /// # Security Requirements
81    /// - Must validate the public key internally
82    /// - Must use fresh randomness from the provided RNG
83    /// - Must be resistant to side-channel attacks
84    fn encapsulate<R: CryptoRng + RngCore>(
85        rng: &mut R,
86        public_key: &Self::PublicKey,
87    ) -> Result<(Self::Ciphertext, Self::SharedSecret)>;
88
89    /// Decapsulate a shared secret using the private key
90    /// 
91    /// # Security Requirements
92    /// - Must be constant-time
93    /// - Should use implicit rejection for IND-CCA2 security
94    /// - Must not leak information about the secret key
95    fn decapsulate(
96        secret_key: &Self::SecretKey,
97        ciphertext: &Self::Ciphertext,
98    ) -> Result<Self::SharedSecret>;
99}
dcrypt_api/traits/kem.rs

dcrypt_api/traits/
kem.rs
