NAME

Net::Pcap::Reassemble - IP fragment reassembly for Net::Pcap

SYNOPSIS

 use Net::Pcap::Reassemble;

 my $pcap_t = Net::Pcap::open_offline($opt_p, \$err);
 if (!defined($pcap_t)) {
   print STDERR "Net::Pcap::open_offline returned error: $err\n";
   exit 1;
 }

 Net::Pcap::Reassemble::loop($pcap_t, -1, \&callback, "user data");

DESCRIPTION

This module performs reassembly of fragmented datagrams in libpcap packet capture data returned by the Net::Pcap loop() function. This module supports reassembly of IPv4 and IPv6 fragments.

FUNCTIONS

loop($pcap, $count, \&callback, $user_data)

The loop() function in Net::Pcap::Reassemble is intended as a seamless wrapper around the same function from Net::Pcap and as such it takes the same arguments. Net::Pcap::Reassemble, however, will only invoke the &callback function when it has a complete packet.

The module will print debug information to stdout (mainly packet header values) if the $debug variable in the package namespace evaluates to true:

 $Net::Pcap::Reassemble::debug = 1;

Layer 2 header data (typically an ethernet header) will be omitted from the packet supplied to the callback function if the $stripl2 variable in the package namespace evaluates to true:

 $Net::Pcap::Reassemble::stripl2 = 1;

flush()

The flush() function destroys the data structures storing any incomplete datagrams. This function can be called after loop() has returned to release memory used by the fragments of incomplete datagrams (assuming your program continues executing after the loop() finishes).

OBJECTS

Data is represented internally using Net::Pcap::Reassemble::Packet and Net::Pcap::Reassemble::Fragment class objects.

Net::Pcap::Reassemble::Packet

Each `Packet' object represents a complete captured packet and contains:

1. An ID: 'srcip dstip IPid protocol' for IPv4; 'srcip dstip IPid' for IPv6
2. A list of Net::Pcap::Reassemble::Fragment object references
3. The final octet, learned from the packet with MF==0
4. A flag to indicate if the fragment list is sorted

It has class functions to add a fragment to the Packet (addfragment()), return a string with information on the fragments received so far (listfragments()), and to test whether a datagram is complete and return its data if it is (iscomplete()).

Net::Pcap::Reassemble::Fragment

Each `Fragment' object represents an IP datagram fragment and contains:

1. Start octet
2. End octet
3. (M)ore (F)ragments flag (`MF' in IPv4; `M' in IPv6)
4. Payload data

It has class functions to return the data above (start(), end(), mf() and data()), and a summary string for debugging (vitals()).

SEE ALSO

Net::Pcap

BUGS

• Stale fragments are not aged out of the pending fragment list. We could look at the pcap header for the capture time of each packet and age out based on that.
• This module offers no resistance against fragment overlap attacks, and other such malarky.
• loop() should accept an optional anonymous hash reference for option passing.
• Incomplete datagrams are left in limbo. Should be able to signal via an option that the callback be invoked for individual fragments aswell as the complete datagram.
• The IP header in the packet supplied to the callback is from the first datagram. Length and checksum values will be incorrect with respect to the reassembled datagram that the callback sees.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. (Being a speaker of British english, I'd call it a "licence" though)

AUTHOR

James Raftery <james@now.ie>.