Skip to main content

qualia_core_db/crypto/network/
entropy.rs

1//! Product OS entropy and ephemeral-key leases.
2//!
3//! Production `fill_os` uses the operating-system CSPRNG only. A `getrandom`
4//! failure returns `EntropyFailure`. This module never imports or falls back
5//! to harness `SeededEntropy`.
6
7use zeroize::Zeroize;
8
9use super::ed25519;
10use super::errors::CryptoError;
11use super::types::{KeyPurpose, ED25519_SIG_LEN, X25519_LEN};
12use super::x25519::X25519Secret;
13
14/// Fill `out` from the OS CSPRNG. Never substitutes deterministic test RNG.
15pub fn fill_os(out: &mut [u8]) -> Result<(), CryptoError> {
16    match getrandom::fill(out) {
17        Ok(()) => Ok(()),
18        Err(_) => {
19            out.zeroize();
20            Err(CryptoError::EntropyFailure)
21        }
22    }
23}
24
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26enum LeaseState {
27    Live,
28    Cancelled,
29    Destroyed,
30}
31
32/// Ephemeral X25519 + Ed25519 material: generate, use, rotate, cancel, destroy.
33pub struct EphemeralKeyLease {
34    purpose: KeyPurpose,
35    x25519: [u8; X25519_LEN],
36    ed25519: [u8; 32],
37    state: LeaseState,
38}
39
40impl EphemeralKeyLease {
41    /// Generate a live lease from OS entropy. Failure is `EntropyFailure`.
42    pub fn generate(purpose: KeyPurpose) -> Result<Self, CryptoError> {
43        let mut x25519 = [0u8; X25519_LEN];
44        let mut ed25519 = [0u8; 32];
45        if let Err(e) = fill_os(&mut x25519) {
46            x25519.zeroize();
47            return Err(e);
48        }
49        if let Err(e) = fill_os(&mut ed25519) {
50            x25519.zeroize();
51            ed25519.zeroize();
52            return Err(e);
53        }
54        Ok(Self {
55            purpose,
56            x25519,
57            ed25519,
58            state: LeaseState::Live,
59        })
60    }
61
62    /// The key purpose this lease was issued for.
63    pub fn purpose(&self) -> Result<KeyPurpose, CryptoError> {
64        self.require_live()?;
65        Ok(self.purpose)
66    }
67
68    /// The lease's X25519 public key.
69    pub fn x25519_public(&self) -> Result<[u8; X25519_LEN], CryptoError> {
70        self.require_live()?;
71        Ok(X25519Secret::from_bytes(self.x25519).public())
72    }
73
74    /// The lease's Ed25519 public key.
75    pub fn ed25519_public(&self) -> Result<[u8; 32], CryptoError> {
76        self.require_live()?;
77        Ok(ed25519::public_from_seed(&self.ed25519))
78    }
79
80    /// Use: X25519 Diffie-Hellman. Rejects all-zero shared secrets via the adapter.
81    pub fn diffie_hellman(&self, peer: &[u8; X25519_LEN]) -> Result<[u8; X25519_LEN], CryptoError> {
82        self.require_live()?;
83        X25519Secret::from_bytes(self.x25519).diffie_hellman(peer)
84    }
85
86    /// Use: Ed25519 with the network length-delimited context.
87    pub fn sign_ed25519(
88        &self,
89        message: &[u8],
90        context: &[u8],
91        sig_out: &mut [u8; ED25519_SIG_LEN],
92    ) -> Result<(), CryptoError> {
93        self.require_live()?;
94        ed25519::sign_with_context(&self.ed25519, message, context, sig_out)
95    }
96
97    /// Replace material with a fresh OS draw; previous bytes are destroyed.
98    pub fn rotate(&mut self) -> Result<(), CryptoError> {
99        self.require_live()?;
100        let mut new_x = [0u8; X25519_LEN];
101        let mut new_ed = [0u8; 32];
102        if let Err(e) = fill_os(&mut new_x) {
103            new_x.zeroize();
104            return Err(e);
105        }
106        if let Err(e) = fill_os(&mut new_ed) {
107            new_x.zeroize();
108            new_ed.zeroize();
109            return Err(e);
110        }
111        self.x25519.zeroize();
112        self.ed25519.zeroize();
113        self.x25519 = new_x;
114        self.ed25519 = new_ed;
115        Ok(())
116    }
117
118    /// Cancels the lease without destroying key material bookkeeping.
119    pub fn cancel(&mut self) {
120        if matches!(self.state, LeaseState::Live) {
121            self.state = LeaseState::Cancelled;
122            self.zeroize_material();
123        }
124    }
125
126    /// Destroys the lease, zeroing key material and releasing the slot.
127    pub fn destroy(&mut self) {
128        self.state = LeaseState::Destroyed;
129        self.zeroize_material();
130    }
131
132    fn require_live(&self) -> Result<(), CryptoError> {
133        match self.state {
134            LeaseState::Live => Ok(()),
135            LeaseState::Cancelled => Err(CryptoError::Cancelled),
136            LeaseState::Destroyed => Err(CryptoError::Revoked),
137        }
138    }
139
140    fn zeroize_material(&mut self) {
141        self.x25519.zeroize();
142        self.ed25519.zeroize();
143    }
144}
145
146impl Drop for EphemeralKeyLease {
147    fn drop(&mut self) {
148        self.zeroize_material();
149    }
150}
151
152impl core::fmt::Debug for EphemeralKeyLease {
153    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
154        f.debug_struct("EphemeralKeyLease")
155            .field("purpose", &self.purpose)
156            .field("state", &self.state)
157            .finish()
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    #[test]
166    fn fill_os_succeeds_or_is_entropy_failure() {
167        let mut buf = [0u8; 32];
168        match fill_os(&mut buf) {
169            Ok(()) => {}
170            Err(e) => {
171                assert_eq!(e, CryptoError::EntropyFailure);
172                assert_eq!(buf, [0u8; 32]);
173            }
174        }
175    }
176
177    #[test]
178    fn os_failure_never_selects_seeded_entropy() {
179        fn product_map(result: Result<(), ()>, out: &mut [u8]) -> Result<(), CryptoError> {
180            match result {
181                Ok(()) => fill_os(out),
182                Err(()) => {
183                    out.zeroize();
184                    Err(CryptoError::EntropyFailure)
185                }
186            }
187        }
188        let mut buf = [0xAAu8; 8];
189        assert_eq!(
190            product_map(Err(()), &mut buf).unwrap_err(),
191            CryptoError::EntropyFailure
192        );
193        assert_eq!(buf, [0u8; 8]);
194    }
195
196    #[test]
197    fn destroy_rejects_later_dh_and_sign() {
198        let mut lease = EphemeralKeyLease::generate(KeyPurpose::QLinkEphemeral).unwrap();
199        let peer = X25519Secret::from_bytes([2u8; 32]);
200        let peer_pk = peer.public();
201        lease.diffie_hellman(&peer_pk).unwrap();
202        let mut sig = [0u8; ED25519_SIG_LEN];
203        lease.sign_ed25519(b"msg", b"ctx", &mut sig).unwrap();
204        lease.destroy();
205        assert_eq!(
206            lease.diffie_hellman(&peer_pk).unwrap_err(),
207            CryptoError::Revoked
208        );
209        assert_eq!(
210            lease.sign_ed25519(b"msg", b"ctx", &mut sig).unwrap_err(),
211            CryptoError::Revoked
212        );
213        assert_eq!(lease.x25519_public().unwrap_err(), CryptoError::Revoked);
214    }
215
216    #[test]
217    fn cancel_rejects_use_with_cancelled() {
218        let mut lease = EphemeralKeyLease::generate(KeyPurpose::QSessionEphemeral).unwrap();
219        let peer_pk = X25519Secret::from_bytes([3u8; 32]).public();
220        lease.cancel();
221        assert_eq!(
222            lease.diffie_hellman(&peer_pk).unwrap_err(),
223            CryptoError::Cancelled
224        );
225        let mut sig = [0u8; ED25519_SIG_LEN];
226        assert_eq!(
227            lease.sign_ed25519(b"m", b"c", &mut sig).unwrap_err(),
228            CryptoError::Cancelled
229        );
230    }
231
232    #[test]
233    fn rotate_replaces_material_and_destroys_old() {
234        let mut lease = EphemeralKeyLease::generate(KeyPurpose::QLinkEphemeral).unwrap();
235        let pk1 = lease.x25519_public().unwrap();
236        let ed1 = lease.ed25519_public().unwrap();
237        lease.rotate().unwrap();
238        let pk2 = lease.x25519_public().unwrap();
239        let ed2 = lease.ed25519_public().unwrap();
240        assert_ne!(pk1, pk2);
241        assert_ne!(ed1, ed2);
242        let peer_pk = X25519Secret::from_bytes([4u8; 32]).public();
243        lease.diffie_hellman(&peer_pk).unwrap();
244    }
245
246    #[test]
247    fn debug_redacts_secret_bytes() {
248        let lease = EphemeralKeyLease::generate(KeyPurpose::QLinkEphemeral).unwrap();
249        let rendered = format!("{:?}", lease);
250        assert!(rendered.contains("EphemeralKeyLease"));
251        assert!(rendered.contains("purpose"));
252        assert!(!rendered.contains("x25519"));
253        assert!(!rendered.contains("ed25519"));
254    }
255}