NAME

Net::Packet - a unified framework to read and write packets over networks from layer 2 to layer 7

CLASS HIERARCHY

  Net::Packet
     |
     +---Net::Packet::Dump
     |
     +---Net::Packet::Desc
     |      |
     |      +---Net::Packet::DescL2
     |      |
     |      +---Net::Packet::DescL3
     |      |
     |      +---Net::Packet::DescL4
     |      |
     |      +---Net::Packet::DescL7
     |
     +---Net::Packet::Frame
            |
            +---Net::Packet::Layer
                   |
                   +---Net::Packet::Layer2
                   |      |
                   |      +---Net::Packet::ETH
                   |
                   +---Net::Packet::Layer3
                   |      |
                   |      +---Net::Packet::ARP
                   |      |
                   |      +---Net::Packet::IPv4
                   |
                   +---Net::Packet::Layer4
                   |      |
                   |      +---Net::Packet::TCP
                   |      |
                   |      +---Net::Packet::UDP
                   |      |
                   |      +---Net::Packet::ICMPv4
                   |
                   +---Net::Packet::Layer7
   
  Net::Packet::Simple

DESCRIPTION

This module is a unified framework to craft, send and receive packets at layers 2, 3, 4 and 7 (but 4 and 7 are just here for completeness, they have not been thoroughly tested. And you should use IO::Socket for layer 7, anyway).

Basically, you forge each layer of a frame (Net::Packet::IPv4 for layer 3, Net::Packet::TCP for layer 4 ; for example), and pack all of this into a Net::Packet::Frame object. Then, you can write it to the network, and use Net::Packet::Dump to receive responses.

GETTING STARED

When you use Net::Packet for the first time in a program, three package variables are automatically set in Net::Packet module: $Net::Packet::Dev, $Net::Packet::Ip, and $Net::Packet::Mac. They are taken from the default interface on your machine, the one taken by tcpdump when not user specified. I recommand you to set the package variable $Net::Packet::Debug to 3 when you are a beginner with this module.

   $Net::Packet::Debug = 3;

Let's create your first Net::Packet::Frame. We will build a TCP packet and send it at layer 3, so we must craft Net::Packet::IPv4 and Net::Packet::TCP headers.

   use Net::Packet::Frame;
   my $ip = Net::Packet::IPv4->new(
      dst => $desc->ipDst,
   );
   my $tcp = Net::Packet::TCP->new(
      dst => 22,
   );

You do not need to set the source IP, since it will be taken from the package variable $Net::Packet::Ip. Also, reasonable defaults are set for other fields in those two layers. See Net::Packet::IPv4 and Net::Packet::TCP for more. If you need to change default interface and/or IP, you can always overwrite it at the beginning of your program by manually setting $Net::Packet::Dev and/or $Net::Packet::Ip.

You have your layers 3 and 4, you can pack all into a frame:

   my $frame = Net::Packet::Frame->new(l3 => $ip, l4 => $tcp);

This step also automatically creates the descriptor that will be used to send frames over the network. That is, since you create a frame starting at layer 3, a Net::Packet::DescL3 object will be automatically created. The global $Net::Packet::Desc will be set to point to it. If you do not want to have an auto-creation of descriptor, you can always create it manually before calling Net::Packet::Frame->new, it will not be overwritten. See Net::Packet::Desc.

Also, a Net::Packet::Dump object is created (that is a tcpdump-like process), but not started for now. The $Net::Packet::Dump global is also written to point to it. If you do not want it to be auto-created, you can create one manually before calling Net::Packet::Frame->new for the first time. See Net::Packet::Dump.

Then, your frame is ok, you can send it over the network in order to receive your response:

   $frame->send;

When the first frame is sent using this method, the Net::Packet::Dump process is started, and ready to receive replies, unless it is already started.

You can sleep a few seconds, and then analyze for the response (if any):

   sleep(3);

   $Net::Pkt::Dump->analyze; # Analyze what have been captured by tcpdump, and
                             # unpack all frames into Net::Packet::Frame format

   my $reply = $frame->recv; # Get the Net::Packet::Frame corresponding to 
                             # the Net::Packet::Frame request from captured 
                             # frames stored in $Net::Packet::Dump->frames

   # Print response content, if any
   if ($reply) {
      $reply->ipPrint;
      $reply->tcpPrint;
   }

An alternative way is to use the global $Net::Packet::Timeout, which is set to 1 if no frame at all have been received from a certain amount of time. Be sure to create a Net::Packet::Dump object with a good pcap filter, because even if the packet read from the network is not destinated to your request, it resets the timeout. See Net::Packet::Dump.

   until ($Net::Packet::Timeout) {
      if ($Net::Packet::Dump->next && $frame->recv) {
         print "\nReply:\n";
         $frame->reply->ipPrint;
         $frame->reply->tcpPrint;
         last;
      }
   }

The method next only analyze for the next captured frame, but the analyze method is more a one shot since it analyzes all captured frames. See Net::Packet::Dump.

For more examples, see the examples directory in the source tarball.

AUTHOR

Patrice <GomoR> Auffret

COPYRIGHT AND LICENSE

Copyright (c) 2004, Patrice <GomoR> Auffret

You may distribute this module under the terms of the Artistic license. See Copying file in the source distribution archive.

RELATED MODULES

NetPacket, Net::RawIP, Net::RawSock

cpanm Net::Packet

perl -MCPAN -e shell
install Net::Packet