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    /// Per RFC 7323 Section 3.2, the TCP Timestamp option has a length of
148    /// 10 bytes:
149    ///   +-------+-------+---------------------+---------------------+
150    ///   |Kind=8 |  10   |   TS Value (TSval)  |TS Echo Reply (TSecr)|
151    ///   +-------+-------+---------------------+---------------------+
152    ///      1       1              4                     4
153    ///
154    /// However, once aligned, it will occupy 12 bytes.
155    const ALIGNED_TIMESTAMP_OPTION_LENGTH: u16 = 12;
156
157    /// Constructs an [`EffectiveMss`] from an [`Mss`]
158    pub const fn from_mss(mss: Mss, timestamp_option_enabled: bool) -> Self {
159        // NB: When adding additional fixed size options in the future, authors
160        // should take care to account for the alignment only once.
161        let fixed_tcp_options_size =
162            if timestamp_option_enabled { Self::ALIGNED_TIMESTAMP_OPTION_LENGTH } else { 0 };
163        EffectiveMss { mss, fixed_tcp_options_size }
164    }
165
166    /// Computes the amount of payload data to include in a segment.
167    ///
168    /// Accounts for the size of any variable-sized options present in the
169    /// segment.
170    pub fn payload_size(&self, options: &SegmentOptions) -> NonZeroU16 {
171        // NB: Ignore the fixed TCP options size, it will be accounted for by
172        // `options`.
173        let Self { mss, fixed_tcp_options_size: _ } = self;
174        // NB: Safe to unwrap here because TCP options have a fixed maximum
175        // size < u16::MAX.
176        let tcp_options_len =
177            u16::try_from(packet_formats::tcp::aligned_options_length(options.iter())).unwrap();
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
200impl From<EffectiveMss> for u32 {
201    fn from(mss: EffectiveMss) -> Self {
202        u32::from(mss.get())
203    }
204}
205
206impl From<EffectiveMss> for usize {
207    fn from(mss: EffectiveMss) -> Self {
208        usize::from(mss.get())
209    }
210}
211
212/// An implementation of [`Payload`] backed by up to `N` byte slices.
213#[derive(Copy, Clone, Debug, PartialEq)]
214pub struct FragmentedPayload<'a, const N: usize> {
215    storage: [&'a [u8]; N],
216    // NB: Not using `Range` because it is not `Copy`.
217    //
218    // Start is inclusive, end is exclusive; so this is equivalent to
219    // `start..end` ranges.
220    start: usize,
221    end: usize,
222}
223
224/// Creates a new `FragmentedPayload` possibly without using the entire
225/// storage capacity `N`.
226///
227/// # Panics
228///
229/// Panics if the iterator contains more than `N` items.
230impl<'a, const N: usize> FromIterator<&'a [u8]> for FragmentedPayload<'a, N> {
231    fn from_iter<T>(iter: T) -> Self
232    where
233        T: IntoIterator<Item = &'a [u8]>,
234    {
235        let Self { storage, start, end } = Self::new_empty();
236        let (storage, end) = iter.into_iter().fold((storage, end), |(mut storage, end), sl| {
237            storage[end] = sl;
238            (storage, end + 1)
239        });
240        Self { storage, start, end }
241    }
242}
243
244impl<'a, const N: usize> FragmentedPayload<'a, N> {
245    /// Creates a new `FragmentedPayload` with the slices in `values`.
246    pub fn new(values: [&'a [u8]; N]) -> Self {
247        Self { storage: values, start: 0, end: N }
248    }
249
250    /// Creates a new `FragmentedPayload` with a single contiguous slice.
251    pub fn new_contiguous(value: &'a [u8]) -> Self {
252        core::iter::once(value).collect()
253    }
254
255    /// Converts this [`FragmentedPayload`] into an owned `Vec`.
256    pub fn to_vec(self) -> Vec<u8> {
257        self.slices().concat()
258    }
259
260    fn slices(&self) -> &[&'a [u8]] {
261        let Self { storage, start, end } = self;
262        &storage[*start..*end]
263    }
264
265    /// Extracted function to implement [`Payload::partial_copy`] and
266    /// [`Payload::partial_copy_uninit`].
267    fn apply_copy<T, F: Fn(&[u8], &mut [T])>(
268        &self,
269        mut offset: usize,
270        mut dst: &mut [T],
271        apply: F,
272    ) {
273        let mut slices = self.slices().into_iter();
274        while let Some(sl) = slices.next() {
275            let l = sl.len();
276            if offset >= l {
277                offset -= l;
278                continue;
279            }
280            let sl = &sl[offset..];
281            let cp = sl.len().min(dst.len());
282            let (target, new_dst) = dst.split_at_mut(cp);
283            apply(&sl[..cp], target);
284
285            // We're done.
286            if new_dst.len() == 0 {
287                return;
288            }
289
290            dst = new_dst;
291            offset = 0;
292        }
293        assert_eq!(dst.len(), 0, "failed to fill dst");
294    }
295}
296
297impl<'a, const N: usize> PayloadLen for FragmentedPayload<'a, N> {
298    fn len(&self) -> usize {
299        self.slices().into_iter().map(|s| s.len()).sum()
300    }
301}
302
303impl<'a, const N: usize> Payload for FragmentedPayload<'a, N> {
304    fn slice(self, byte_range: Range<u32>) -> Self {
305        let Self { mut storage, start: mut self_start, end: mut self_end } = self;
306        let Range { start: byte_start, end: byte_end } = byte_range;
307        let byte_start =
308            usize::try_from(byte_start).expect("range start index out of range for usize");
309        let byte_end = usize::try_from(byte_end).expect("range end index out of range for usize");
310        assert!(byte_end >= byte_start);
311        let mut storage_iter =
312            (&mut storage[self_start..self_end]).into_iter().scan(0, |total_len, slice| {
313                let slice_len = slice.len();
314                let item = Some((*total_len, slice));
315                *total_len += slice_len;
316                item
317            });
318
319        // Keep track of whether the start was inside the range, we should panic
320        // even on an empty range out of start bounds.
321        let mut start_offset = None;
322        let mut final_len = 0;
323        while let Some((sl_offset, sl)) = storage_iter.next() {
324            let orig_len = sl.len();
325
326            // Advance until the start of the specified range, discarding unused
327            // slices.
328            if sl_offset + orig_len < byte_start {
329                *sl = &[];
330                self_start += 1;
331                continue;
332            }
333            // Discard any empty slices at the end.
334            if sl_offset >= byte_end {
335                *sl = &[];
336                self_end -= 1;
337                continue;
338            }
339
340            let sl_start = byte_start.saturating_sub(sl_offset);
341            let sl_end = sl.len().min(byte_end - sl_offset);
342            *sl = &sl[sl_start..sl_end];
343
344            match start_offset {
345                Some(_) => (),
346                None => {
347                    // Keep track of the start offset of the first slice.
348                    start_offset = Some(sl_offset + sl_start);
349                    // Avoid producing an empty slice if we haven't added
350                    // anything yet.
351                    if sl.len() == 0 {
352                        self_start += 1;
353                    }
354                }
355            }
356            final_len += sl.len();
357        }
358        // Verify that the entire range was consumed.
359        assert_eq!(
360            // If we didn't use start_offset the only valid value for
361            // `byte_start` is zero.
362            start_offset.unwrap_or(0),
363            byte_start,
364            "range start index out of range {byte_range:?}"
365        );
366        assert_eq!(byte_start + final_len, byte_end, "range end index out of range {byte_range:?}");
367
368        // Canonicalize an empty payload.
369        if self_start == self_end {
370            self_start = 0;
371            self_end = 0;
372        }
373        Self { storage, start: self_start, end: self_end }
374    }
375
376    fn new_empty() -> Self {
377        Self { storage: [&[]; N], start: 0, end: 0 }
378    }
379
380    fn partial_copy(&self, offset: usize, dst: &mut [u8]) {
381        self.apply_copy(offset, dst, |src, dst| {
382            dst.copy_from_slice(src);
383        });
384    }
385
386    fn partial_copy_uninit(&self, offset: usize, dst: &mut [MaybeUninit<u8>]) {
387        self.apply_copy(offset, dst, |src, dst| {
388            // TODO(https://github.com/rust-lang/rust/issues/79995): Replace unsafe
389            // with copy_from_slice when stabiliized.
390            // SAFETY: &[T] and &[MaybeUninit<T>] have the same layout.
391            let uninit_src: &[MaybeUninit<u8>] = unsafe { core::mem::transmute(src) };
392            dst.copy_from_slice(&uninit_src);
393        });
394    }
395}
396
397impl<'a, const N: usize> InnerPacketBuilder for FragmentedPayload<'a, N> {
398    fn bytes_len(&self) -> usize {
399        self.len()
400    }
401
402    fn serialize(&self, buffer: &mut [u8]) {
403        self.partial_copy(0, buffer);
404    }
405}
406
407#[cfg(any(test, feature = "testutils"))]
408mod testutil {
409    use super::*;
410
411    impl From<Mss> for u32 {
412        fn from(Mss(mss): Mss) -> Self {
413            u32::from(mss)
414        }
415    }
416
417    impl From<Mss> for usize {
418        fn from(Mss(mss): Mss) -> Self {
419            usize::from(mss)
420        }
421    }
422}
423
424#[cfg(test)]
425mod test {
426    use super::*;
427    use alloc::format;
428
429    use packet::Serializer as _;
430    use proptest::test_runner::Config;
431    use proptest::{prop_assert_eq, proptest};
432    use proptest_support::failed_seeds_no_std;
433    use test_case::test_case;
434
435    use crate::{SackBlock, SackBlocks, SeqNum, Timestamp, TimestampOption};
436
437    const EXAMPLE_DATA: [u8; 10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
438    #[test_case(FragmentedPayload::new([&EXAMPLE_DATA[..]]); "contiguous")]
439    #[test_case(FragmentedPayload::new([&EXAMPLE_DATA[0..2], &EXAMPLE_DATA[2..]]); "split once")]
440    #[test_case(FragmentedPayload::new([
441        &EXAMPLE_DATA[0..2],
442        &EXAMPLE_DATA[2..5],
443        &EXAMPLE_DATA[5..],
444    ]); "split twice")]
445    #[test_case(FragmentedPayload::<4>::from_iter([
446        &EXAMPLE_DATA[0..2],
447        &EXAMPLE_DATA[2..5],
448        &EXAMPLE_DATA[5..],
449    ]); "partial twice")]
450    fn fragmented_payload_serializer_data<const N: usize>(payload: FragmentedPayload<'_, N>) {
451        let serialized = payload
452            .into_serializer()
453            .serialize_vec_outer()
454            .expect("should serialize")
455            .unwrap_b()
456            .into_inner();
457        assert_eq!(&serialized[..], EXAMPLE_DATA);
458    }
459
460    #[test]
461    #[should_panic(expected = "range start index out of range")]
462    fn slice_start_out_of_bounds() {
463        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
464        let bad_len = len + 1;
465        // Like for standard slices, this shouldn't succeed if the start length
466        // is out of bounds, even if the total range is empty.
467        let _ = FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(bad_len..bad_len);
468    }
469
470    #[test]
471    #[should_panic(expected = "range end index out of range")]
472    fn slice_end_out_of_bounds() {
473        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
474        let bad_len = len + 1;
475        let _ = FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(0..bad_len);
476    }
477
478    #[test]
479    fn canon_empty_payload() {
480        let len = u32::try_from(EXAMPLE_DATA.len()).unwrap();
481        assert_eq!(
482            FragmentedPayload::<1>::new_contiguous(&EXAMPLE_DATA).slice(len..len),
483            FragmentedPayload::new_empty()
484        );
485        assert_eq!(
486            FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(len..len),
487            FragmentedPayload::new_empty()
488        );
489        assert_eq!(
490            FragmentedPayload::<2>::new_contiguous(&EXAMPLE_DATA).slice(2..2),
491            FragmentedPayload::new_empty()
492        );
493    }
494
495    const TEST_BYTES: &'static [u8] = b"Hello World!";
496    proptest! {
497        #![proptest_config(Config {
498            // Add all failed seeds here.
499            failure_persistence: failed_seeds_no_std!(),
500            ..Config::default()
501        })]
502
503        #[test]
504        fn fragmented_payload_to_vec(payload in fragmented_payload::with_payload()) {
505            prop_assert_eq!(payload.to_vec(), &TEST_BYTES[..]);
506        }
507
508        #[test]
509        fn fragmented_payload_len(payload in fragmented_payload::with_payload()) {
510            prop_assert_eq!(payload.len(), TEST_BYTES.len())
511        }
512
513        #[test]
514        fn fragmented_payload_slice((payload, (start, end)) in fragmented_payload::with_range()) {
515            let want = &TEST_BYTES[start..end];
516            let start = u32::try_from(start).unwrap();
517            let end = u32::try_from(end).unwrap();
518            prop_assert_eq!(payload.clone().slice(start..end).to_vec(), want);
519        }
520
521        #[test]
522        fn fragmented_payload_partial_copy((payload, (start, end)) in fragmented_payload::with_range()) {
523            let mut buffer = [0; TEST_BYTES.len()];
524            let buffer = &mut buffer[0..(end-start)];
525            payload.partial_copy(start, buffer);
526            prop_assert_eq!(buffer, &TEST_BYTES[start..end]);
527        }
528    }
529
530    mod fragmented_payload {
531        use super::*;
532
533        use proptest::strategy::{Just, Strategy};
534        use rand::Rng as _;
535
536        const TEST_STORAGE: usize = 5;
537        type TestFragmentedPayload = FragmentedPayload<'static, TEST_STORAGE>;
538        pub(super) fn with_payload() -> impl Strategy<Value = TestFragmentedPayload> {
539            (1..=TEST_STORAGE).prop_perturb(|slices, mut rng| {
540                (0..slices)
541                    .scan(0, |st, slice| {
542                        let len = if slice == slices - 1 {
543                            TEST_BYTES.len() - *st
544                        } else {
545                            rng.random_range(0..=(TEST_BYTES.len() - *st))
546                        };
547                        let start = *st;
548                        *st += len;
549                        Some(&TEST_BYTES[start..*st])
550                    })
551                    .collect()
552            })
553        }
554
555        pub(super) fn with_range() -> impl Strategy<Value = (TestFragmentedPayload, (usize, usize))>
556        {
557            (
558                with_payload(),
559                (0..TEST_BYTES.len()).prop_flat_map(|start| (Just(start), start..TEST_BYTES.len())),
560            )
561        }
562    }
563
564    #[test_case(true; "timestamp_enabled")]
565    #[test_case(false; "timestamp_disabled")]
566    fn effective_mss_accounts_for_fixed_size_tcp_options(timestamp: bool) {
567        const SIZE: u16 = 1000;
568        let mss = EffectiveMss::from_mss(Mss::new(SIZE).unwrap(), timestamp);
569        if timestamp {
570            assert_eq!(mss.get(), SIZE - EffectiveMss::ALIGNED_TIMESTAMP_OPTION_LENGTH)
571        } else {
572            assert_eq!(mss.get(), SIZE);
573        }
574    }
575
576    #[test_case(SegmentOptions {sack_blocks: SackBlocks::EMPTY, timestamp: None}; "empty")]
577    #[test_case(SegmentOptions {
578        sack_blocks: SackBlocks::from_iter([
579            SackBlock::try_new(SeqNum::new(1), SeqNum::new(2)).unwrap(),
580            SackBlock::try_new(SeqNum::new(4), SeqNum::new(6)).unwrap(),
581        ]),
582        timestamp: None
583    }; "sack_blocks")]
584    #[test_case(SegmentOptions {
585        sack_blocks: SackBlocks::EMPTY,
586        timestamp: Some(TimestampOption {
587            ts_val: Timestamp::new(12345), ts_echo_reply: Timestamp::new(54321)
588        }),
589    }; "timestamp")]
590    #[test_case(SegmentOptions {
591        sack_blocks: SackBlocks::from_iter([
592            SackBlock::try_new(SeqNum::new(1), SeqNum::new(2)).unwrap(),
593            SackBlock::try_new(SeqNum::new(4), SeqNum::new(6)).unwrap(),
594        ]),
595        timestamp: Some(TimestampOption {
596            ts_val: Timestamp::new(12345), ts_echo_reply: Timestamp::new(54321)
597        }),
598    }; "sack_blocks_and_timestamp")]
599
600    fn effective_mss_accounts_for_variable_size_tcp_options(options: SegmentOptions) {
601        const SIZE: u16 = 1000;
602        let timestamp = options.timestamp.is_some();
603        let mss = EffectiveMss::from_mss(Mss::new(SIZE).unwrap(), timestamp);
604        let options_len =
605            u16::try_from(packet_formats::tcp::aligned_options_length(options.iter())).unwrap();
606        assert_eq!(mss.payload_size(&options).get(), SIZE - options_len);
607    }
608}
netstack3_base/tcp/base.rs

netstack3_base/tcp/
base.rs
