netstack3_base/tcp/
base.rs

1// Copyright 2024 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! The Transmission Control Protocol (TCP).
6
7use core::iter::FromIterator;
8use core::ops::Range;
9
10use alloc::vec::Vec;
11use core::mem::MaybeUninit;
12use core::num::NonZeroU16;
13use net_types::ip::{Ip, IpVersion};
14use packet::InnerPacketBuilder;
15use static_assertions::const_assert;
16
17use crate::ip::Mms;
18use crate::tcp::segment::{Payload, PayloadLen, SegmentOptions};
19
20/// Control flags that can alter the state of a TCP control block.
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub enum Control {
23    /// Corresponds to the SYN bit in a TCP segment.
24    SYN,
25    /// Corresponds to the FIN bit in a TCP segment.
26    FIN,
27    /// Corresponds to the RST bit in a TCP segment.
28    RST,
29}
30
31impl Control {
32    /// Returns whether the control flag consumes one byte from the sequence
33    /// number space.
34    pub fn has_sequence_no(self) -> bool {
35        match self {
36            Control::SYN | Control::FIN => true,
37            Control::RST => false,
38        }
39    }
40}
41
42const TCP_HEADER_LEN: u32 = packet_formats::tcp::HDR_PREFIX_LEN as u32;
43
44/// Maximum segment size, that is the maximum TCP payload one segment can carry.
45///
46/// `Mss` also acts as a witness that the contained value is >= `Mss::MIN`.
47#[derive(Clone, Copy, PartialEq, Eq, Debug, PartialOrd, Ord)]
48pub struct Mss(u16);
49
50const_assert!(Mss::MIN.get() <= Mss::DEFAULT_IPV4.get());
51const_assert!(Mss::MIN.get() <= Mss::DEFAULT_IPV6.get());
52const_assert!(Mss::MIN.get() as usize >= packet_formats::tcp::MAX_OPTIONS_LEN);
53
54impl Mss {
55    /// The minimum MSS allowed by TCP.
56    ///
57    /// Although enforcing a minimum MSS is outside the recommendations of any
58    /// RFC, it is a common practice on other platforms and has multiple
59    /// benefits:
60    ///   1) Ensures there is enough space to transmit TCP Options & IP Options.
61    ///      See RFC 6691 section 2, which clarifies that
62    ///          The TCP MSS OPTION [...] SHOULD NOT be decreased to account for
63    ///          any possible IP or TCP options; conversely, the sender MUST
64    ///          reduce the TCP data length to account for any IP or TCP options
65    ///          that it is including in the packets that it sends.
66    ///   2) Protects against DOS attacks in which the attacker initiates TCP
67    ///      connections with an intentionally small MSS to incur additional
68    ///      packet processing overhead on the victim. See
69    ///      * FreeBSD: https://www.cve.org/CVERecord?id=CVE-2004-0002
70    ///      * Linux: https://www.cve.org/CVERecord?id=CVE-2019-11479
71    ///
72    /// Here, the value 216 is inspired by FreeBSD. It's large enough to satisfy
73    /// points 1 & 2 from above, while remaining small enough to support all
74    /// link-layer technologies on the open Internet.
75    pub const MIN: Mss = Mss(216);
76
77    /// Per RFC 9293 Section 3.7.1:
78    ///  If an MSS Option is not received at connection setup, TCP
79    ///  implementations MUST assume a default send MSS of 536 (576 - 40) for
80    ///  IPv4.
81    pub const DEFAULT_IPV4: Mss = Mss(536);
82
83    /// Per RFC 9293 Section 3.7.1:
84    ///  If an MSS Option is not received at connection setup, TCP
85    ///  implementations MUST assume a default send MSS of [...] 1220
86    /// (1280 - 60) for IPv6 (MUST-15).
87    pub const DEFAULT_IPV6: Mss = Mss(1220);
88
89    /// Creates `Mss`, provided the given value satisfies the requirements.
90    pub const fn new(mss: u16) -> Option<Self> {
91        if mss < Self::MIN.get() { None } else { Some(Mss(mss)) }
92    }
93
94    /// Creates MSS from the maximum message size of the IP layer.
95    pub fn from_mms(mms: Mms) -> Option<Self> {
96        let mss = u16::try_from(mms.get().get().saturating_sub(TCP_HEADER_LEN)).unwrap_or(u16::MAX);
97        Self::new(mss)
98    }
99
100    /// Create a new [`Mss`] with the IP-version default value, as defined by RFC 9293.
101    pub const fn default<I: Ip>() -> Self {
102        match I::VERSION {
103            IpVersion::V4 => Self::DEFAULT_IPV4,
104            IpVersion::V6 => Self::DEFAULT_IPV6,
105        }
106    }
107
108    /// Gets the numeric value of the MSS.
109    pub const fn get(&self) -> u16 {
110        let Self(mss) = *self;
111        mss
112    }
113}
114
115/// Like [`Mss`], but smaller to account for fixed-size TCP Options.
116///
117/// This corresponds to the "effective send MSS" as defined in RFC 9293 section
118/// 3.7.1:
119///   Eff.snd.MSS = min(SendMSS+20, MMS_S) - TCPhdrsize - IPoptionsize
120///   where:
121///     [...]
122///     * TCPhdrsize is the size of the fixed TCP header and any options.
123///
124/// Both [`Mss`] and [`EffectiveMss`] have their place in TCP. For example,
125/// the TCP MSS option has [`Mss`] semantics, while the MSS used to calculate
126/// receive windows & congestion windows has [`EffectiveMss`] semantics. When
127/// implementing a TCP feature, refer to the feature's RFC to determine which
128/// MSS semantics are appropriate to use.
129///
130/// Note: this implementation accounts for all fixed-sized TCP Options that are
131/// part of [`SegmentOptions`]. SACK blocks are ignored, because they are
132/// variable sized. Variable sized options pose a problem when calculating the
133/// [`EffectiveMss`] because they vary from segment to segment, whereas the
134/// [`EffectiveMss`] should be stable throughout the lifetime of the connection.
135/// While, no RFC explicitly states how to account for variable sized options,
136/// we take inspiration from Linux's TCP implementation and choose to ignore
137/// them until it comes time to actually calculate payload sizes for a given
138/// segment.
139// TODO(https://fxbug.dev/441271979): Account for fixed-size IP Options.
140#[derive(Clone, Copy, PartialEq, Eq, Debug)]
141pub struct EffectiveMss {
142    mss: Mss,
143    fixed_tcp_options_size: u16,
144}
145
146impl EffectiveMss {
147    /// Constructs an [`EffectiveMss`] from an [`Mss`]
148    pub const fn from_mss(mss: Mss, size_limits: MssSizeLimiters) -> Self {
149        let MssSizeLimiters { timestamp_enabled } = size_limits;
150        // NB: When adding additional fixed size options in the future, authors
151        // should take care to account for the alignment only once.
152        let fixed_tcp_options_size = if timestamp_enabled {
153            packet_formats::tcp::options::ALIGNED_TIMESTAMP_OPTION_LENGTH as u16
154        } else {
155            0
156        };
157        EffectiveMss { mss, fixed_tcp_options_size }
158    }
159
160    /// Computes the amount of payload data to include in a segment.
161    ///
162    /// Accounts for the size of any variable-sized options present in the
163    /// segment.
164    pub fn payload_size(&self, options: &SegmentOptions) -> NonZeroU16 {
165        let Self { mss, fixed_tcp_options_size } = self;
166        // Determine the length of the TCP Options. If we don't have any
167        // variable-sized options, we can use the already-known fixed size.
168        // otherwise we need to recalculate.
169        let SegmentOptions { timestamp: _, sack_blocks } = options;
170        let tcp_options_len = if sack_blocks.is_empty() {
171            *fixed_tcp_options_size
172        } else {
173            // NB: Safe to unwrap here because TCP options have a fixed maximum
174            // size < u16::MAX.
175            u16::try_from(options.builder().bytes_len()).unwrap()
176        };
177
178        // NB: Safe to unwrap here because MSS has a minimum value large enough
179        // to fit all TCP options.
180        NonZeroU16::new(mss.get() - tcp_options_len).unwrap()
181    }
182
183    /// Returns the original [`Mss`] used to compute this [`EffectiveMss`].
184    pub fn mss(&self) -> &Mss {
185        &self.mss
186    }
187
188    /// Replaces the held [`Mss`] with a new value.
189    pub fn update_mss(&mut self, new: Mss) {
190        self.mss = new
191    }
192
193    /// Gets the numeric value of the MSS.
194    pub const fn get(&self) -> u16 {
195        let Self { mss, fixed_tcp_options_size } = *self;
196        mss.get() - fixed_tcp_options_size
197    }
198}
199
200/// Factors that may limit the space available from the MSS.
201pub struct MssSizeLimiters {
202    /// True if the TCP Timestamp Option is enabled.
203    pub timestamp_enabled: bool,
204}
205
206impl From<EffectiveMss> for u32 {
207    fn from(mss: EffectiveMss) -> Self {
208        u32::from(mss.get())
209    }
210}
211
212impl From<EffectiveMss> for usize {
213    fn from(mss: EffectiveMss) -> Self {
214        usize::from(mss.get())
215    }
216}
217
218/// An implementation of [`Payload`] backed by up to `N` byte slices.
219#[derive(Copy, Clone, Debug, PartialEq)]
220pub struct FragmentedPayload<'a, const N: usize> {
221    storage: [&'a [u8]; N],
222    // NB: Not using `Range` because it is not `Copy`.
223    //
224    // Start is inclusive, end is exclusive; so this is equivalent to
225    // `start..end` ranges.
226    start: usize,
227    end: usize,
228}
229
230/// Creates a new `FragmentedPayload` possibly without using the entire
231/// storage capacity `N`.
232///
233/// # Panics
234///
235/// Panics if the iterator contains more than `N` items.
236impl<'a, const N: usize> FromIterator<&'a [u8]> for FragmentedPayload<'a, N> {
237    fn from_iter<T>(iter: T) -> Self
238    where
239        T: IntoIterator<Item = &'a [u8]>,
240    {
241        let Self { storage, start, end } = Self::new_empty();
242        let (storage, end) = iter.into_iter().fold((storage, end), |(mut storage, end), sl| {
243            storage[end] = sl;
244            (storage, end + 1)
245        });
246        Self { storage, start, end }
247    }
248}
249
250impl<'a, const N: usize> FragmentedPayload<'a, N> {
251    /// Creates a new `FragmentedPayload` with the slices in `values`.
252    pub fn new(values: [&'a [u8]; N]) -> Self {
253        Self { storage: values, start: 0, end: N }
254    }
255
256    /// Creates a new `FragmentedPayload` with a single contiguous slice.
257    pub fn new_contiguous(value: &'a [u8]) -> Self {
258        core::iter::once(value).collect()
259    }
260
261    /// Converts this [`FragmentedPayload`] into an owned `Vec`.
262    pub fn to_vec(self) -> Vec<u8> {
263        self.slices().concat()
264    }
265
266    fn slices(&self) -> &[&'a [u8]] {
267        let Self { storage, start, end } = self;
268        &storage[*start..*end]
269    }
270
271    /// Extracted function to implement [`Payload::partial_copy`] and
272    /// [`Payload::partial_copy_uninit`].
273    fn apply_copy<T, F: Fn(&[u8], &mut [T])>(
274        &self,
275        mut offset: usize,
276        mut dst: &mut [T],
277        apply: F,
278    ) {
279        let mut slices = self.slices().into_iter();
280        while let Some(sl) = slices.next() {
281            let l = sl.len();
282            if offset >= l {
283                offset -= l;
284                continue;
285            }
286            let sl = &sl[offset..];
287            let cp = sl.len().min(dst.len());
288            let (target, new_dst) = dst.split_at_mut(cp);
289            apply(&sl[..cp], target);
290
291            // We're done.
292            if new_dst.len() == 0 {
293                return;
294            }
295
296            dst = new_dst;
297            offset = 0;
298        }
299        assert_eq!(dst.len(), 0, "failed to fill dst");
300    }
301}
302
303impl<'a, const N: usize> PayloadLen for FragmentedPayload<'a, N> {
304    fn len(&self) -> usize {
305        self.slices().into_iter().map(|s| s.len()).sum()
306    }
307}
308
309impl<'a, const N: usize> Payload for FragmentedPayload<'a, N> {
310    fn slice(self, byte_range: Range<u32>) -> Self {
311        let Self { mut storage, start: mut self_start, end: mut self_end } = self;
312        let Range { start: byte_start, end: byte_end } = byte_range;
313        let byte_start =
314            usize::try_from(byte_start).expect("range start index out of range for usize");
315        let byte_end = usize::try_from(byte_end).expect("range end index out of range for usize");
316        assert!(byte_end >= byte_start);
317        let mut storage_iter =
318            (&mut storage[self_start..self_end]).into_iter().scan(0, |total_len, slice| {
319                let slice_len = slice.len();
320                let item = Some((*total_len, slice));
321                *total_len += slice_len;
322                item
323            });
324
325        // Keep track of whether the start was inside the range, we should panic
326        // even on an empty range out of start bounds.
327        let mut start_offset = None;
328        let mut final_len = 0;
329        while let Some((sl_offset, sl)) = storage_iter.next() {
330            let orig_len = sl.len();
331
332            // Advance until the start of the specified range, discarding unused
333            // slices.
334            if sl_offset + orig_len < byte_start {
335                *sl = &[];
336                self_start += 1;
337                continue;
338            }
339            // Discard any empty slices at the end.
340            if sl_offset >= byte_end {
341                *sl = &[];
342                self_end -= 1;
343                continue;
344            }
345
346            let sl_start = byte_start.saturating_sub(sl_offset);
347            let sl_end = sl.len().min(byte_end - sl_offset);
348            *sl = &sl[sl_start..sl_end];
349
350            match start_offset {
351                Some(_) => (),
352                None => {
353                    // Keep track of the start offset of the first slice.
354                    start_offset = Some(sl_offset + sl_start);
355                    // Avoid producing an empty slice if we haven't added
356                    // anything yet.
357                    if sl.len() == 0 {
358                        self_start += 1;
359                    }
360                }
361            }
362            final_len += sl.len();
363        }
364        // Verify that the entire range was consumed.
365        assert_eq!(
366            // If we didn't use start_offset the only valid value for
367            // `byte_start` is zero.
368            start_offset.unwrap_or(0),
369            byte_start,
370            "range start index out of range {byte_range:?}"
371        );
372        assert_eq!(byte_start + final_len, byte_end, "range end index out of range {byte_range:?}");
373
374        // Canonicalize an empty payload.
375        if self_start == self_end {
376            self_start = 0;
377            self_end = 0;
378        }
379        Self { storage, start: self_start, end: self_end }
380    }
381
382    fn new_empty() -> Self {
383        Self { storage: [&[]; N], start: 0, end: 0 }
384    }
385
386    fn partial_copy(&self, offset: usize, dst: &mut [u8]) {
387        self.apply_copy(offset, dst, |src, dst| {
388            dst.copy_from_slice(src);
389        });
390    }
391
392    fn partial_copy_uninit(&self, offset: usize, dst: &mut [MaybeUninit<u8>]) {
393        self.apply_copy(offset, dst, |src, dst| {
394            let _ = dst.write_copy_of_slice(src);
395        });
396    }
397}
398
399impl<'a, const N: usize> InnerPacketBuilder for FragmentedPayload<'a, N> {
400    fn bytes_len(&self) -> usize {
401        self.len()
402    }
403
404    fn serialize(&self, buffer: &mut [u8]) {
405        self.partial_copy(0, buffer);
406    }
407}
408
409#[cfg(any(test, feature = "testutils"))]
410mod testutil {
411    use super::*;
412
413    impl From<Mss> for u32 {
414        fn from(Mss(mss): Mss) -> Self {
415            u32::from(mss)
416        }
417    }
418
419    impl From<Mss> for usize {
420        fn from(Mss(mss): Mss) -> Self {
421            usize::from(mss)
422        }
423    }
424}
425
426#[cfg(test)]
427mod test {
428    use super::*;
429    use alloc::format;
430
431    use packet::Serializer as _;
432    use proptest::test_runner::Config;
433    use proptest::{prop_assert_eq, proptest};
434    use proptest_support::failed_seeds_no_std;
435    use test_case::test_case;
436
437    use crate::{SackBlock, SackBlocks, SeqNum, Timestamp, TimestampOption};
438
439    const EXAMPLE_DATA: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
440    #[test_case(FragmentedPayload::new([&EXAMPLE_DATA[..]]); "contiguous")]
441    #[test_case(FragmentedPayload::new([&EXAMPLE_DATA[0..2], &EXAMPLE_DATA[2..]]); "split once")]
442    #[test_case(FragmentedPayload::new([
443        &EXAMPLE_DATA[0..2],
444        &EXAMPLE_DATA[2..5],
445        &EXAMPLE_DATA[5..],
446    ]); "split twice")]
447    #[test_case(FragmentedPayload::<4>::from_iter([
448        &EXAMPLE_DATA[0..2],
449        &EXAMPLE_DATA[2..5],
450        &EXAMPLE_DATA[5..],
451    ]); "partial twice")]
452    fn fragmented_payload_serializer_data<const N: usize>(payload: FragmentedPayload<'_, N>) {
453        let serialized = payload
454            .into_serializer()
455            .serialize_vec_outer()
456            .expect("should serialize")
457            .unwrap_b()
458            .into_inner();
459        assert_eq!(&serialized[..], EXAMPLE_DATA);
460    }
461
462    #[test]
463    #[should_panic(expected = "range start index out of range")]
464    fn slice_start_out_of_bounds() {
465        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
466        let bad_len = len + 1;
467        // Like for standard slices, this shouldn't succeed if the start length
468        // is out of bounds, even if the total range is empty.
469        let _ = FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(bad_len..bad_len);
470    }
471
472    #[test]
473    #[should_panic(expected = "range end index out of range")]
474    fn slice_end_out_of_bounds() {
475        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
476        let bad_len = len + 1;
477        let _ = FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(0..bad_len);
478    }
479
480    #[test]
481    fn canon_empty_payload() {
482        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
483        assert_eq!(
484            FragmentedPayload::<1>::new_contiguous(&EXAMPLE_DATA).slice(len..len),
485            FragmentedPayload::new_empty()
486        );
487        assert_eq!(
488            FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(len..len),
489            FragmentedPayload::new_empty()
490        );
491        assert_eq!(
492            FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(2..2),
493            FragmentedPayload::new_empty()
494        );
495    }
496
497    const TEST_BYTES: &'static [u8] = b"Hello World!";
498    proptest! {
499        #![proptest_config(Config {
500            // Add all failed seeds here.
501            failure_persistence: failed_seeds_no_std!(),
502            ..Config::default()
503        })]
504
505        #[test]
506        fn fragmented_payload_to_vec(payload in fragmented_payload::with_payload()) {
507            prop_assert_eq!(payload.to_vec(), &TEST_BYTES[..]);
508        }
509
510        #[test]
511        fn fragmented_payload_len(payload in fragmented_payload::with_payload()) {
512            prop_assert_eq!(payload.len(), TEST_BYTES.len())
513        }
514
515        #[test]
516        fn fragmented_payload_slice((payload, (start, end)) in fragmented_payload::with_range()) {
517            let want = &TEST_BYTES[start..end];
518            let start = u32::try_from(start).unwrap();
519            let end = u32::try_from(end).unwrap();
520            prop_assert_eq!(payload.clone().slice(start..end).to_vec(), want);
521        }
522
523        #[test]
524        fn fragmented_payload_partial_copy((payload, (start, end)) in fragmented_payload::with_range()) {
525            let mut buffer = [0; TEST_BYTES.len()];
526            let buffer = &mut buffer[0..(end-start)];
527            payload.partial_copy(start, buffer);
528            prop_assert_eq!(buffer, &TEST_BYTES[start..end]);
529        }
530    }
531
532    mod fragmented_payload {
533        use super::*;
534
535        use proptest::strategy::{Just, Strategy};
536        use rand::Rng as _;
537
538        const TEST_STORAGE: usize = 5;
539        type TestFragmentedPayload = FragmentedPayload<'static, TEST_STORAGE>;
540        pub(super) fn with_payload() -> impl Strategy<Value = TestFragmentedPayload> {
541            (1..=TEST_STORAGE).prop_perturb(|slices, mut rng| {
542                (0..slices)
543                    .scan(0, |st, slice| {
544                        let len = if slice == slices - 1 {
545                            TEST_BYTES.len() - *st
546                        } else {
547                            rng.random_range(0..=(TEST_BYTES.len() - *st))
548                        };
549                        let start = *st;
550                        *st += len;
551                        Some(&TEST_BYTES[start..*st])
552                    })
553                    .collect()
554            })
555        }
556
557        pub(super) fn with_range() -> impl Strategy<Value = (TestFragmentedPayload, (usize, usize))>
558        {
559            (
560                with_payload(),
561                (0..TEST_BYTES.len()).prop_flat_map(|start| (Just(start), start..TEST_BYTES.len())),
562            )
563        }
564    }
565
566    #[test_case(true; "timestamp_enabled")]
567    #[test_case(false; "timestamp_disabled")]
568    fn effective_mss_accounts_for_fixed_size_tcp_options(timestamp_enabled: bool) {
569        const SIZE: u16 = 1000;
570        let mss =
571            EffectiveMss::from_mss(Mss::new(SIZE).unwrap(), MssSizeLimiters { timestamp_enabled });
572        if timestamp_enabled {
573            assert_eq!(
574                mss.get(),
575                SIZE - packet_formats::tcp::options::ALIGNED_TIMESTAMP_OPTION_LENGTH as u16
576            )
577        } else {
578            assert_eq!(mss.get(), SIZE);
579        }
580    }
581
582    #[test_case(SegmentOptions {sack_blocks: SackBlocks::EMPTY, timestamp: None}; "empty")]
583    #[test_case(SegmentOptions {
584        sack_blocks: SackBlocks::from_iter([
585            SackBlock::try_new(SeqNum::new(1), SeqNum::new(2)).unwrap(),
586            SackBlock::try_new(SeqNum::new(4), SeqNum::new(6)).unwrap(),
587        ]),
588        timestamp: None
589    }; "sack_blocks")]
590    #[test_case(SegmentOptions {
591        sack_blocks: SackBlocks::EMPTY,
592        timestamp: Some(TimestampOption {
593            ts_val: Timestamp::new(12345), ts_echo_reply: Timestamp::new(54321)
594        }),
595    }; "timestamp")]
596    #[test_case(SegmentOptions {
597        sack_blocks: SackBlocks::from_iter([
598            SackBlock::try_new(SeqNum::new(1), SeqNum::new(2)).unwrap(),
599            SackBlock::try_new(SeqNum::new(4), SeqNum::new(6)).unwrap(),
600        ]),
601        timestamp: Some(TimestampOption {
602            ts_val: Timestamp::new(12345), ts_echo_reply: Timestamp::new(54321)
603        }),
604    }; "sack_blocks_and_timestamp")]
605
606    fn effective_mss_accounts_for_variable_size_tcp_options(options: SegmentOptions) {
607        const SIZE: u16 = 1000;
608        let timestamp_enabled = options.timestamp.is_some();
609        let mss =
610            EffectiveMss::from_mss(Mss::new(SIZE).unwrap(), MssSizeLimiters { timestamp_enabled });
611        let options_len = u16::try_from(options.builder().bytes_len()).unwrap();
612        assert_eq!(mss.payload_size(&options).get(), SIZE - options_len);
613    }
614}
netstack3_base/tcp/base.rs

netstack3_base/tcp/
base.rs
