Reassemble(3p)

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. The layer 2 header, if present, will be from the last datagram to be captured.

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>.