Skip to main content

prolink_capture/
capture.rs

1// SPDX-License-Identifier: GPL-3.0-only
2
3//! Reading a capture file, frame by frame.
4//!
5//! Handles classic pcap and pcapng, dispatching on the first four bytes; this
6//! project's corpus contains both, because `tcpdump` writes pcapng as soon as
7//! it is given more than one interface and pcap otherwise.
8//!
9//! # What is deliberately not handled
10//!
11//! Ethernet only, IPv4 only, UDP and TCP only. That is the whole of what a Pro
12//! DJ Link capture contains, and every additional link layer is code that
13//! nothing in this project can test. A capture recorded on a link type this
14//! crate does not dissect is an [`Error::UnsupportedLinkType`] rather than an
15//! empty result, because an empty result is indistinguishable from a capture
16//! of a quiet network. Frames that *are* Ethernet but carry ARP, IPv6 or
17//! anything above IP that is not UDP or TCP are simply not packets in this
18//! crate's sense and are skipped without comment. Of pcapng's block types only
19//! the section header, the interface description, the enhanced packet block
20//! and the simple packet block are read; the obsolete packet block, which
21//! nothing since libpcap 0.x writes, is not.
22//!
23//! # Two things the format makes easy to get wrong
24//!
25//! **Ethernet padding.** A frame shorter than 60 bytes is padded, and the
26//! padding is not payload. The IP header's `total_len` is authoritative, so
27//! every length here comes from that and not from the captured frame length.
28//!
29//! **pcapng timestamp units.** A pcapng timestamp is a 64-bit counter in units
30//! the *interface* declares through its `if_tsresol` option, defaulting to
31//! microseconds. `pcap-file` 2.0 hands the raw counter back as a
32//! [`Duration`] of nanoseconds regardless, so every timestamp it produces for
33//! a `tcpdump` capture is a thousand times too small — 1970-01-21 instead of
34//! 2026. The option is re-read here and the scaling redone.
35//!
36//! # IP fragmentation is not optional
37//!
38//! A CDJ issues NFS `READ`s of 8192 bytes, the NFSv2 maximum, and each reply
39//! comes back as five or six IP fragments of which only the first carries a
40//! UDP header. A reader that ignores fragments therefore sees a fraction of
41//! every transfer and *under-reports it silently*. Fragments are reassembled
42//! here, per capture interface, and an incomplete datagram is never emitted.
43
44use std::collections::HashMap;
45use std::fs::File;
46use std::io::{BufReader, Chain, Cursor, Read};
47use std::net::{Ipv4Addr, SocketAddrV4};
48use std::path::Path;
49use std::time::Duration;
50
51use etherparse::{IpNumber, LaxNetSlice, LaxSlicedPacket, TcpSlice, UdpSlice};
52use pcap_file::PcapError;
53use pcap_file::pcap::PcapReader;
54use pcap_file::pcapng::blocks::interface_description::{
55    InterfaceDescriptionBlock, InterfaceDescriptionOption,
56};
57use pcap_file::pcapng::{Block, PcapNgReader};
58
59use crate::sparse::Sparse;
60use crate::{Error, Packet, Result, Transport};
61
62/// pcapng section header block type, which is byte-order independent.
63const PCAPNG_SECTION_HEADER: [u8; 4] = [0x0a, 0x0d, 0x0d, 0x0a];
64
65/// The classic pcap magic in both byte orders and both time resolutions.
66const PCAP_MAGICS: [[u8; 4]; 4] = [
67    [0xa1, 0xb2, 0xc3, 0xd4],
68    [0xd4, 0xc3, 0xb2, 0xa1],
69    [0xa1, 0xb2, 0x3c, 0x4d],
70    [0x4d, 0x3c, 0xb2, 0xa1],
71];
72
73/// Ethernet, the only link type dissected here.
74const LINKTYPE_ETHERNET: u32 = 1;
75
76/// pcapng's default timestamp resolution when an interface declares none.
77const DEFAULT_TS_DIVISOR: u64 = 1_000_000;
78
79/// How many part-assembled datagrams to hold before dropping the stalest.
80///
81/// A capture with heavy loss can leave fragments that will never complete;
82/// without a bound they accumulate for the length of the file. The bound is
83/// far above what a clean capture needs — the corpus never exceeds a handful.
84const MAX_PENDING_DATAGRAMS: usize = 1024;
85
86/// Which of the two file formats a capture is in.
87#[derive(Clone, Copy, PartialEq, Eq, Debug)]
88pub enum Format {
89    /// Classic libpcap: one global header, one link type, flat records.
90    Pcap,
91    /// pcapng: sections, per-interface link types and timestamp resolutions.
92    PcapNg,
93}
94
95/// The reader, once the four magic bytes have been put back in front of it.
96type Rewound<R> = BufReader<Chain<Cursor<[u8; 4]>, R>>;
97
98enum Source<R: Read> {
99    Pcap(Box<PcapReader<Rewound<R>>>),
100    PcapNg(Box<PcapNgReader<Rewound<R>>>),
101}
102
103/// What a pcapng interface description block tells us about its frames.
104#[derive(Clone, Copy, Debug)]
105struct Interface {
106    link_type: u32,
107    /// Timestamp counter ticks per second.
108    ts_divisor: u64,
109    /// Whether an unsupported link type has already been reported for it, so
110    /// a capture on the wrong interface costs one error and not one per frame.
111    reported: bool,
112}
113
114/// A capture file, read one packet at a time.
115///
116/// Iterating yields every UDP datagram and TCP segment in the file, in capture
117/// order. Frames are read and dissected lazily: a capture costs the underlying
118/// reader's 8 MiB window plus one frame plus whatever IP fragments are still
119/// being reassembled, and not the size of the file. That matters here — the
120/// corpus this crate exists for is 272 MB, one file of it 78 MB.
121///
122/// # Errors are the caller's to act on
123///
124/// The item type is [`Result`], and a hard error ends the iteration. That is
125/// deliberate: when walking a directory of captures, a file that ends
126/// part-way through a record should cost that file and not the run, but
127/// *whether* it does is a policy this crate has no business choosing. Match on
128/// [`Error::is_truncated`] and decide.
129///
130/// ```no_run
131/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
132/// use prolink_capture::Capture;
133///
134/// for entry in std::fs::read_dir("captures")? {
135///     let path = entry?.path();
136///     let capture = match Capture::open(&path) {
137///         Ok(capture) => capture,
138///         Err(error) => {
139///             eprintln!("{}: {error}", path.display());
140///             continue;
141///         }
142///     };
143///     // Every datagram a real player addressed to the status port.
144///     for packet in capture.udp_to(50002) {
145///         match packet {
146///             Ok(packet) => println!("{} bytes", packet.payload.len()),
147///             Err(error) => {
148///                 eprintln!("{}: {error}", path.display());
149///                 break;
150///             }
151///         }
152///     }
153/// }
154/// # Ok(())
155/// # }
156/// ```
157pub struct Capture<R: Read> {
158    source: Source<R>,
159    /// Indexed by pcapng interface id. Classic pcap has exactly one entry.
160    interfaces: Vec<Interface>,
161    defragmenter: Defragmenter,
162    index: u64,
163    finished: bool,
164}
165
166impl Capture<File> {
167    /// Open a capture file.
168    ///
169    /// The format is decided by the first four bytes, not by the extension:
170    /// every file in this project's corpus is named `run.pcap` and eleven of
171    /// the thirty-seven are pcapng.
172    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
173        Self::new(File::open(path)?)
174    }
175}
176
177impl<R: Read> Capture<R> {
178    /// Read a capture from anything byte-shaped.
179    ///
180    /// Fails when the leading bytes are neither magic, or — for classic pcap,
181    /// whose link type is declared once in the global header — when the frames
182    /// are not Ethernet.
183    pub fn new(mut reader: R) -> Result<Self> {
184        // Peek the four bytes the format is decided by, then put them back in
185        // front of the reader: a capture may come from a pipe, so seeking back
186        // is not available.
187        let mut magic = [0u8; 4];
188        let mut filled = 0usize;
189        while filled < magic.len() {
190            let Some(rest) = magic.get_mut(filled..) else {
191                break;
192            };
193            match reader.read(rest) {
194                Ok(0) => return Err(Error::NotACapture { magic }),
195                Ok(read) => filled = filled.saturating_add(read),
196                Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
197                Err(error) => return Err(error.into()),
198            }
199        }
200
201        let rewound = BufReader::new(Cursor::new(magic).chain(reader));
202        if magic == PCAPNG_SECTION_HEADER {
203            let reader = PcapNgReader::new(rewound).map_err(convert)?;
204            return Ok(Self::from_source(
205                Source::PcapNg(Box::new(reader)),
206                Vec::new(),
207            ));
208        }
209        if PCAP_MAGICS.contains(&magic) {
210            let reader = PcapReader::new(rewound).map_err(convert)?;
211            let link_type = u32::from(reader.header().datalink);
212            if link_type != LINKTYPE_ETHERNET {
213                return Err(Error::UnsupportedLinkType { link_type });
214            }
215            let interface = Interface {
216                link_type,
217                ts_divisor: DEFAULT_TS_DIVISOR,
218                reported: false,
219            };
220            return Ok(Self::from_source(
221                Source::Pcap(Box::new(reader)),
222                vec![interface],
223            ));
224        }
225        Err(Error::NotACapture { magic })
226    }
227
228    fn from_source(source: Source<R>, interfaces: Vec<Interface>) -> Self {
229        Self {
230            source,
231            interfaces,
232            defragmenter: Defragmenter::new(),
233            index: 0,
234            finished: false,
235        }
236    }
237
238    /// Which of the two formats this file turned out to be.
239    pub fn format(&self) -> Format {
240        match self.source {
241            Source::Pcap(_) => Format::Pcap,
242            Source::PcapNg(_) => Format::PcapNg,
243        }
244    }
245
246    /// Every UDP datagram **addressed to** `port`.
247    ///
248    /// The destination and nothing else, which is the whole reason this exists
249    /// rather than being left to the caller. The Pro DJ Link type byte at
250    /// offset `0x0a` is shared across ports and the layouts behind it are not:
251    /// `0x06` is a keep-alive on 50000 and a media response on 50002. A tool
252    /// that binds one socket and sends its keep-alives *from* 50002
253    /// contributes packets that an "either endpoint" filter accepts and the
254    /// 50002 decoder reads as confident nonsense — a failure with no error and
255    /// no exception, only wrong fields.
256    ///
257    /// Real hardware makes this easy to miss: of the 35 103 datagrams in this
258    /// project's corpus addressed to 50002, only 24 were *sent from* 50002,
259    /// because a CDJ sends each status packet from a **different, incrementing
260    /// source port** — 4763, 4764, 4765 and so on through a session. Filtering
261    /// on the source therefore finds almost nothing, and filtering on either
262    /// endpoint looks right until the day a second tool is on the network.
263    ///
264    /// Zero-length datagrams are not filtered out, because a zero-length
265    /// datagram is a thing that was sent and an empty result is not an error.
266    pub fn udp_to(self, port: u16) -> UdpTo<R> {
267        UdpTo {
268            capture: self,
269            port,
270        }
271    }
272}
273
274impl<R: Read> std::fmt::Debug for Capture<R> {
275    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
276        f.debug_struct("Capture")
277            .field("format", &self.format())
278            .field("interfaces", &self.interfaces.len())
279            .field("frames_read", &self.index)
280            .finish_non_exhaustive()
281    }
282}
283
284impl<R: Read> Iterator for Capture<R> {
285    type Item = Result<Packet>;
286
287    fn next(&mut self) -> Option<Self::Item> {
288        while !self.finished {
289            let outcome = match &mut self.source {
290                Source::Pcap(reader) => {
291                    let Some(frame) = reader.next_packet() else {
292                        self.finished = true;
293                        return None;
294                    };
295                    match frame {
296                        Ok(frame) => {
297                            self.index = self.index.saturating_add(1);
298                            dissect(
299                                &mut self.defragmenter,
300                                &frame.data,
301                                0,
302                                self.index,
303                                frame.timestamp,
304                            )
305                            .map(Ok)
306                        }
307                        Err(error) => Some(Err(convert(error))),
308                    }
309                }
310                Source::PcapNg(reader) => {
311                    let Some(block) = reader.next_block() else {
312                        self.finished = true;
313                        return None;
314                    };
315                    match block {
316                        Ok(block) => step_pcapng(
317                            block,
318                            &mut self.interfaces,
319                            &mut self.defragmenter,
320                            &mut self.index,
321                        ),
322                        Err(error) => Some(Err(convert(error))),
323                    }
324                }
325            };
326            match outcome {
327                Some(Ok(packet)) => return Some(Ok(packet)),
328                Some(Err(error)) => {
329                    // An unsupported link type concerns one interface of a
330                    // multi-interface capture; everything else is fatal.
331                    if !matches!(error, Error::UnsupportedLinkType { .. }) {
332                        self.finished = true;
333                    }
334                    return Some(Err(error));
335                }
336                None => {}
337            }
338        }
339        None
340    }
341}
342
343/// Consume one pcapng block, which may describe an interface, carry a frame,
344/// or be neither.
345fn step_pcapng(
346    block: Block<'_>,
347    interfaces: &mut Vec<Interface>,
348    defragmenter: &mut Defragmenter,
349    index: &mut u64,
350) -> Option<Result<Packet>> {
351    match block {
352        Block::SectionHeader(_) => {
353            // Interface ids restart with every section.
354            interfaces.clear();
355            None
356        }
357        Block::InterfaceDescription(idb) => {
358            interfaces.push(Interface {
359                link_type: u32::from(idb.linktype),
360                ts_divisor: timestamp_divisor(&idb),
361                reported: false,
362            });
363            None
364        }
365        Block::EnhancedPacket(epb) => {
366            *index = index.saturating_add(1);
367            let interface_id = epb.interface_id;
368            let Some(interface) = usize::try_from(interface_id)
369                .ok()
370                .and_then(|id| interfaces.get_mut(id))
371            else {
372                return Some(Err(Error::Malformed {
373                    reason: format!("packet block names interface {interface_id}, undeclared"),
374                }));
375            };
376            if interface.link_type != LINKTYPE_ETHERNET {
377                if interface.reported {
378                    return None;
379                }
380                interface.reported = true;
381                return Some(Err(Error::UnsupportedLinkType {
382                    link_type: interface.link_type,
383                }));
384            }
385            let timestamp = rescale(epb.timestamp, interface.ts_divisor);
386            dissect(defragmenter, &epb.data, interface_id, *index, timestamp).map(Ok)
387        }
388        Block::SimplePacket(spb) => {
389            // A simple packet block records no interface and no time; it
390            // belongs to interface 0 by definition and carries no timestamp,
391            // which is reported as zero rather than guessed at.
392            *index = index.saturating_add(1);
393            let link_type = interfaces
394                .first()
395                .map_or(LINKTYPE_ETHERNET, |i| i.link_type);
396            if link_type != LINKTYPE_ETHERNET {
397                return None;
398            }
399            dissect(defragmenter, &spb.data, 0, *index, Duration::ZERO).map(Ok)
400        }
401        _ => None,
402    }
403}
404
405/// Ticks per second for a pcapng interface, from its `if_tsresol` option.
406///
407/// The high bit of the option selects a power of two rather than of ten. An
408/// absent option means microseconds, which is what `tcpdump` writes and
409/// therefore what every capture in this project's corpus uses.
410fn timestamp_divisor(idb: &InterfaceDescriptionBlock<'_>) -> u64 {
411    for option in &idb.options {
412        if let InterfaceDescriptionOption::IfTsResol(resolution) = *option {
413            return if resolution & 0x80 == 0 {
414                10u64
415                    .checked_pow(u32::from(resolution))
416                    .unwrap_or(DEFAULT_TS_DIVISOR)
417            } else {
418                1u64.checked_shl(u32::from(resolution & 0x7f))
419                    .unwrap_or(DEFAULT_TS_DIVISOR)
420            };
421        }
422    }
423    DEFAULT_TS_DIVISOR
424}
425
426/// Undo `pcap-file`'s assumption that a pcapng timestamp counts nanoseconds.
427///
428/// It hands the raw 64-bit counter back as `Duration::from_nanos(counter)`, so
429/// the counter is recovered from the nanoseconds and rescaled by the interface's
430/// real resolution.
431fn rescale(raw: Duration, divisor: u64) -> Duration {
432    let ticks = raw.as_nanos();
433    let divisor = u128::from(divisor);
434    let Some(seconds) = ticks.checked_div(divisor) else {
435        return Duration::ZERO;
436    };
437    let nanos = ticks
438        .checked_rem(divisor)
439        .and_then(|fraction| fraction.checked_mul(1_000_000_000))
440        .and_then(|scaled| scaled.checked_div(divisor))
441        .unwrap_or(0);
442    Duration::new(
443        u64::try_from(seconds).unwrap_or(u64::MAX),
444        u32::try_from(nanos).unwrap_or(0),
445    )
446}
447
448/// Ethernet → IPv4 → UDP or TCP, or nothing.
449fn dissect(
450    defragmenter: &mut Defragmenter,
451    frame: &[u8],
452    interface: u32,
453    index: u64,
454    timestamp: Duration,
455) -> Option<Packet> {
456    let sliced = LaxSlicedPacket::from_ethernet(frame).ok()?;
457    let Some(LaxNetSlice::Ipv4(ipv4)) = sliced.net else {
458        return None;
459    };
460    let header = ipv4.header();
461    let source_ip = header.source_addr();
462    let destination_ip = header.destination_addr();
463    let ip_payload = ipv4.payload();
464
465    let assembled;
466    let (protocol, payload) = if ip_payload.fragmented {
467        let key = FragmentKey {
468            interface,
469            source: source_ip,
470            destination: destination_ip,
471            identification: header.identification(),
472            protocol: ip_payload.ip_number,
473        };
474        assembled = defragmenter.add(
475            key,
476            index,
477            u64::from(header.fragments_offset().byte_offset()),
478            ip_payload.payload,
479            header.more_fragments(),
480        )?;
481        (ip_payload.ip_number, assembled.as_slice())
482    } else {
483        (ip_payload.ip_number, ip_payload.payload)
484    };
485
486    let segment = parse_transport(protocol, payload)?;
487    Some(Packet {
488        index,
489        timestamp,
490        interface,
491        source: SocketAddrV4::new(source_ip, segment.source_port),
492        destination: SocketAddrV4::new(destination_ip, segment.destination_port),
493        transport: segment.transport,
494        payload: segment.payload.to_vec(),
495    })
496}
497
498struct Segment<'a> {
499    source_port: u16,
500    destination_port: u16,
501    transport: Transport,
502    payload: &'a [u8],
503}
504
505fn parse_transport(protocol: IpNumber, payload: &[u8]) -> Option<Segment<'_>> {
506    if protocol == IpNumber::UDP {
507        let udp = UdpSlice::from_slice_lax(payload).ok()?;
508        return Some(Segment {
509            source_port: udp.source_port(),
510            destination_port: udp.destination_port(),
511            transport: Transport::Udp,
512            payload: udp.payload(),
513        });
514    }
515    if protocol == IpNumber::TCP {
516        let tcp = TcpSlice::from_slice(payload).ok()?;
517        return Some(Segment {
518            source_port: tcp.source_port(),
519            destination_port: tcp.destination_port(),
520            transport: Transport::Tcp {
521                sequence: tcp.sequence_number(),
522                syn: tcp.syn(),
523                fin: tcp.fin(),
524                reset: tcp.rst(),
525            },
526            payload: tcp.payload(),
527        });
528    }
529    None
530}
531
532/// The RFC 791 reassembly tuple, plus the capture interface.
533///
534/// The interface belongs in the key because a capture of a bridge records the
535/// same datagram on both of its interfaces, with the same addresses and the
536/// same identification. Without it the two copies' fragments would be folded
537/// into one datagram, so fragmented traffic would be silently de-duplicated
538/// while unfragmented traffic stayed doubled — the two counts would then
539/// disagree for a reason nothing in the output would explain.
540#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
541struct FragmentKey {
542    interface: u32,
543    source: Ipv4Addr,
544    destination: Ipv4Addr,
545    identification: u16,
546    protocol: IpNumber,
547}
548
549struct Pending {
550    bytes: Sparse,
551    /// Total length, known only once the fragment without `more fragments`
552    /// arrives — which is not necessarily the last one to be captured.
553    total: Option<u64>,
554    last_seen: u64,
555}
556
557/// Reassembles fragmented IPv4 datagrams.
558///
559/// No timeout is modelled in seconds, because a capture is finite and a
560/// datagram left incomplete at the end of one is not interesting. The only
561/// eviction is a bound on how many part-assembled datagrams may be held at
562/// once, so a lossy capture cannot grow this without limit.
563struct Defragmenter {
564    pending: HashMap<FragmentKey, Pending>,
565}
566
567impl Defragmenter {
568    fn new() -> Self {
569        Self {
570            pending: HashMap::new(),
571        }
572    }
573
574    /// Add one fragment; return the whole datagram once it is complete.
575    fn add(
576        &mut self,
577        key: FragmentKey,
578        index: u64,
579        offset: u64,
580        payload: &[u8],
581        more_fragments: bool,
582    ) -> Option<Vec<u8>> {
583        if self.pending.len() > MAX_PENDING_DATAGRAMS {
584            let horizon = index.saturating_sub(
585                u64::try_from(MAX_PENDING_DATAGRAMS).unwrap_or(u64::from(u32::MAX)),
586            );
587            self.pending
588                .retain(|_, pending| pending.last_seen >= horizon);
589        }
590
591        let entry = self.pending.entry(key).or_insert_with(|| Pending {
592            bytes: Sparse::new(),
593            total: None,
594            last_seen: index,
595        });
596        entry.last_seen = index;
597        entry.bytes.insert(offset, payload);
598        if !more_fragments {
599            entry.total = Some(offset.saturating_add(payload.len().try_into().unwrap_or(u64::MAX)));
600        }
601
602        let total = entry.total?;
603        let complete = entry
604            .bytes
605            .contiguous()
606            .is_some_and(|bytes| u64::try_from(bytes.len()).unwrap_or(u64::MAX) >= total);
607        if !complete {
608            return None;
609        }
610        let mut assembled = self.pending.remove(&key)?.bytes.contiguous()?.to_vec();
611        assembled.truncate(usize::try_from(total).unwrap_or(usize::MAX));
612        Some(assembled)
613    }
614}
615
616/// Every UDP datagram addressed to one port. Built by [`Capture::udp_to`].
617#[derive(Debug)]
618pub struct UdpTo<R: Read> {
619    capture: Capture<R>,
620    port: u16,
621}
622
623impl<R: Read> Iterator for UdpTo<R> {
624    type Item = Result<Packet>;
625
626    fn next(&mut self) -> Option<Self::Item> {
627        loop {
628            match self.capture.next()? {
629                Ok(packet) => {
630                    if packet.transport.is_udp() && packet.destination.port() == self.port {
631                        return Some(Ok(packet));
632                    }
633                }
634                Err(error) => return Some(Err(error)),
635            }
636        }
637    }
638}
639
640/// Translate the reader's errors into this crate's, keeping the one
641/// distinction that matters.
642///
643/// A file that ends part-way through a record reaches us as an
644/// `UnexpectedEof`, not as `IncompleteBuffer`: the underlying reader asks for
645/// more bytes, gets none, and reports the read rather than the parse. Both
646/// mean the same thing here and both are [`Error::Truncated`], so a corpus
647/// walker can tell a `tcpdump` that was killed from a file that is not a
648/// capture at all.
649fn convert(error: PcapError) -> Error {
650    match error {
651        PcapError::IncompleteBuffer => Error::Truncated,
652        PcapError::IoError(inner) if inner.kind() == std::io::ErrorKind::UnexpectedEof => {
653            Error::Truncated
654        }
655        PcapError::IoError(inner) => Error::Io(inner),
656        other => Error::Malformed {
657            reason: other.to_string(),
658        },
659    }
660}