Skip to main content

qualia_core_db/net/qdnf/session/
rekey.rs

1//! Bounded traffic-key update (E02.4).
2//!
3//! Rekey and replayed cached [`PolicyOutcome::Allow`] do not renew service
4//! authority. Drain: Active → Draining is permitted; application from
5//! Draining is rejected except closure. Old-key retention is current plus
6//! [`MAX_OLD_KEYS`] previous generations with actual secret material.
7//! Packages remain open.
8//!
9//! CRY-02.11: a traffic-key update is not fresh hybrid recovery.
10
11use crate::crypto::network::types::AEAD_KEY_LEN;
12use crate::net::qdnf::authority::PolicyOutcome;
13use crate::net::qdnf::crypto::schedule::derive_traffic_update;
14use crate::net::qdnf::errors::QdnfError;
15use crate::net::qdnf::session::handshake::{SessionBinding, SessionState};
16use crate::net::qdnf::types::Generation;
17use zeroize::Zeroize;
18
19/// Bounded old-key retention (current + 2 old).
20pub const MAX_OLD_KEYS: usize = 2;
21
22#[repr(u8)]
23#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24pub enum KeyPhase {
25    Current = 1,
26    Previous = 2,
27    Stale = 3,
28}
29
30#[repr(C)]
31#[derive(Clone, Copy, Debug, PartialEq, Eq)]
32pub struct TrafficKeySlot {
33    pub generation: u64,
34    pub phase: KeyPhase,
35}
36
37struct SecretSlot {
38    occupied: bool,
39    generation: u64,
40    send: [u8; AEAD_KEY_LEN],
41    recv: [u8; AEAD_KEY_LEN],
42}
43
44impl SecretSlot {
45    const EMPTY: Self = Self {
46        occupied: false,
47        generation: 0,
48        send: [0u8; AEAD_KEY_LEN],
49        recv: [0u8; AEAD_KEY_LEN],
50    };
51
52    fn erase(&mut self) {
53        self.send.zeroize();
54        self.recv.zeroize();
55        self.occupied = false;
56        self.generation = 0;
57    }
58}
59
60/// Owner of traffic secrets. Not `Copy`: generations without keys are not a rotation.
61pub struct RekeyTable {
62    current: u64,
63    /// Newest-first previous generations. Index 0 is immediately previous.
64    old: [u64; MAX_OLD_KEYS],
65    old_len: u8,
66    current_keys: SecretSlot,
67    old_keys: [SecretSlot; MAX_OLD_KEYS],
68}
69
70impl RekeyTable {
71    /// Builds `RekeyTable` from `keys`.
72    pub fn from_keys(
73        send: [u8; AEAD_KEY_LEN],
74        recv: [u8; AEAD_KEY_LEN],
75    ) -> Result<Self, QdnfError> {
76        if send == [0u8; AEAD_KEY_LEN] || recv == [0u8; AEAD_KEY_LEN] || send == recv {
77            return Err(QdnfError::CryptoFailure);
78        }
79        Ok(Self {
80            current: 1,
81            old: [0; MAX_OLD_KEYS],
82            old_len: 0,
83            current_keys: SecretSlot {
84                occupied: true,
85                generation: 1,
86                send,
87                recv,
88            },
89            old_keys: [SecretSlot::EMPTY; MAX_OLD_KEYS],
90        })
91    }
92
93    #[inline]
94    /// `RekeyTable::current_generation`.
95    pub fn current_generation(&self) -> u64 {
96        self.current
97    }
98
99    /// `RekeyTable::current_generation_token`.
100    pub fn current_generation_token(&self) -> Generation {
101        Generation(self.current)
102    }
103
104    /// Install next traffic key generation. Does not change
105    /// [`SessionBinding::policy`] / grant.
106    ///
107    /// Derives new secrets from the current pair, zeroizes the retired slot,
108    /// and resets uniqueness by exposing a new generation id for packet spaces.
109    pub fn rotate(&mut self) -> Result<u64, QdnfError> {
110        if self.current == u64::MAX {
111            return Err(QdnfError::Capacity);
112        }
113        if !self.current_keys.occupied {
114            return Err(QdnfError::Incomplete);
115        }
116        let next = self.current.saturating_add(1);
117        let (next_send, next_recv) =
118            derive_traffic_update(&self.current_keys.send, &self.current_keys.recv, next)?;
119        let retiring = self.current;
120        let retiring_keys = SecretSlot {
121            occupied: true,
122            generation: retiring,
123            send: self.current_keys.send,
124            recv: self.current_keys.recv,
125        };
126        let n = self.old_len as usize;
127        if n == MAX_OLD_KEYS {
128            self.old_keys[MAX_OLD_KEYS - 1].erase();
129            let mut i = MAX_OLD_KEYS;
130            while i > 1 {
131                i -= 1;
132                self.old[i] = self.old[i - 1];
133                self.old_keys[i] = SecretSlot {
134                    occupied: self.old_keys[i - 1].occupied,
135                    generation: self.old_keys[i - 1].generation,
136                    send: self.old_keys[i - 1].send,
137                    recv: self.old_keys[i - 1].recv,
138                };
139            }
140            self.old[0] = retiring;
141            self.old_keys[0] = retiring_keys;
142        } else {
143            let mut i = n;
144            while i > 0 {
145                self.old[i] = self.old[i - 1];
146                self.old_keys[i] = SecretSlot {
147                    occupied: self.old_keys[i - 1].occupied,
148                    generation: self.old_keys[i - 1].generation,
149                    send: self.old_keys[i - 1].send,
150                    recv: self.old_keys[i - 1].recv,
151                };
152                i -= 1;
153            }
154            self.old[0] = retiring;
155            self.old_keys[0] = retiring_keys;
156            self.old_len = self.old_len.saturating_add(1);
157        }
158        self.current_keys.send.zeroize();
159        self.current_keys.recv.zeroize();
160        self.current_keys = SecretSlot {
161            occupied: true,
162            generation: next,
163            send: next_send,
164            recv: next_recv,
165        };
166        self.current = next;
167        Ok(self.current)
168    }
169
170    /// Rekey phase.
171    pub fn phase(&self, generation: u64) -> Result<KeyPhase, QdnfError> {
172        if generation == self.current {
173            return Ok(KeyPhase::Current);
174        }
175        let n = self.old_len as usize;
176        let mut i = 0;
177        while i < n {
178            if self.old[i] == generation {
179                return Ok(if i == 0 {
180                    KeyPhase::Previous
181                } else {
182                    KeyPhase::Stale
183                });
184            }
185            i += 1;
186        }
187        Err(QdnfError::Expired)
188    }
189
190    /// Rekey slot.
191    pub fn slot(&self, generation: u64) -> Result<TrafficKeySlot, QdnfError> {
192        Ok(TrafficKeySlot {
193            generation,
194            phase: self.phase(generation)?,
195        })
196    }
197
198    /// Copy directional keys for an occupied generation. Retired generations fail.
199    pub fn keys(
200        &self,
201        generation: u64,
202    ) -> Result<([u8; AEAD_KEY_LEN], [u8; AEAD_KEY_LEN]), QdnfError> {
203        if generation == self.current && self.current_keys.occupied {
204            return Ok((self.current_keys.send, self.current_keys.recv));
205        }
206        let n = self.old_len as usize;
207        let mut i = 0;
208        while i < n {
209            if self.old_keys[i].occupied && self.old_keys[i].generation == generation {
210                return Ok((self.old_keys[i].send, self.old_keys[i].recv));
211            }
212            i += 1;
213        }
214        Err(QdnfError::Expired)
215    }
216
217    /// True when `generation` has been retired from both current and old key slots (`R04`).
218    pub fn is_generation_zeroized(&self, generation: u64) -> bool {
219        if self.current_keys.occupied && self.current_keys.generation == generation {
220            return false;
221        }
222        let mut i = 0;
223        while i < MAX_OLD_KEYS {
224            if self.old_keys[i].occupied && self.old_keys[i].generation == generation {
225                return false;
226            }
227            i += 1;
228        }
229        true
230    }
231}
232
233impl Drop for RekeyTable {
234    fn drop(&mut self) {
235        self.current_keys.erase();
236        let mut i = 0;
237        while i < MAX_OLD_KEYS {
238            self.old_keys[i].erase();
239            i += 1;
240        }
241    }
242}
243
244/// Rekey never renews service authority (NET-05.12).
245#[inline]
246pub fn rekey_renews_service_authority() -> bool {
247    false
248}
249
250/// Replayed cached Allow does not become a current grant.
251#[inline]
252pub fn replayed_cached_allow_renews_grant() -> bool {
253    let _ = PolicyOutcome::Allow;
254    false
255}
256
257/// Drain: Active → Draining is ok; application from Draining is Unauthorized
258/// except closure.
259///
260/// If `!grant_current` → [`QdnfError::Unauthorized`] even if
261/// `binding.policy` is [`PolicyOutcome::Allow`] and state is Active.
262/// If `binding.state` is Draining or Closed → [`QdnfError::Closed`].
263/// Else delegate to [`SessionBinding::admit_application`] (already requires
264/// Active + current policy).
265pub fn admit_after_rekey(binding: &SessionBinding, grant_current: bool) -> Result<(), QdnfError> {
266    if !grant_current {
267        return Err(QdnfError::Unauthorized);
268    }
269    if matches!(
270        binding.state(),
271        SessionState::Draining | SessionState::Closed
272    ) {
273        return Err(QdnfError::Closed);
274    }
275    binding.admit_application()
276}
277
278/// CRY-02.11: key update ≠ fresh hybrid recovery.
279#[inline]
280pub fn traffic_update_is_hybrid_recovery() -> bool {
281    false
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287    use crate::net::qdnf::types::{OperationId, StrongDigest};
288
289    fn binding(state: SessionState, policy: PolicyOutcome) -> SessionBinding {
290        SessionBinding::test_fixture(
291            OperationId([1u8; 16]),
292            StrongDigest([2u8; 48]),
293            StrongDigest([3u8; 48]),
294            StrongDigest([4u8; 48]),
295            policy,
296            state,
297        )
298    }
299
300    #[test]
301    fn rotate_twice_keeps_current_and_two_old_third_retires_oldest() {
302        let mut table = RekeyTable::from_keys([1u8; 32], [2u8; 32]).unwrap();
303        assert_eq!(table.current_generation(), 1);
304        let first = table.keys(1).unwrap();
305        assert_eq!(table.rotate(), Ok(2));
306        assert_eq!(table.rotate(), Ok(3));
307        assert_eq!(table.current_generation(), 3);
308        assert_eq!(table.phase(3), Ok(KeyPhase::Current));
309        assert_eq!(table.phase(2), Ok(KeyPhase::Previous));
310        assert_eq!(table.phase(1), Ok(KeyPhase::Stale));
311        assert_eq!(table.slot(1).unwrap().generation, 1);
312        assert_eq!(table.rotate(), Ok(4));
313        assert_eq!(table.current_generation(), 4);
314        assert_eq!(table.phase(4), Ok(KeyPhase::Current));
315        assert_eq!(table.phase(3), Ok(KeyPhase::Previous));
316        assert_eq!(table.phase(2), Ok(KeyPhase::Stale));
317        assert_eq!(table.phase(1), Err(QdnfError::Expired));
318        assert_eq!(table.phase(99), Err(QdnfError::Expired));
319        assert_eq!(table.keys(1), Err(QdnfError::Expired));
320        assert_ne!(table.keys(4).unwrap(), first);
321    }
322
323    #[test]
324    fn rekey_and_replayed_cache_do_not_renew_authority() {
325        assert!(!rekey_renews_service_authority());
326        assert!(!replayed_cached_allow_renews_grant());
327    }
328
329    #[test]
330    fn admit_after_rekey_stale_grant_unauthorized_when_active_allow() {
331        let s = binding(SessionState::Active, PolicyOutcome::Allow);
332        assert_eq!(s.admit_application(), Ok(()));
333        assert_eq!(admit_after_rekey(&s, false), Err(QdnfError::Unauthorized));
334    }
335
336    #[test]
337    fn admit_after_rekey_active_allow_current_grant_ok() {
338        let s = binding(SessionState::Active, PolicyOutcome::Allow);
339        assert_eq!(admit_after_rekey(&s, true), Ok(()));
340    }
341
342    #[test]
343    fn admit_after_rekey_draining_is_closed() {
344        let s = binding(SessionState::Draining, PolicyOutcome::Allow);
345        assert_eq!(admit_after_rekey(&s, true), Err(QdnfError::Closed));
346    }
347
348    #[test]
349    fn traffic_update_is_not_hybrid_recovery() {
350        assert!(!traffic_update_is_hybrid_recovery());
351    }
352
353    #[test]
354    fn rotate_zero_to_two_current_and_previous_phases() {
355        let mut table = RekeyTable::from_keys([1u8; 32], [2u8; 32]).unwrap();
356        assert_eq!(table.rotate(), Ok(2));
357        assert_eq!(table.rotate(), Ok(3));
358        assert_eq!(
359            table.phase(table.current_generation()),
360            Ok(KeyPhase::Current)
361        );
362        assert_eq!(table.phase(2), Ok(KeyPhase::Previous));
363    }
364
365    #[test]
366    fn rotate_derives_new_secrets_and_does_not_renew_grant() {
367        let mut table = RekeyTable::from_keys([7u8; 32], [8u8; 32]).unwrap();
368        let before = table.keys(1).unwrap();
369        table.rotate().unwrap();
370        let after = table.keys(2).unwrap();
371        assert_ne!(before, after);
372        assert!(!rekey_renews_service_authority());
373        let s = binding(SessionState::Active, PolicyOutcome::Allow);
374        assert_eq!(admit_after_rekey(&s, true), Ok(()));
375        assert_eq!(admit_after_rekey(&s, false), Err(QdnfError::Unauthorized));
376    }
377
378    #[test]
379    fn all_zero_or_equal_keys_are_rejected() {
380        assert!(RekeyTable::from_keys([0u8; 32], [1u8; 32]).is_err());
381        assert!(RekeyTable::from_keys([1u8; 32], [1u8; 32]).is_err());
382    }
383
384    #[test]
385    fn r04_retired_slot_is_zeroized_after_rotation_window() {
386        let mut table = RekeyTable::from_keys([3u8; 32], [4u8; 32]).unwrap();
387        assert!(!table.is_generation_zeroized(1));
388        table.rotate().unwrap(); // gen 2 current, [1] in old
389        table.rotate().unwrap(); // gen 3 current, [2, 1] in old
390        assert!(!table.is_generation_zeroized(1));
391        table.rotate().unwrap(); // gen 4 current, [3, 2] in old -> gen 1 erased
392        assert!(table.is_generation_zeroized(1));
393        assert_eq!(table.keys(1), Err(QdnfError::Expired));
394    }
395}