Skip to main content

qualia_core_db/net/qdnf/session/
packet.rs

1//! Caller-buffered packet numbers, 64-bit replay window, nonce construction,
2//! and QUIC-style bounded varints (NET-05.04 partial). Packages remain open.
3//!
4//! Packet numbers occupy `[0, MAX_PACKET_NUMBER]`. Retransmits use a fresh
5//! packet number; ciphertext/nonce reuse is forbidden.
6
7use crate::net::qdnf::errors::QdnfError;
8
9/// Sliding receive window width (one bit per packet number).
10pub const REPLAY_WINDOW: u64 = 64;
11
12/// Inclusive send/receive ceiling. The next allocate after this is exhaustion.
13pub const MAX_PACKET_NUMBER: u64 = (1u64 << 62) - 1;
14
15/// 12-byte AEAD nonce (4 zero bytes ‖ u64be packet number).
16pub const AEAD_NONCE_LEN: usize = 12;
17
18const VARINT_1: u64 = 1 << 6;
19const VARINT_2: u64 = 1 << 14;
20const VARINT_4: u64 = 1 << 30;
21
22#[repr(transparent)]
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
24pub struct PacketNumber(pub u64);
25
26/// Per encryption-level packet-number space: next send, largest received,
27/// and a 64-bit sliding replay bitmap (bit 0 = largest received).
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub struct PacketSpace {
30    next_send: u64,
31    largest_recv: u64,
32    recv_bits: u64,
33}
34
35impl PacketSpace {
36    /// Creates a default `PacketSpace`.
37    pub const fn new() -> Self {
38        Self {
39            next_send: 0,
40            largest_recv: 0,
41            recv_bits: 0,
42        }
43    }
44
45    /// Allocate next send pn. After [`MAX_PACKET_NUMBER`] → [`QdnfError::Expired`].
46    pub fn allocate_send(&mut self) -> Result<PacketNumber, QdnfError> {
47        if self.next_send > MAX_PACKET_NUMBER {
48            return Err(QdnfError::Expired);
49        }
50        let pn = PacketNumber(self.next_send);
51        self.next_send += 1;
52        Ok(pn)
53    }
54
55    /// Accept a received pn. Duplicate or too old → [`QdnfError::Replay`].
56    /// `pn > MAX_PACKET_NUMBER` → [`QdnfError::Range`].
57    pub fn accept_receive(&mut self, pn: PacketNumber) -> Result<(), QdnfError> {
58        if pn.0 > MAX_PACKET_NUMBER {
59            return Err(QdnfError::Range);
60        }
61        if self.recv_bits == 0 {
62            self.largest_recv = pn.0;
63            self.recv_bits = 1;
64            return Ok(());
65        }
66        if pn.0 > self.largest_recv {
67            let shift = pn.0 - self.largest_recv;
68            self.recv_bits = if shift >= REPLAY_WINDOW {
69                1
70            } else {
71                (self.recv_bits << shift) | 1
72            };
73            self.largest_recv = pn.0;
74            return Ok(());
75        }
76        let delta = self.largest_recv - pn.0;
77        if delta >= REPLAY_WINDOW {
78            return Err(QdnfError::Replay);
79        }
80        let bit = 1u64 << delta;
81        if self.recv_bits & bit != 0 {
82            return Err(QdnfError::Replay);
83        }
84        self.recv_bits |= bit;
85        Ok(())
86    }
87}
88
89/// 12-byte nonce: 4 zero bytes ‖ u64be(packet number). Never reuse a pn.
90pub fn nonce_from_packet_number(pn: PacketNumber, out: &mut [u8; AEAD_NONCE_LEN]) {
91    out[..4].fill(0);
92    out[4..].copy_from_slice(&pn.0.to_be_bytes());
93}
94
95/// Retransmit semantic frames under a fresh packet number, never the same nonce.
96pub fn reuse_packet_number_on_retransmit() -> bool {
97    false
98}
99
100#[inline]
101const fn varint_len(value: u64) -> usize {
102    if value < VARINT_1 {
103        1
104    } else if value < VARINT_2 {
105        2
106    } else if value < VARINT_4 {
107        4
108    } else {
109        8
110    }
111}
112
113/// QUIC-style bounded varint (1/2/4/8). Short `out` → [`QdnfError::Capacity`].
114/// `value > MAX_PACKET_NUMBER` → [`QdnfError::Range`].
115pub fn encode_varint(value: u64, out: &mut [u8]) -> Result<usize, QdnfError> {
116    if value > MAX_PACKET_NUMBER {
117        return Err(QdnfError::Range);
118    }
119    let len = varint_len(value);
120    if out.len() < len {
121        return Err(QdnfError::Capacity);
122    }
123    match len {
124        1 => out[0] = value as u8,
125        2 => {
126            let n = (value as u16) | 0x4000;
127            out[..2].copy_from_slice(&n.to_be_bytes());
128        }
129        4 => {
130            let n = (value as u32) | 0x8000_0000;
131            out[..4].copy_from_slice(&n.to_be_bytes());
132        }
133        _ => {
134            let n = value | 0xC000_0000_0000_0000;
135            out[..8].copy_from_slice(&n.to_be_bytes());
136        }
137    }
138    Ok(len)
139}
140
141/// Decode one bounded varint. Truncated input → [`QdnfError::Truncated`].
142/// Overlong / non-canonical encodings → [`QdnfError::Malformed`].
143pub fn decode_varint(src: &[u8]) -> Result<(u64, usize), QdnfError> {
144    let first = *src.first().ok_or(QdnfError::Truncated)?;
145    let len = 1usize << (first >> 6);
146    if src.len() < len {
147        return Err(QdnfError::Truncated);
148    }
149    let value = match len {
150        1 => first as u64,
151        2 => u16::from_be_bytes([src[0], src[1]]) as u64 & 0x3fff,
152        4 => u32::from_be_bytes([src[0], src[1], src[2], src[3]]) as u64 & 0x3fff_ffff,
153        8 => {
154            u64::from_be_bytes([
155                src[0], src[1], src[2], src[3], src[4], src[5], src[6], src[7],
156            ]) & MAX_PACKET_NUMBER
157        }
158        _ => return Err(QdnfError::Malformed),
159    };
160    if varint_len(value) != len {
161        return Err(QdnfError::Malformed);
162    }
163    Ok((value, len))
164}
165
166#[cfg(test)]
167impl PacketSpace {
168    fn set_next_send_for_test(&mut self, next: u64) {
169        self.next_send = next;
170    }
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    #[test]
178    fn allocate_zero_then_one_duplicate_receive_is_replay() {
179        let mut space = PacketSpace::new();
180        assert_eq!(space.allocate_send(), Ok(PacketNumber(0)));
181        assert_eq!(space.allocate_send(), Ok(PacketNumber(1)));
182        assert_eq!(space.accept_receive(PacketNumber(0)), Ok(()));
183        assert_eq!(
184            space.accept_receive(PacketNumber(0)),
185            Err(QdnfError::Replay)
186        );
187    }
188
189    #[test]
190    fn accept_below_window_is_replay() {
191        let mut space = PacketSpace::new();
192        assert_eq!(space.accept_receive(PacketNumber(0)), Ok(()));
193        assert_eq!(space.accept_receive(PacketNumber(REPLAY_WINDOW)), Ok(()));
194        assert_eq!(
195            space.accept_receive(PacketNumber(0)),
196            Err(QdnfError::Replay)
197        );
198    }
199
200    #[test]
201    fn allocate_after_max_is_expired() {
202        let mut space = PacketSpace::new();
203        space.set_next_send_for_test(MAX_PACKET_NUMBER);
204        assert_eq!(space.allocate_send(), Ok(PacketNumber(MAX_PACKET_NUMBER)));
205        assert_eq!(space.allocate_send(), Err(QdnfError::Expired));
206        space.set_next_send_for_test(MAX_PACKET_NUMBER + 1);
207        assert_eq!(space.allocate_send(), Err(QdnfError::Expired));
208    }
209
210    #[test]
211    fn nonce_from_packet_number_one_is_be_u64() {
212        let mut out = [0xffu8; AEAD_NONCE_LEN];
213        nonce_from_packet_number(PacketNumber(1), &mut out);
214        assert_eq!(&out[..4], &[0, 0, 0, 0]);
215        assert_eq!(&out[4..], &[0, 0, 0, 0, 0, 0, 0, 1]);
216    }
217
218    #[test]
219    fn reuse_packet_number_on_retransmit_is_false() {
220        assert!(!reuse_packet_number_on_retransmit());
221    }
222
223    #[test]
224    fn decode_varint_overlong_is_malformed() {
225        // 0 encoded as 2-byte (0x40 0x00) is non-canonical.
226        assert_eq!(decode_varint(&[0x40, 0x00]), Err(QdnfError::Malformed));
227        assert_eq!(decode_varint(&[0x00]), Ok((0, 1)));
228    }
229
230    #[test]
231    fn encode_varint_length_and_short_output() {
232        let mut one = [0u8; 1];
233        assert_eq!(encode_varint(63, &mut one), Ok(1));
234        assert_eq!(one[0], 63);
235        let mut two = [0u8; 2];
236        assert_eq!(encode_varint(64, &mut two), Ok(2));
237        assert_eq!(&two, &[0x40, 0x40]);
238        let mut short = [0u8; 1];
239        assert_eq!(encode_varint(64, &mut short), Err(QdnfError::Capacity));
240        assert_eq!(encode_varint(63, &mut []), Err(QdnfError::Capacity));
241    }
242
243    #[test]
244    fn accept_above_max_is_range() {
245        let mut space = PacketSpace::new();
246        assert_eq!(
247            space.accept_receive(PacketNumber(MAX_PACKET_NUMBER + 1)),
248            Err(QdnfError::Range)
249        );
250    }
251
252    #[test]
253    fn decode_varint_truncated() {
254        assert_eq!(decode_varint(&[]), Err(QdnfError::Truncated));
255        assert_eq!(decode_varint(&[0x40]), Err(QdnfError::Truncated));
256    }
257}