NAME¶
Net::RawIP - Perl extension to manipulate raw IP packets with interface to
libpcap
VERSION¶
This is the documentation of "Net::RawIP" version 0.25
SYNOPSIS¶
use Net::RawIP;
$n = Net::RawIP->new({
ip => {
saddr => 'my.target.lan',
daddr => 'my.target.lan',
},
});
tcp => {
source => 139,
dest => 139,
psh => 1,
syn => 1,
},
});
$n->send;
$n->ethnew("eth0");
$n->ethset(source => 'my.target.lan', dest =>'my.target.lan');
$n->ethsend;
$p = $n->pcapinit("eth0", "dst port 21", 1500, 30);
$f = dump_open($p, "/my/home/log");
loop($p, 10, \&dump, $f);
DESCRIPTION¶
This package provides a class which can be used for creating, manipulating and
sending raw IP packets with optional features for manipulating Ethernet
headers.
Note: Ethernet related methods are implemented on Linux and *BSD only.
As its name implies, this module is quite low-level, and currently duplicates
some features with "Net::Pcap". If you prefer a higher-level module
(in terms of Perl support), please take a look at "Net::Write",
which provides a portable interface to construct and send raw packets on the
network.
Exported constants¶
PCAP_ERRBUF_SIZE
PCAP_VERSION_MAJOR
PCAP_VERSION_MINOR
lib_pcap_h
Exported functions¶
open_live open_offline dump_open lookupdev lookupnet dispatch loop dump compile
setfilter next datalink snapshot is_swapped major_version minor_version stats
file fileno perror geterr strerror close dump_close timem linkoffset
ifaddrlist rdev
By default exported functions are the
loop,
dispatch,
dump_open,
dump,
open_live,
timem,
linkoffset,
ifaddrlist,
rdev. You have to use the export
tag
pcap for export all of the pcap functions. Please read the docs for
the libpcap and look at
Net::RawIP::libpcap(3pm).
Please look at the examples in the examples/ folder of the distribution.
METHODS¶
- new
-
Net::RawIP->new({
ARGPROTO => {PROTOKEY => PROTOVALUE,...}
ip => {IPKEY => IPVALUE,...},
})
ARGPROTO is one of (tcp, udp, icmp,
generic) defining the protcol of the current packet. Defaults to
tcp.
You can NOT change protocol in the object after its creation. Unless
you want your packet to be TCP, you must set the protocol type in the
new() call.
The possible values of PROTOKEY depend on the value of ARGPROTO
If ARGPROTO is <tcp> PROTOKEY can be one of ( source,
dest, seq, ack_seq, doff, res1,
res2, urg, ack, psh, rst, syn,
fin, window, check, urg_ptr, data).
If ARGPROTO is icmp PROTOKEY can be one of ( type,
code, check, gateway, id, sequence,
unused, mtu, data).
If ARGPROTO is udp PROTOKEY can be one of ( source,
dest, len, check, data)
If ARGPROTO is generic PROTOKEY can be data only.
The data entries are scalars containing packed network byte order
data.
As the real icmp packet is a C union one can specify only one of the
following set of values.
- •
- gateway - (int)
- •
- (id and sequence) - (short and short)
- •
- (mtu and unused) - (short and short)
The default values are:
- •
- (0,0,0,0,5,0,0,0,0,0,0,0,0,0xffff,0,0,'') for tcp
- •
- (0,0,0,0,0,0,0,0,'') for icmp
- •
- (0,0,0,0,'') for udp
- •
- ('') for generic
The valid values for
urg ack psh rst syn
fin are 0 or 1. The value of
data is a string. Length of the
result packet will be calculated if you do not specify non-zero value for
tot_len.
The value of
ip is a hash defining the parameters of the IP header (
iphdr) in the current IP packet.
IPKEY is one of (
version,
ihl,
tos,
tot_len,
id,
frag_off,
ttl,
protocol,
check,
saddr,
daddr). You can to specify any and all of the above
parameters. If
check is not given checksum will be calculated
automatically.
The values of the
saddr and the
daddr can be hostname (e.g.
www.oracle.com ) or IP address (205.227.44.16), and even the integer value if
you happen to know what is 205.227.44.16 as an unsigned int in the host format
;).
Examples:
my $rawip = Net::RawIP->new({udp =>{}});
or
my $rawip = Net::RawIP->new({ip => { tos => 22 }, udp => { source => 22,dest =>23 } });
The default values of the
ip hash are
- •
- (4,5,16,0,0,0x4000,64,6,0,0,0) for tcp
- •
- (4,5,16,0,0,0x4000,64,17,0,0,0) for udp
- •
- (4,5,16,0,0,0x4000,64,1,0,0,0) for icmp
- •
- (4,5,16,0,0,0x4000,64,0,0,0,0) for generic
- dump_open
- If dump_open opens and returns a valid file
descriptor, this descriptor can be used in the perl callback as a perl
filehandle.
- loop
- dispatch
- loop and dispatch can run a perl code refs as
a callbacks for packet analyzing and printing. the fourth parameter for
loop and dispatch can be an array or a hash reference and it
can be dereferenced in a perl callback.
- next
- next() returns a string (next
packet).
- timem
- timem() returns a string that
looks like sec.microsec, where the sec and the
microsec are the values returned by gettimeofday(3). If
microsec is less than 100000 then zeros will be added to the left
side of microsec for adjusting to six digits.
Similar to sprintf("%.6f", Time::HiRes::time());
- linkoffset
- The function which called linkoffset returns a
number of the bytes in the link protocol header e.g. 14 for a Ethernet or
4 for a Point-to-Point protocol. This function has one input parameter
(pcap_t*) that is returned by open_live.
- ifaddrlist
- ifaddrlist() returns a hash
reference. In this hash keys are the running network devices, values are
ip addresses of those devices in an internet address format.
- rdev
- rdev() returns a name of the
outgoing device for given destination address. It has one input parameter
(destination address in an internet address or a domain name or a host
byteorder int formats).
- proto
- Returns the name of the subclass current object e.g.
tcp. No input parameters.
- packet
- Returns a scalar which contain the packed ip packet of the
current object. No input parameters.
- set
- Method for setting the parameters of the current object.
The given parameters must look like the parameters for the
constructor.
- bset($packet,$eth)
- Method for setting the parameters of the current object.
$packet is a scalar which contain binary structure
(an ip or an eth packet). This scalar must match with the subclass of the
current object. If $eth is given and it have a
non-zero value then assumed that packet is a ethernet packet,otherwise it
is a ip packet.
- get
- is a method for get the parameters from the current object.
This method returns the array which will be filled with an asked
parameters in order as they have ordered in packet if you'd call it with
an array context. If this method is called with a scalar context then it
returns a hash reference. In that hash will stored an asked parameters as
values,the keys are their names.
The input parameter is a hash reference. In this hash can be three keys.
They are a ip and an one of the ARGPROTOs. The value must be
an array reference. This array contain asked parameters. E.g. you want to
know current value of the tos from the iphdr and the flags of the tcphdr.
Here is a code :
($tos,$urg,$ack,$psh,$rst,$syn,$fin) = $packet->get({
ip => [qw(tos)],
tcp => [qw(psh syn urg ack rst fin)]
});
The members in the array can be given in any order.
For get the ethernet parameters you have to use the key eth and the
values of the array ( dest,source,proto). The values
of the dest and the source will look like the output of the
ifconfig(8) e.g. 00:00:E8:43:0B:2A.
- open_live
- send($delay,$times)
- is a method which has used for send raw ip packet. The
input parameters are the delay seconds and the times for repeating send.
If you do not specify parameters for the send,then packet will be
sent once without delay. If you do specify for the times a negative value
then packet will be sent forever. E.g. you want to send the packet for ten
times with delay equal to one second. Here is a code :
$packet->send(1,10);
The delay could be specified not only as integer but and as 0.25 for sleep
to 250 ms or 3.5 to sleep for 3 seconds and 500 ms.
- pcapinit($device,$filter,$psize,$timeout)
- is a method for some a pcap init. The input parameters are
a device,a string with a program for a filter,a packet size,a timeout.
This method will call the function open_live,then compile the filter
string by compile(), set the filter and returns the pointer (
pcap_t *).
- pcapinit_offline($fname)
- is a method for an offline pcap init.The input parameter is
a name of the file which contains raw output of the libpcap dump function.
Returns the pointer ( pcap_t *).
- ethnew($device,dest
=> ARGOFDEST,source => ARGOFSOURCE)
- is a method for init the ethernet subclass in the current
object, $device is a required parameter, dest
and source are an optional, $device is an
ethernet device e.g. eth0, an ARGOFDEST and an
ARGOFSOURCE are a the ethernet addresses in the ethernet header of
the current object.
The ARGOFDEST and the ARGOFSOURCE can be given as a string
which contain just 6 bytes of the real ethernet address or like the output
of the ifconfig(8) e.g. 00:00:E8:43:0B:2A or just an ip address or
a hostname of a target, then a mac address will be discovered
automatically.
The ethernet frame will be sent with given addresses. By default the
source and the dest will be filled with a hardware address
of the $device.
NOTE: For use methods which are related to the ethernet you have to
before initialize ethernet subclass by ethnew.
- ethset
- is a method for set an ethernet parameters in the current
object. The given parameters must look like parameters for the
ethnew without a $device.
- ethsend
- is a method for send an ethernet frame. The given
parameters must look like a parameters for the send.
- send_eth_frame($frame,$times,$delay)
- is a method for send any ethernet frame which you may
construct by hands. $frame is a packed ethernet frame
exept destination and source fields(these fields can be setting by
ethset or ethnew). Another parameters must look like the
parameters for the send.
- optset(OPTPROTO => { type => [...],data => [...]
},...)
- is a method for set an IP and a TCP options. The parameters
for the optset must be given as a key-value pairs. The OPTPROTO,s
are the prototypes of the options( ip,tcp),values are the
hashes references.The keys in this hashes are type and data.
The value of the type is an array reference. This array must be
filled with an integers.Refer to a RFC for a valid types.The value of the
data also is an array reference. This array must be filled with
strings which must contain all bytes from a option except bytes with type
and length of an option.Of course indexes in those arrays must be equal
for the one option.If type is equal to 0 or 1 then there is no bytes with
a length and a data,but you have to specify zero data for
compability.
- optget(OPTPROTO => { type => [...] },...)
- is a method for get an IP and a TCP options. The parameters
for the optget must be given as key-value pairs. The OPTPROTO is
the prototype of the options( ip,tcp),the values are the
hashes references.The key is the type.The value of the type
is an array reference. The return value is an array which will be filled
with asked types,lengths,datas of the each type of the option in order as
you have asked.If you do not specify type then all types,lengths,datas of
an options will be returned. E.g. you want to know all the IP options from
the current object. Here is a code:
@opts = $n->optget(ip => {});
E.g. you want to know just the IP options with the type which equal to 131
and 137. Here is a code:
($t131,$l131,$d131,$t137,$l137,$d137) = $n->optget(
ip =>{
type =>[(131,137)]
} );
- optunset
- is a method for unset a subclass of the IP or the TCP
options from a current object.It can be used if you won't use options in
the current object later. This method must be used only after the
optset. The parameters for this method are the OPTPROTO's.
E.g. you want to unset an IP options. Here is a code:
$n->optunset('ip');
E.g. you want to unset a TCP and an IP options. Here is a code:
$n->optunset('ip','tcp');
SEE ALSO¶
pcap(3),
tcpdump(1), RFC 791-793, RFC 768.
Net::Pcap, Net::Pcap::Easy, Net::Pcap::Reassemble, Net::Pcap::FindDevice
Net::Write for an alternative module to send raw packets on the network
AUTHORS¶
Current maintainer is Sebastien Aperghis-Tramoni <sebastien@aperghis.net>
Previous authors & maintainers:
- •
- Sergey Kolychev <ksv@al.lg.ua>
- •
- Gabor Szabo <gabor@pti.co.il>
COPYRIGHT & LICENSE¶
Copyright (c) 1998-2006 Sergey Kolychev. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.
CREDITS¶
Steve Bonds <u5rhsiz02@sneakemail.com>
+ work on some endianness bugs and improving code comments