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}