Skip to main content

qualia_core_db/net/qdnf/session/handshake/
fragmented.rs

1//! Production QSession hello exchange over admit-before-buffer fragments.
2//!
3//! ClientHello / ServerHello exceed a 1500-byte Ethernet MTU. The session path
4//! always splits through [`split_handshake`]. A split or admission failure is
5//! returned as-is; the whole hello is never sent as one datagram.
6
7use crate::crypto::network::kem::MlKem768Secret;
8use crate::crypto::network::mldsa;
9use crate::crypto::network::transcript::Transcript;
10use crate::net::qdnf::bearer::contract::{check_frame_mtu, Bearer};
11use crate::net::qdnf::bearer::fragment::{
12    admit_and_buffer, split_handshake, HandshakeReassembler, FRAG_HDR_LEN, MAX_FRAGMENTS,
13    MAX_FRAME, MAX_HANDSHAKE_BYTES,
14};
15use crate::net::qdnf::bearer::mtu::{negotiate_mtu, unfragmented_fit, MAX_QDNF_MTU, MIN_QDNF_MTU};
16use crate::net::qdnf::crypto::finished::{finished_mac, verify_finished};
17use crate::net::qdnf::crypto::handshake::failures::entropy_fill;
18use crate::net::qdnf::crypto::handshake::{
19    initiator_complete, initiator_share, qualified_handshake_gate, reject_unknown_key_share,
20    require_bound_identities, responder_complete, HandshakeState, FORBIDDEN_ZERO_RTT,
21};
22use crate::net::qdnf::crypto::schedule::{derive_handshake_keys, HandshakeKeys};
23use crate::net::qdnf::errors::QdnfError;
24use crate::net::qdnf::frame::{
25    copy_payload, decode_frame, encode_frame, FrameHeader, BASE_HEADER_LEN,
26};
27use crate::net::qdnf::registries::{flags, FrameType, NextProtocol};
28use crate::net::qdnf::types::{ObservedLocator, StrongDigest};
29
30use super::hello::{
31    decode_client_hello, decode_server_hello, encode_client_hello_with_certs,
32    encode_server_hello_with_certs, CLIENT_HELLO_WIRE_LEN, SERVER_HELLO_WIRE_LEN,
33};
34
35const CLIENT_HELLO_MSG: u32 = 1;
36const SERVER_HELLO_MSG: u32 = 2;
37
38const _: () = assert!(FORBIDDEN_ZERO_RTT);
39
40/// Completed fragmented handshake. Finished tags are HMAC-SHA-384.
41#[derive(Clone, Copy)]
42pub struct FragmentedHandshake {
43    pub keys: HandshakeKeys,
44    pub finished_i2r: StrongDigest,
45    pub finished_r2i: StrongDigest,
46    pub client_fragments: usize,
47    pub server_fragments: usize,
48}
49
50/// Bytes of hello after QFrame and fragment headers on a negotiated MTU.
51pub fn hello_fragment_payload_mtu(mtu: u16) -> Result<u16, QdnfError> {
52    if mtu < MIN_QDNF_MTU {
53        return Err(QdnfError::Range);
54    }
55    let inner = (mtu as usize)
56        .checked_sub(BASE_HEADER_LEN)
57        .ok_or(QdnfError::Range)?;
58    if inner <= FRAG_HDR_LEN {
59        return Err(QdnfError::Range);
60    }
61    u16::try_from(inner - FRAG_HDR_LEN).map_err(|_| QdnfError::Range)
62}
63
64/// Split `hello` and send each fragment as a QFrame. Split failure is fatal.
65pub fn send_hello_fragments<B: Bearer>(
66    sender: &mut B,
67    dest: &ObservedLocator,
68    msg_id: u32,
69    hello: &[u8],
70    mtu: u16,
71    frame_type: FrameType,
72) -> Result<usize, QdnfError> {
73    let payload_mtu = hello_fragment_payload_mtu(mtu)?;
74    send_hello_fragments_at(sender, dest, msg_id, hello, mtu, payload_mtu, frame_type)
75}
76
77fn send_hello_fragments_at<B: Bearer>(
78    sender: &mut B,
79    dest: &ObservedLocator,
80    msg_id: u32,
81    hello: &[u8],
82    mtu: u16,
83    payload_mtu: u16,
84    frame_type: FrameType,
85) -> Result<usize, QdnfError> {
86    if hello.is_empty() {
87        return Err(QdnfError::Malformed);
88    }
89    // Whole-datagram send of an oversize hello is Capacity. Never used as fallback.
90    if hello.len() > mtu as usize {
91        let _ = unfragmented_fit(hello.len(), mtu);
92        let _ = check_frame_mtu(hello.len(), mtu);
93    }
94    let mut frames = [[0u8; MAX_FRAME]; MAX_FRAGMENTS];
95    let mut lens = [0usize; MAX_FRAGMENTS];
96    let n = split_handshake(msg_id, hello, payload_mtu, &mut frames, &mut lens)?;
97    let mut i = 0usize;
98    while i < n {
99        let mut header = FrameHeader::new(frame_type, NextProtocol::QSession);
100        header.flags |= flags::FRAGMENT;
101        header.payload_len = u16::try_from(lens[i]).map_err(|_| QdnfError::Capacity)?;
102        let mut wire = [0u8; MAX_QDNF_MTU as usize];
103        let wn = encode_frame(&header, &frames[i][..lens[i]], &mut wire)?;
104        if wn > mtu as usize {
105            return Err(QdnfError::Capacity);
106        }
107        let sent = sender.send(dest, &wire[..wn])?;
108        if sent != wn {
109            return Err(QdnfError::WouldBlock);
110        }
111        i += 1;
112    }
113    Ok(n)
114}
115
116fn recv_hello_fragments<B: Bearer>(
117    recv: &mut B,
118    expected: FrameType,
119    reassembler: &mut HandshakeReassembler,
120    out: &mut [u8],
121) -> Result<usize, QdnfError> {
122    let mut seen = 0usize;
123    loop {
124        if seen >= MAX_FRAGMENTS {
125            return Err(QdnfError::Capacity);
126        }
127        let mut wire = [0u8; MAX_QDNF_MTU as usize];
128        let (got, _meta) = recv.recv(&mut wire)?;
129        let (decoded, off, len) = decode_frame(&wire[..got])?;
130        if decoded.frame_type != expected || decoded.next_protocol != NextProtocol::QSession {
131            return Err(QdnfError::Malformed);
132        }
133        if !decoded.is_fragment() {
134            return Err(QdnfError::Capacity);
135        }
136        let mut payload = [0u8; MAX_FRAME];
137        let copied = copy_payload(&wire[..got], off, len, &mut payload)?;
138        match admit_and_buffer(reassembler, &payload[..copied], out)? {
139            Some(n) => return Ok(n),
140            None => seen += 1,
141        }
142    }
143}
144
145fn distinct_x25519() -> Result<([u8; 32], [u8; 32]), QdnfError> {
146    let mut a = [0u8; 32];
147    let mut b = [0u8; 32];
148    entropy_fill(&mut a)?;
149    entropy_fill(&mut b)?;
150    if a == b {
151        b[0] ^= 0x5a;
152        if b.iter().all(|x| *x == 0) {
153            return Err(QdnfError::EntropyFailure);
154        }
155    }
156    Ok((a, b))
157}
158
159fn bind_handshake_transcript(
160    initiator_id: &StrongDigest,
161    responder_id: &StrongDigest,
162    i_x: &[u8; 32],
163    r_x: &[u8; 32],
164) -> Result<Transcript, QdnfError> {
165    let mut t = Transcript::new();
166    t.append(b"suite", b"qpr-pq-1")?;
167    t.append(b"initiator", initiator_id.as_bytes())?;
168    t.append(b"responder", responder_id.as_bytes())?;
169    t.append(b"i-x", i_x)?;
170    t.append(b"r-x", r_x)?;
171    t.append(b"0rtt", &[0])?;
172    require_bound_identities(&t, initiator_id, responder_id)?;
173    reject_unknown_key_share(*responder_id, *responder_id)?;
174    Ok(t)
175}
176
177/// Hybrid handshake over fragmented ClientHello / ServerHello on `mtu ≤ 1500`.
178///
179/// Fragment split or admission failure is returned. The whole hello is not sent.
180pub fn handshake_over_fragments<I, R>(
181    initiator: &mut I,
182    responder: &mut R,
183    initiator_dest: &ObservedLocator,
184    responder_dest: &ObservedLocator,
185    initiator_id: &StrongDigest,
186    responder_id: &StrongDigest,
187) -> Result<FragmentedHandshake, QdnfError>
188where
189    I: Bearer,
190    R: Bearer,
191{
192    if initiator_id.is_zero() || responder_id.is_zero() || initiator_id == responder_id {
193        return Err(QdnfError::Unauthorized);
194    }
195    // PQ hellos exceed Ethernet MTU. Cap even when the local bearer is larger
196    // (local-ipc 8192) so the public path still fragments instead of whole-datagram.
197    let negotiated = negotiate_mtu(initiator.mtu(), responder.mtu())?;
198    let mtu = core::cmp::min(negotiated, MAX_QDNF_MTU);
199    let (sk, pk) = MlKem768Secret::generate()?;
200    let (i_x, r_x) = distinct_x25519()?;
201    let ishare = initiator_share(&i_x, &pk)?;
202
203    let (i_mldsa_sk, i_mldsa_pk) = mldsa::generate_keypair()?;
204    let (r_mldsa_sk, r_mldsa_pk) = mldsa::generate_keypair()?;
205    let mut i_ed = [0u8; 32];
206    let mut r_ed = [0u8; 32];
207    entropy_fill(&mut i_ed)?;
208    entropy_fill(&mut r_ed)?;
209
210    let mut client = [0u8; CLIENT_HELLO_WIRE_LEN];
211    let cn = encode_client_hello_with_certs(&ishare, &i_mldsa_sk, &i_mldsa_pk, &i_ed, &mut client)?;
212    if cn != CLIENT_HELLO_WIRE_LEN || cn <= MAX_QDNF_MTU as usize {
213        return Err(QdnfError::Malformed);
214    }
215    if unfragmented_fit(cn, mtu).is_ok() {
216        return Err(QdnfError::Capacity);
217    }
218
219    let client_fragments = send_hello_fragments(
220        initiator,
221        initiator_dest,
222        CLIENT_HELLO_MSG,
223        &client[..cn],
224        mtu,
225        FrameType::SessionChallenge,
226    )?;
227    if client_fragments < 2 {
228        return Err(QdnfError::Capacity);
229    }
230
231    let mut reassembled = [0u8; MAX_HANDSHAKE_BYTES];
232    let mut rx = HandshakeReassembler::new();
233    let got = recv_hello_fragments(
234        responder,
235        FrameType::SessionChallenge,
236        &mut rx,
237        &mut reassembled,
238    )?;
239    if got != cn {
240        return Err(QdnfError::Malformed);
241    }
242    let peer_ishare = decode_client_hello(&reassembled[..got])?;
243
244    let (rshare, r_kem, r_dh) = responder_complete(&peer_ishare, &r_x)?;
245    let mut server = [0u8; SERVER_HELLO_WIRE_LEN];
246    let sn = encode_server_hello_with_certs(&rshare, &r_mldsa_sk, &r_mldsa_pk, &r_ed, &mut server)?;
247    if sn != SERVER_HELLO_WIRE_LEN || sn <= MAX_QDNF_MTU as usize {
248        return Err(QdnfError::Malformed);
249    }
250    if unfragmented_fit(sn, mtu).is_ok() {
251        return Err(QdnfError::Capacity);
252    }
253
254    let server_fragments = send_hello_fragments(
255        responder,
256        responder_dest,
257        SERVER_HELLO_MSG,
258        &server[..sn],
259        mtu,
260        FrameType::SessionProof,
261    )?;
262    if server_fragments < 2 {
263        return Err(QdnfError::Capacity);
264    }
265
266    let mut rx2 = HandshakeReassembler::new();
267    let got_s = recv_hello_fragments(
268        initiator,
269        FrameType::SessionProof,
270        &mut rx2,
271        &mut reassembled,
272    )?;
273    if got_s != sn {
274        return Err(QdnfError::Malformed);
275    }
276    let peer_rshare = decode_server_hello(&reassembled[..got_s])?;
277    let (i_kem, i_dh) = initiator_complete(&sk, &i_x, &peer_rshare)?;
278    if i_kem != r_kem || i_dh != r_dh {
279        return Err(QdnfError::CryptoFailure);
280    }
281
282    let t = bind_handshake_transcript(
283        initiator_id,
284        responder_id,
285        &ishare.x25519_pk,
286        &peer_rshare.x25519_pk,
287    )?;
288    let keys = derive_handshake_keys(&i_kem, &i_dh, &t)?;
289    let finished_i2r = finished_mac(&keys.initiator_to_responder, &keys.transcript_digest, true)?;
290    let finished_r2i = finished_mac(&keys.responder_to_initiator, &keys.transcript_digest, false)?;
291    verify_finished(
292        &keys.initiator_to_responder,
293        &keys.transcript_digest,
294        true,
295        &finished_i2r,
296    )?;
297    verify_finished(
298        &keys.responder_to_initiator,
299        &keys.transcript_digest,
300        false,
301        &finished_r2i,
302    )?;
303    qualified_handshake_gate(HandshakeState::Traffic)?;
304    Ok(FragmentedHandshake {
305        keys,
306        finished_i2r,
307        finished_r2i,
308        client_fragments,
309        server_fragments,
310    })
311}
312
313#[cfg(test)]
314mod tests {
315    use super::*;
316    use crate::crypto::network::digest::sha384;
317    use crate::net::qdnf::bearer::ipc_pair;
318    use crate::net::qdnf::harness::oracles::{independent_finished, unkeyed_finished_defect};
319    use crate::net::qdnf::types::ScopeEpoch;
320
321    fn ids() -> (StrongDigest, StrongDigest) {
322        (sha384(b"did:q42:a"), sha384(b"did:q42:b"))
323    }
324
325    #[test]
326    fn oversized_hello_is_fragmented_admitted_reassembled_hmac_sha384() {
327        let scope = ScopeEpoch { scope: 1, epoch: 1 };
328        let (mut a, mut b) = ipc_pair(scope, MAX_QDNF_MTU).unwrap();
329        let dest_b = b.locator();
330        let dest_a = a.locator();
331        let (id_a, id_b) = ids();
332        let done =
333            handshake_over_fragments(&mut a, &mut b, &dest_b, &dest_a, &id_a, &id_b).unwrap();
334        assert!(done.client_fragments >= 2);
335        assert!(done.server_fragments >= 2);
336        assert_ne!(
337            done.keys.initiator_to_responder,
338            done.keys.responder_to_initiator
339        );
340        assert_eq!(
341            done.finished_i2r,
342            independent_finished(
343                &done.keys.initiator_to_responder,
344                &done.keys.transcript_digest,
345                true
346            )
347        );
348        assert_eq!(
349            done.finished_r2i,
350            independent_finished(
351                &done.keys.responder_to_initiator,
352                &done.keys.transcript_digest,
353                false
354            )
355        );
356        assert_ne!(
357            done.finished_i2r,
358            unkeyed_finished_defect(&done.keys.transcript_digest, b"qpr-pq-1/finished/i2r")
359        );
360        assert_ne!(done.finished_i2r, done.finished_r2i);
361        verify_finished(
362            &done.keys.initiator_to_responder,
363            &done.keys.transcript_digest,
364            true,
365            &done.finished_i2r,
366        )
367        .unwrap();
368    }
369
370    #[test]
371    fn oversize_hello_without_admission_is_capacity() {
372        assert!(CLIENT_HELLO_WIRE_LEN > MAX_QDNF_MTU as usize);
373        assert_eq!(
374            unfragmented_fit(CLIENT_HELLO_WIRE_LEN, MAX_QDNF_MTU),
375            Err(QdnfError::Capacity)
376        );
377        assert_eq!(
378            check_frame_mtu(CLIENT_HELLO_WIRE_LEN, MAX_QDNF_MTU),
379            Err(QdnfError::Capacity)
380        );
381
382        let scope = ScopeEpoch { scope: 1, epoch: 1 };
383        let (mut a, b) = ipc_pair(scope, MAX_QDNF_MTU).unwrap();
384        let dest = b.locator();
385        let hello = [0x7Au8; CLIENT_HELLO_WIRE_LEN];
386        assert_eq!(a.send(&dest, &hello), Err(QdnfError::Capacity));
387
388        let mut header = FrameHeader::new(FrameType::SessionChallenge, NextProtocol::QSession);
389        header.payload_len = 4;
390        let mut wire = [0u8; 128];
391        let n = encode_frame(&header, &[1, 2, 3, 4], &mut wire).unwrap();
392        a.send(&dest, &wire[..n]).unwrap();
393        let mut rx = HandshakeReassembler::new();
394        let mut out = [0u8; 16];
395        let mut peer_b = b;
396        assert_eq!(
397            recv_hello_fragments(&mut peer_b, FrameType::SessionChallenge, &mut rx, &mut out),
398            Err(QdnfError::Capacity)
399        );
400        assert_eq!(rx.buffered_len(CLIENT_HELLO_MSG), 0);
401    }
402
403    #[test]
404    fn fragment_failure_does_not_fall_back_to_whole_datagram() {
405        let scope = ScopeEpoch { scope: 1, epoch: 1 };
406        let (mut a, mut b) = ipc_pair(scope, MAX_QDNF_MTU).unwrap();
407        let dest = b.locator();
408        let hello = [0x3Cu8; CLIENT_HELLO_WIRE_LEN];
409        assert_eq!(
410            send_hello_fragments_at(
411                &mut a,
412                &dest,
413                CLIENT_HELLO_MSG,
414                &hello,
415                MAX_QDNF_MTU,
416                400,
417                FrameType::SessionChallenge,
418            ),
419            Err(QdnfError::Capacity)
420        );
421        let mut out = [0u8; MAX_QDNF_MTU as usize];
422        assert_eq!(b.recv(&mut out), Err(QdnfError::WouldBlock));
423        assert_eq!(a.send(&dest, &hello), Err(QdnfError::Capacity));
424    }
425}