Skip to main content

qualia_core_db/net/qdnf/session/
protected_ack.rs

1//! ACK/loss/credit integration with protected packet numbers (E09.1).
2//!
3//! Duplicate and reordered authenticated packets must not close the session.
4//! Retransmits allocate a fresh packet number. Replay is dropped, not fatal.
5
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::session::loss::{AckFrame, SentTable, SENT_HISTORY};
8use crate::net::qdnf::session::packet_protection::{PacketProtection, OVERHEAD, PN_LEN};
9use crate::net::qdnf::types::Generation;
10
11#[repr(u8)]
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum ProtectedRecv {
14    Delivered = 0,
15    Duplicate = 1,
16}
17
18pub struct ProtectedAckSession {
19    protection: PacketProtection,
20    sent: SentTable,
21    closed: bool,
22}
23
24impl ProtectedAckSession {
25    /// Builds `ProtectedAckSession` from `keys`.
26    pub fn from_keys(
27        send_key: [u8; 32],
28        recv_key: [u8; 32],
29        generation: Generation,
30    ) -> Result<Self, QdnfError> {
31        Ok(Self {
32            protection: PacketProtection::from_keys(send_key, recv_key, generation)?,
33            sent: SentTable::new(),
34            closed: false,
35        })
36    }
37
38    #[inline]
39    /// `true` when closed.
40    pub const fn is_closed(&self) -> bool {
41        self.closed
42    }
43
44    #[inline]
45    /// `ProtectedAckSession::in_flight`.
46    pub fn in_flight(&self) -> usize {
47        self.sent.in_flight_count()
48    }
49
50    /// Seal application bytes and record the allocated packet number.
51    pub fn seal_tracked(
52        &mut self,
53        aad: &[u8],
54        plaintext: &mut [u8],
55        out: &mut [u8],
56    ) -> Result<usize, QdnfError> {
57        if self.closed {
58            return Err(QdnfError::Closed);
59        }
60        let n = self.protection.seal(aad, plaintext, out)?;
61        let pn = packet_number_of(out, n)?;
62        self.sent.record_send(pn)?;
63        Ok(n)
64    }
65
66    /// Open a sealed packet. Replay/duplicates are dropped without closing.
67    pub fn open_tracked(
68        &mut self,
69        aad: &[u8],
70        sealed: &[u8],
71        out: &mut [u8],
72    ) -> Result<(ProtectedRecv, usize), QdnfError> {
73        if self.closed {
74            return Err(QdnfError::Closed);
75        }
76        match self.protection.open(aad, sealed, out) {
77            Ok(n) => Ok((ProtectedRecv::Delivered, n)),
78            Err(QdnfError::Replay) => Ok((ProtectedRecv::Duplicate, 0)),
79            Err(e) => Err(e),
80        }
81    }
82
83    /// Apply authenticated ACK ranges to in-flight ownership. Unknown PNs
84    /// that are not in the sent table are ignored per range member that was
85    /// never sent; a range that matches nothing is Malformed.
86    pub fn apply_ack(&mut self, ack: &AckFrame) -> Result<usize, QdnfError> {
87        if self.closed {
88            return Err(QdnfError::Closed);
89        }
90        if ack.range_count() == 0 {
91            return Err(QdnfError::Malformed);
92        }
93        let mut retired = 0usize;
94        let mut i = 0usize;
95        while i < SENT_HISTORY {
96            if let Some(pn) = self.sent.packet_at(i) {
97                if ack.contains(pn) {
98                    self.sent.on_ack(pn)?;
99                    retired = retired.saturating_add(1);
100                }
101            }
102            i += 1;
103        }
104        if retired == 0 {
105            return Err(QdnfError::Malformed);
106        }
107        Ok(retired)
108    }
109
110    /// Retransmit the same application bytes under a fresh packet number.
111    pub fn retransmit(
112        &mut self,
113        aad: &[u8],
114        plaintext: &mut [u8],
115        out: &mut [u8],
116    ) -> Result<usize, QdnfError> {
117        self.seal_tracked(aad, plaintext, out)
118    }
119
120    /// Install new traffic keys via [`PacketProtection::install_update`].
121    /// The immediately previous generation remains openable during overlap.
122    /// Sent-table ownership starts a new packet-number space.
123    pub fn install_update(
124        &mut self,
125        send_key: [u8; 32],
126        recv_key: [u8; 32],
127        generation: Generation,
128    ) -> Result<(), QdnfError> {
129        self.protection
130            .install_update(send_key, recv_key, generation)?;
131        self.sent = SentTable::new();
132        Ok(())
133    }
134}
135
136/// Packet number for the ack.
137pub fn packet_number_of(sealed: &[u8], len: usize) -> Result<u64, QdnfError> {
138    if len < OVERHEAD || sealed.len() < PN_LEN {
139        return Err(QdnfError::Truncated);
140    }
141    let bytes: [u8; 8] = sealed[..PN_LEN].try_into().map_err(|_| QdnfError::Range)?;
142    Ok(u64::from_be_bytes(bytes))
143}
144
145#[cfg(test)]
146mod tests {
147    use super::*;
148
149    fn pair() -> (ProtectedAckSession, ProtectedAckSession) {
150        let a = ProtectedAckSession::from_keys([1u8; 32], [2u8; 32], Generation(1)).unwrap();
151        let b = ProtectedAckSession::from_keys([2u8; 32], [1u8; 32], Generation(1)).unwrap();
152        (a, b)
153    }
154
155    #[test]
156    fn reorder_and_duplicate_do_not_close() {
157        let (mut a, mut b) = pair();
158        let mut sealed = [[0u8; 64]; 3];
159        let mut lens = [0usize; 3];
160        let mut i = 0usize;
161        while i < 3 {
162            let mut pt = *b"pkt-body";
163            lens[i] = a.seal_tracked(b"aad", &mut pt, &mut sealed[i]).unwrap();
164            i += 1;
165        }
166        assert_eq!(a.in_flight(), 3);
167        let order = [2usize, 0, 1];
168        let mut delivered = 0u8;
169        let mut j = 0usize;
170        while j < 3 {
171            let idx = order[j];
172            let mut out = [0u8; 16];
173            let (kind, n) = b
174                .open_tracked(b"aad", &sealed[idx][..lens[idx]], &mut out)
175                .unwrap();
176            assert_eq!(kind, ProtectedRecv::Delivered);
177            assert_eq!(n, 8);
178            delivered = delivered.saturating_add(1);
179            j += 1;
180        }
181        let mut out = [0u8; 16];
182        let (dup, n) = b
183            .open_tracked(b"aad", &sealed[0][..lens[0]], &mut out)
184            .unwrap();
185        assert_eq!(dup, ProtectedRecv::Duplicate);
186        assert_eq!(n, 0);
187        assert!(!a.is_closed());
188        assert!(!b.is_closed());
189        assert_eq!(delivered, 3);
190    }
191
192    #[test]
193    fn ack_retires_in_flight_and_unknown_ack_is_malformed() {
194        let (mut a, mut b) = pair();
195        let mut pt = *b"hello-qpr";
196        let mut sealed = [0u8; 64];
197        let n = a.seal_tracked(b"aad", &mut pt, &mut sealed).unwrap();
198        let pn = packet_number_of(&sealed, n).unwrap();
199        let mut out = [0u8; 16];
200        b.open_tracked(b"aad", &sealed[..n], &mut out).unwrap();
201        let mut ack = AckFrame::new();
202        ack.insert_range(pn, pn).unwrap();
203        assert_eq!(a.apply_ack(&ack).unwrap(), 1);
204        assert_eq!(a.in_flight(), 0);
205        let mut bogus = AckFrame::new();
206        bogus.insert_range(99, 99).unwrap();
207        assert_eq!(a.apply_ack(&bogus), Err(QdnfError::Malformed));
208        assert!(!a.is_closed());
209    }
210
211    #[test]
212    fn previous_generation_in_flight_opens_during_overlap() {
213        use crate::net::qdnf::session::rekey::MAX_OLD_KEYS;
214        let (mut a, mut b) = pair();
215        let mut pt = *b"hello-qpr";
216        let mut sealed_old = [0u8; 64];
217        let n_old = a.seal_tracked(b"aad", &mut pt, &mut sealed_old).unwrap();
218        a.install_update([3u8; 32], [4u8; 32], Generation(2))
219            .unwrap();
220        b.install_update([4u8; 32], [3u8; 32], Generation(2))
221            .unwrap();
222        let mut out = [0u8; 16];
223        let (kind, n) = b
224            .open_tracked(b"aad", &sealed_old[..n_old], &mut out)
225            .unwrap();
226        assert_eq!(kind, ProtectedRecv::Delivered);
227        assert_eq!(&out[..n], b"hello-qpr");
228        let mut gen = 2u64;
229        let mut k = 5u8;
230        while gen < 2 + MAX_OLD_KEYS as u64 {
231            gen += 1;
232            a.install_update([k; 32], [k.wrapping_add(1); 32], Generation(gen))
233                .unwrap();
234            b.install_update([k.wrapping_add(1); 32], [k; 32], Generation(gen))
235                .unwrap();
236            k = k.wrapping_add(2);
237        }
238        assert_eq!(
239            b.open_tracked(b"aad", &sealed_old[..n_old], &mut out),
240            Err(QdnfError::CryptoFailure)
241        );
242        assert!(!b.is_closed());
243    }
244
245    #[test]
246    fn retransmit_uses_fresh_packet_number() {
247        let (mut a, _b) = pair();
248        let mut pt = *b"hello-qpr";
249        let mut first = [0u8; 64];
250        let n1 = a.seal_tracked(b"aad", &mut pt, &mut first).unwrap();
251        let pn1 = packet_number_of(&first, n1).unwrap();
252        let mut pt2 = *b"hello-qpr";
253        let mut second = [0u8; 64];
254        let n2 = a.retransmit(b"aad", &mut pt2, &mut second).unwrap();
255        let pn2 = packet_number_of(&second, n2).unwrap();
256        assert_ne!(pn1, pn2);
257        assert_eq!(a.in_flight(), 2);
258        assert!(!crate::net::qdnf::session::loss::reuse_packet_number_on_retransmit());
259    }
260}