Skip to main content

rustnet_core/network/protocol/
tcp.rs

1//! TCP (Transmission Control Protocol) parsing
2
3use crate::network::dpi;
4use crate::network::parser::{ParsedPacket, ParserConfig};
5use crate::network::protocol::{TransportParams, orient_endpoints};
6use crate::network::types::{Protocol, ProtocolState, TcpState};
7
8const TCP_FIN: u8 = 0x01;
9const TCP_SYN: u8 = 0x02;
10const TCP_RST: u8 = 0x04;
11const TCP_ACK: u8 = 0x10;
12
13/// TCP flags from the TCP header
14#[derive(Debug, Clone, Copy)]
15pub struct TcpFlags {
16    pub fin: bool,
17    pub syn: bool,
18    pub rst: bool,
19    pub ack: bool,
20}
21
22/// TCP header information extracted from the packet
23#[derive(Debug, Clone, Copy)]
24pub struct TcpHeaderInfo {
25    pub seq: u32,         // Sequence number
26    pub ack: u32,         // Acknowledgment number
27    pub window: u16,      // Window size
28    pub flags: TcpFlags,  // TCP flags
29    pub payload_len: u32, // Actual TCP payload length (not including headers)
30    /// Window-scale verdict from the SYN's options (RFC 7323). Only ever
31    /// `Some` on a SYN segment; the option is illegal elsewhere.
32    pub window_scale: Option<SynWindowScale>,
33}
34
35/// What a SYN's options said about window scaling. `Absent` is a proven
36/// negative (the options were walked completely and carried no window-scale
37/// option), which is different from `Unknown` (truncated or malformed
38/// options), where no conclusion may be drawn: treating an unexamined SYN
39/// as a refusal would permanently disable scaling for the connection even
40/// when a complete retransmitted SYN later shows the option.
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum SynWindowScale {
43    /// The SYN offered window scaling with this shift.
44    Present(u8),
45    /// The options were fully examined and carry no window-scale option.
46    Absent,
47    /// The options could not be fully examined (capture truncation or a
48    /// malformed option); nothing can be concluded.
49    Unknown,
50}
51
52/// Highest shift RFC 7323 permits; larger advertised values are clamped.
53const MAX_WINDOW_SCALE: u8 = 14;
54
55/// Extract the window-scale verdict (option kind 3) from a SYN's option bytes.
56fn parse_window_scale(options: &[u8]) -> SynWindowScale {
57    let mut i = 0;
58    while i < options.len() {
59        match options[i] {
60            0 => return SynWindowScale::Absent, // End of option list
61            1 => i += 1,                        // NOP
62            kind => {
63                let Some(&len) = options.get(i + 1) else {
64                    return SynWindowScale::Unknown; // kind byte without length
65                };
66                let len = len as usize;
67                if len < 2 || i + len > options.len() {
68                    return SynWindowScale::Unknown; // Malformed, stop walking
69                }
70                if kind == 3 {
71                    // Kind 3 is exactly three bytes (RFC 7323); any other
72                    // length is a malformed option (RFC 9293) and proves
73                    // nothing, so it must not end the walk in Absent.
74                    return if len == 3 {
75                        SynWindowScale::Present(options[i + 2].min(MAX_WINDOW_SCALE))
76                    } else {
77                        SynWindowScale::Unknown
78                    };
79                }
80                i += len;
81            }
82        }
83    }
84    SynWindowScale::Absent
85}
86
87/// Parse TCP flags from the flags byte
88pub(crate) fn parse_tcp_flags(flags: u8) -> TcpFlags {
89    TcpFlags {
90        fin: (flags & TCP_FIN) != 0,
91        syn: (flags & TCP_SYN) != 0,
92        rst: (flags & TCP_RST) != 0,
93        ack: (flags & TCP_ACK) != 0,
94    }
95}
96
97/// Parse a TCP packet
98pub(crate) fn parse(
99    transport_data: &[u8],
100    params: TransportParams,
101    config: &ParserConfig,
102    local_ips: &std::collections::HashSet<std::net::IpAddr>,
103) -> Option<ParsedPacket> {
104    if transport_data.len() < 20 {
105        return None;
106    }
107
108    let src_port = u16::from_be_bytes([transport_data[0], transport_data[1]]);
109    let dst_port = u16::from_be_bytes([transport_data[2], transport_data[3]]);
110
111    let seq = u32::from_be_bytes([
112        transport_data[4],
113        transport_data[5],
114        transport_data[6],
115        transport_data[7],
116    ]);
117    let ack = u32::from_be_bytes([
118        transport_data[8],
119        transport_data[9],
120        transport_data[10],
121        transport_data[11],
122    ]);
123    let window = u16::from_be_bytes([transport_data[14], transport_data[15]]);
124    let flags = transport_data[13];
125
126    let tcp_flags = parse_tcp_flags(flags);
127
128    // Calculate actual TCP payload length. A data offset below 5 is invalid
129    // (RFC 9293 ยง3.1); treating it as a header length would make the
130    // payload overlap the header itself.
131    let tcp_header_len = ((transport_data[12] >> 4) as usize) * 4;
132    if tcp_header_len < 20 {
133        return None;
134    }
135    let tcp_payload_len = transport_data.len().saturating_sub(tcp_header_len) as u32;
136
137    // The window-scale option only appears on SYN segments. A capture
138    // truncated before the declared data offset (snaplen) cannot prove the
139    // option absent, so it yields Unknown rather than Absent.
140    let window_scale = if tcp_flags.syn {
141        Some(if transport_data.len() < tcp_header_len {
142            SynWindowScale::Unknown
143        } else if tcp_header_len > 20 {
144            parse_window_scale(&transport_data[20..tcp_header_len])
145        } else {
146            SynWindowScale::Absent
147        })
148    } else {
149        None
150    };
151
152    let tcp_header = TcpHeaderInfo {
153        seq,
154        ack,
155        window,
156        flags: tcp_flags,
157        payload_len: tcp_payload_len,
158        window_scale,
159    };
160
161    log::trace!(
162        "TCP flags: FIN={} SYN={} RST={} ACK={}",
163        tcp_flags.fin,
164        tcp_flags.syn,
165        tcp_flags.rst,
166        tcp_flags.ack
167    );
168
169    let (local_addr, remote_addr, is_outgoing) =
170        orient_endpoints(&params, src_port, dst_port, local_ips);
171
172    let dpi_result = if config.enable_dpi {
173        if transport_data.len() > tcp_header_len {
174            let payload = &transport_data[tcp_header_len..];
175            dpi::analyze_tcp_packet(payload, local_addr.port(), remote_addr.port(), is_outgoing)
176        } else {
177            None
178        }
179    } else {
180        None
181    };
182
183    let mut packet = ParsedPacket::new(
184        Protocol::Tcp,
185        local_addr,
186        remote_addr,
187        ProtocolState::Tcp(TcpState::Unknown),
188        is_outgoing,
189        params.packet_len,
190        params.process_name,
191        params.process_id,
192    );
193    packet.tcp_header = Some(tcp_header);
194    packet.dpi_result = dpi_result;
195    Some(packet)
196}
197
198#[cfg(test)]
199mod tests {
200    use super::*;
201
202    #[test]
203    fn test_tcp_flags_parsing() {
204        let flags = parse_tcp_flags(0x02); // SYN
205        assert!(flags.syn);
206        assert!(!flags.ack);
207        assert!(!flags.fin);
208
209        let flags = parse_tcp_flags(0x12); // SYN + ACK
210        assert!(flags.syn);
211        assert!(flags.ack);
212
213        let flags = parse_tcp_flags(0x11); // FIN + ACK
214        assert!(flags.fin);
215        assert!(flags.ack);
216    }
217
218    #[test]
219    fn window_scale_option_parsed() {
220        // MSS (kind 2, len 4), NOP, window scale (kind 3, len 3, shift 7)
221        let options = [2, 4, 0x05, 0xb4, 1, 3, 3, 7];
222        assert_eq!(parse_window_scale(&options), SynWindowScale::Present(7));
223    }
224
225    #[test]
226    fn window_scale_proven_absent() {
227        // MSS only, then end-of-options: a complete walk is a proven negative.
228        let options = [2, 4, 0x05, 0xb4, 0, 0, 0, 0];
229        assert_eq!(parse_window_scale(&options), SynWindowScale::Absent);
230        // Fully walked without hitting end-of-list is also proven.
231        let options = [2, 4, 0x05, 0xb4];
232        assert_eq!(parse_window_scale(&options), SynWindowScale::Absent);
233    }
234
235    #[test]
236    fn window_scale_clamped_to_rfc_max() {
237        let options = [3, 3, 60];
238        assert_eq!(parse_window_scale(&options), SynWindowScale::Present(14));
239    }
240
241    #[test]
242    fn window_scale_unknown_on_malformed_options() {
243        // Malformed options prove nothing: they must not read as a refusal.
244        // Option claims a length running past the buffer
245        let options = [2, 40, 0x05];
246        assert_eq!(parse_window_scale(&options), SynWindowScale::Unknown);
247        // Zero-length option must not loop forever
248        let options = [5, 0, 3, 3, 7];
249        assert_eq!(parse_window_scale(&options), SynWindowScale::Unknown);
250        // Truncated: kind byte with no length byte
251        let options = [3];
252        assert_eq!(parse_window_scale(&options), SynWindowScale::Unknown);
253    }
254
255    #[test]
256    fn window_scale_with_illegal_length_is_unknown() {
257        // Kind 3 is exactly three bytes; other lengths are malformed and
258        // must not read as a proven absence.
259        let options = [3, 2];
260        assert_eq!(parse_window_scale(&options), SynWindowScale::Unknown);
261        let options = [3, 4, 7, 0];
262        assert_eq!(parse_window_scale(&options), SynWindowScale::Unknown);
263    }
264}