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 dcrypt_internal::random::{CryptoRng, RngCore};
11use dcrypt_internal::zeroing::Zeroize;
12
13/// Trait for Key Encapsulation Mechanism (KEM) with domain-specific types.
14///
15/// # Security Design
16///
17/// This trait defines distinct types and explicit serialization contracts for
18/// KEM inputs and outputs. Implementations remain responsible for validating
19/// encodings and meeting their algorithm-specific security requirements.
20pub trait Kem {
21    /// Public key type with appropriate constraints.
22    ///
23    /// # Security Note
24    /// Implements `Serialize` for the public encoding boundary.
25    type PublicKey: Clone + Serialize;
26
27    /// Secret key type with an explicit clearing and serialization contract.
28    ///
29    /// # Security Note
30    /// - Implements `Zeroize` for best-effort clearing of owned initialized storage.
31    /// - Implements `SerializeSecret` for exact-size protected exports.
32    type SecretKey: Zeroize + Clone + SerializeSecret;
33
34    /// Shared-secret type with an explicit clearing and serialization contract.
35    ///
36    /// # Security Note
37    /// - Implements `Zeroize` for best-effort clearing of owned initialized storage.
38    /// - Implements `SerializeSecret` for exact-size protected exports.
39    /// - Should be converted to application keys immediately after generation.
40    type SharedSecret: Zeroize + Clone + SerializeSecret;
41
42    /// Ciphertext type for the encapsulated key.
43    ///
44    /// # Security Note
45    /// Implements `Serialize` for the public encoding boundary.
46    type Ciphertext: Clone + Serialize;
47
48    /// Keypair type for efficient storage of related keys. It is an intermediate type
49    /// and does not require a serialization contract itself.
50    type KeyPair: Clone;
51
52    /// Returns the KEM algorithm name.
53    fn name() -> &'static str;
54
55    /// Generate a new keypair.
56    ///
57    /// # Security Requirements
58    /// - Must use the provided CSPRNG for all randomness.
59    /// - Keys must be generated according to the algorithm specification.
60    fn keypair<R: CryptoRng + RngCore>(rng: &mut R) -> Result<Self::KeyPair>;
61
62    /// Extract public key from keypair.
63    fn public_key(keypair: &Self::KeyPair) -> Self::PublicKey;
64
65    /// Extract secret key from keypair.
66    ///
67    /// # Security Note
68    /// The returned secret key should be protected and explicitly cleared after use.
69    fn secret_key(keypair: &Self::KeyPair) -> Self::SecretKey;
70
71    /// Encapsulate a shared secret using the recipient's public key.
72    ///
73    /// # Security Requirements
74    /// - Must validate the public key internally.
75    /// - Must use fresh randomness from the provided RNG.
76    /// - Must not intentionally branch or index memory on secret material.
77    ///   Concrete compiler/target behavior requires separate validation.
78    fn encapsulate<R: CryptoRng + RngCore>(
79        rng: &mut R,
80        public_key: &Self::PublicKey,
81    ) -> Result<(Self::Ciphertext, Self::SharedSecret)>;
82
83    /// Decapsulate a shared secret using the private key.
84    ///
85    /// # Security Requirements
86    /// - Must not intentionally branch or index memory on secret material.
87    ///   Concrete compiler/target behavior requires separate validation.
88    /// - Should use implicit rejection for IND-CCA2 security where applicable.
89    /// - Must not leak information about the secret key.
90    fn decapsulate(
91        secret_key: &Self::SecretKey,
92        ciphertext: &Self::Ciphertext,
93    ) -> Result<Self::SharedSecret>;
94}
dcrypt_api/traits/kem.rs

dcrypt_api/traits/
kem.rs
