Differences for page hping3 APICurrent version compared with version Tue May 18 04:09:15 GMT 2004...
part already implemented in the current CVS version of hping3.
Also note that this document currently does NOT cover the hping standard
- library, that is an higher level API build on top of the low-level API
+ library, which is a higher level API build on top of the low-level API
(for low-level API I mean what's described in this document).
===API basics===
...
-> [hping setfield]
-> [hping delfield]
-> [hping checksum]
+ -> [hping event]
Most are to receive, send, and manage packets, and in general all the
subcommands of the hping command are about networking.
...
+ Click on the links to have more information about every specific command.
- ----
-
- OVERVIEW
-
- Hping uses the Tcl language as scripting language to write networking
- and security related applications, test suites, and software prototypes.
- To run hping in scripting mode just run it without arguments.
-
- # hping
-
- It will display a prompt, and will accept commands from the standard
- input. Here you can write Tcl commands, and use the embedded
- hping command to manipulate, send and receive packets, set filters,
- read the interface list and so on.
-
- To execute an hping script, call the hping program with "exec"
- as first argument followed by the name of the script and
- the arguments.
-
- # hping exec hping.htcl www.hping.org
-
- The goal of this document is to describe the API exported by hping
- to the Tcl language. This document aims to be informative, but will
- not cover all the aspects of the API usage: the experienced user
- should be able to fully exploit the hping capabilities just reading
- this document and the examples under the 'lib' directory.
-
- Note that the API is not yet complete: this document only covers the
- part already implemented in the current CVS version of hping3.
-
- Also note that this document currently does NOT cover the hping standard
- library, that is an higher level API build on top of the low-level API
- (for low-level API I mean what's described in this document).
-
- The plan is to start a Wiki to document hping3 in a collaborative way.
-
- --------------------------------------------------------------------------------
-
- API BASICS
- The main idea of the hping API is to export a single command for every
- 'section' of the facilities provided by hping.
-
- The most important command exported is 'hping', this command
- expects a subcommand that specify the operation to perform. The
- following subcommands are currently available:
-
- resolve
- send
- sendraw
- recv
- recvraw
- iflist
- outifa
- getfield
- hasfield
- setfield
- delfield
- checksum
-
- Most are to receive, send, and manage packets, and in general all the
- subcommands of the hping command are about networking.
+ See also [hpingstdlib.htcl] for functions included in the standard library.
- HPING SUBCOMMANDS
-
- hping resolve <hostname>
-
- The resolve subcommand translate an host name in its IPv4 address
- using the DNS system. It is basically a gethostname() wrapper, that
- just returns its input if <hostname> is already an IP address.
-
- Example:
-
- hping3.0.0-alpha> hping resolve www.hping.org
- 192.70.106.166
-
- --
-
- #######################################################
- hping recv ?-hexdata? <interface> ?timeout? ?count?
- #######################################################
-
- Receive packets as a Tcl list in the APD format. <interface> is
- the interface from wich to read packets, ?timeout? is an optional
- argument to set a timeout value in milliseconds, with the
- exception that a zero timeout means to return as soon as possible
- the packets that was already in queue when the recv subcommand
- was called, while a -1 timeout value means to expect forever
- for packets (no timeout). If ?timeout? is specified, an additional
- (optional) ?count? parameter can be specified, modifing the recv
- subcommand behaviour to return as soon as ?count? packets were
- already received. A special ?count? value of zero means
- to collect an infinite number of packets (at least until the
- timeout is not reached).
-
- The optional ?-hexdata? switch specify to return packets payload
- as hex digits instead of quoted strings. To use -hexdata is encouraged
- for all the applications, but the ones that needs to display packets
- in a human readable format.
-
- For default the timeout is set to -1, and count to 1 (in other
- words hping will wait forever if no packets are available, but
- will return when the first packet is received).
-
- Examples:
-
- # Capture a packet from eth0
- hping3.0.0-alpha> hping recv eth0
- {ip(ihl=5,ver=4,tos=02,totlen=58,id=63474,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=9ecb,saddr=192.168.1.6,daddr=213.82.224.41)+tcp(sport=33295,dport=110,seq=2486133764,ack=2745754339,x2=0,off=8,flags=pa,win=5840,cksum=7a69,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=1021017,ecr=355869116)+data(str=STAT\0d\0a)}
-
- # Caputure a packet using the hex format for data payload
- hping3.0.0-alpha> hping recv -hexdata eth0
- ip(ihl=5,ver=4,tos=00,totlen=84,id=2435,fragoff=0,mf=0,df=0,rf=0,ttl=49,proto=1,cksum=25be,saddr=216.239.39.99,daddr=192.168.1.6)+icmp(type=0,code=0,id=55048,seq=512)+data(hex=3f565c1b000d7e4008090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f3031323334353637)
-
- # Wait for all the packets received in 5 seconds, and print how much they are
- hping3.0.0-alpha> puts [llength [hping recv eth0 5000 0]]
- 36
-
- --
-
- ################
- hping iflist
- ################
-
- The iflist subcommand returns a list of all the available interfaces
- (with the UP flag set), and information about every interface.
- Interface informations are returned as a Tcl list, that's
- an example:
-
- hping3.0.0-alpha> hping iflist
- {lo 16436 {127.0.0.1} {LOOPBACK}} {eth0 1500 {192.168.1.6} {}}
-
- # But this may be more clear:
-
- hping3.0.0-alpha> foreach i [hping iflist] {puts $i}
- lo 16436 {127.0.0.1} {LOOPBACK}
- eth0 1500 {192.168.1.6} {}
-
- # As you can see both the interface addresses and flags are reported
- # as Tcl lists, in order to deal with multiple-flags and addresses
- # interfaces. This is an example:
-
- hping3.0.0-alpha> foreach i [hping iflist] {puts $i}
- lo0 33224 {127.0.0.1} {LOOPBACK}
- xl0 1500 {191.224.144.21 64.238.141.219} {}
-
- # The above host has an IPv4 alias for xl0
-
- --
-
- #########################
- hping outifa <target>
- #########################
-
- Experienced users will not be satisfied with the iflist subcommand alone.
- Suppose you want to rewrite the ping program in hping, you need to
- know what is the interface used to send and receive packets for a given
- destination. The outifa subcommand does exactly this: it returns the
- IPv4 address of the outgoing interface for the <target> destination.
-
- Assuming there are no bugs nor hyper-strange configurations, the
- address returned will match at least one of the interface addresses
- returned with hping iflist. The implementation of this command
- may not work in all the cases in this beta version of hping.
-
- Example:
-
- hping3.0.0-alpha> hping outifa www.google.com
- 192.168.1.6
- hping3.0.0-alpha> hping iflist
- {lo 16436 {127.0.0.1} {LOOPBACK}} {eth0 1500 {192.168.1.6} {}}
-
- # As you can see 192.168.1.6 is the eth0 unique address -- note that
- # the host is configured with a 192.168.1.1 as default gateway.
-
- To write a Tcl procedure that returns the name of the interface
- with a given address is trivial, such a procedure is included
- in the hping standard library (hpingstdlib.htcl).
-
- --
-
- ##################################
- hping send ?-nocompile? packet
- ##################################
-
- This command is used to send TCP/IP packets. It is able to send
- packets specified in the same format the command 'hping recv' returns
- packets, this basically means that you can experiment with
- 'hping recv' in order to undrestand how to send a given packet.
- Also note that a common pattern with hping3 is to receive
- packets with 'hping recv', modify this packets in some way
- and resend with 'hping send'. This makes the creation of scripts
- to do NAT and all the sort of TCP/IP flow manipulation very easy.
-
- In order to send a TCP packet with the SYN flag set to the
- host www.hping.org one can write:
-
- hping3> set target www.hping.org
- www.hping.org
- hping3> set myaddr [hping outifa $target]
- 192.168.1.6
- hping3> hping send "ip(saddr=$myaddr,daddr=$target,ttl=255)+tcp(sport=123,dport=80,flags=s)"
-
- Note that the first two commands are used to get the outgoing interface
- address. From the example it should be clear that in the hping3 world
- packets are strings rappresenting different layers of the packet.
- When a given layer is not specified by the user, hping try to set
- it at a reasonable value. For instance the user don't need to
- specify IP and TCP checksums for normal packets because hping will
- compute it automatically. Of curse to create broken packets it can
- be useful to specify a checksum field.
-
- Working with packets as strings, it is handy to create a packet
- starting with an empty string, adding a layer at a time: this makes
- the code very simple to read. For example the previous code to
- send a packet can be written this way:
-
- set target www.hping.org
- set myaddr [hping outifa $target]
- set syn {}
- append syn "ip(saddr=$myaddr,daddr=$target,ttl=255)"
- append syn "+tcp(sport=123,dport=80,flags=2)"
- hping send $syn
-
- You can cut&paste the code in a file called 'example.htcl', then
- run it using:
-
- hping3 exec example.htcl
-
- Note that you can use all the features of Tcl, for example
- in order to send the same SYN packet with 10 different TTL values
- it is possible to modify the previous script to obtain this:
-
- set target www.hping.org
- set myaddr [hping outifa $target]
- for {set ttl 0} {$ttl < 10} {incr ttl} {
- set syn {}
- append syn "ip(saddr=$myaddr,daddr=$target,ttl=$ttl)"
- append syn "+tcp(sport=123,dport=80,flags=2)"
- hping send $syn
- }
-
- The '-nocompile' optional switch is used to tell hping to don't
- compile the packet (packet compilation calculate stuff like
- checksums, tot length, and so on), it is useful in order to
- send broken packets.
-
- --
-
- ##################################################
- hping getfield layer field ?skip? packet
- hping hasfield layer field ?skip? packet
- hping setfield layer field value ?skip? packet
- hping delfield layer field ?skip? packet
- ##################################################
-
- So in hping packets are strings, this makes to work with packets
- simple, but sometimes to modify a field may require to use
- string substitution, regexp, or alike, not very clean nor fast,
- so hping API exports functions to set, read, and test for
- given fields in given layers.
-
- 'hping getfield' returns the value of the given 'field' in the given
- 'layer', for 'packets'. For example:
-
- hping3> hping getfield ip ttl "ip(saddr=1.2.3.4,daddr=5.6.7.8,ttl=64)"
- 64
-
- If the layer does not exists, an empty string is returned.
-
- In complex packets the same layer can be present more times,
- for example an ICMP error message can have its own IP header
- and the IP header of the quoted packet. In order to specify
- what is the right layer the 'skip' argument of get/has/set field
- is used. This argument specify how many layers of the specified
- type to skip before to get the field value, so to specify a
- skip value of 1 means to get the field from the second IP layer
- and so on. Example:
-
- hping3.0.0-alpha> set p [hping recv eth0]
- {ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)}
-
- Remember that 'hping recv' returns a Tcl list, for default this list
- is composed of only one element, but anyway we need to get extract
- this element from the list:
-
- hping3.0.0-alpha> set packet [lindex $p 0]
- ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)
-
- Now 'packet' is set to an ICMP error obtained using netcat to send an UDP packet
- to a non-bound port. We can ask for the checksum of the first ip layer:
-
- hping3.0.0-alpha> hping getfield ip cksum $packet
- e500
-
- If we want the second, we add a 'skip' argument of 1:
-
- hping3.0.0-alpha> hping getfield ip cksum 1 $packet
- 40c9
-
- A 'skip' value of 0 is valid, and is equivalent to the
- form without the skip argument.
-
- 'hping hasfield' is similar to getfield, but just returns 1 if the
- specified layer/field exists, otherwise 0 is returned.
-
- 'hping setfield' is used to set a given field in a packet, it returns
- a new packet with the given field set to the specified value:
-
- hping3.0.0-alpha> hping setfield udp sport 2000 $packet
- ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=2000,dport=10,len=10,cksum=94d6)+data(str=fa)
-
- So in order to modify a packet hold in a Tcl variable it is possible
- to write:
-
- set packet [hping setfield udp sport 2000 $packet]
-
- 'hping setfield' can't add fields, so an attempt to set a non-existent
- layer/field returns an error.
-
- Note that get/has/set field commands are not enough to deal
- with packets without to use 'regexp', 'regxub', 'split', and so,
- but other hping commands to directly add/remove layers, add
- fields, and so on, will be added before the hping3 stable release.
-
- Btw, note that field name and values are guaranteed to don't contain
- a '+', ',', ')', and other similar characters that are used in
- the syntax to describe packets, so to split packets in layers using
- + as separator, or to split a layer in fields using ',' as separator
- is prefrectly legal. Some example:
-
- hping3.0.0-alpha> foreach layer [split $packet +] {puts $layer}
- ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)
- icmp(type=3,code=3,unused=0)
- ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)
- udp(sport=33169,dport=10,len=10,cksum=94d6)
- data(str=fa)
-
- A more complex example: a Tcl procedure that split a packet in layers
- and fields.
-
- ################################### split.htcl #################################
- set packet "ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)"
-
- foreach layer [split $packet +] {
- set t [split $layer ()]
- set name [lindex $t 0]
- set fields [lindex $t 1]
- puts $name
- foreach field [split $fields ,] {
- puts " $field"
- }
- puts {}
- }
- ################################################################################
-
- This script produce the following output:
-
- ip
- ihl=5
- ver=4
- tos=c0
- totlen=58
- id=62912
- fragoff=0
- mf=0
- df=0
- rf=0
- ttl=64
- proto=1
- cksum=e500
- saddr=192.168.1.7
- daddr=192.168.1.6
-
- icmp
- type=3
- code=3
- unused=0
-
- ip
- ihl=5
- ver=4
- tos=00
- totlen=30
- id=60976
- fragoff=0
- mf=0
- df=1
- rf=0
- ttl=64
- proto=17
- cksum=40c9
- saddr=192.168.1.6
- daddr=192.168.1.7
-
- udp
- sport=33169
- dport=10
- len=10
- cksum=94d6
-
- data
- str=fa
-
- You can create your own procedure to deal with packets, but eventually
- the interface that seems the more useful will be included in the
- hping standard library. Two functions to convert hping APD packets
- to Tcl lists, and the reverse are already included in the hping standard
- library. Check for 'apd2list' and 'list2apd'. That's how they works:
-
- # Get a packet...
- hping3.0.0-alpha> set p [lindex [hping recv eth0] 0]
- ip(ihl=5,ver=4,tos=00,totlen=52,id=28845,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=bb46,saddr=192.168.1.5,daddr=192.168.1.6)+tcp(sport=3733,dport=4662,seq=2054230415,ack=1135045853,x2=0,off=8,flags=a,win=63700,cksum=a509,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=6860018,ecr=13978115)
-
- # Convert it to a Tcl list
- hping3.0.0-alpha> apd2list $p
- {ip {ihl 5} {ver 4} {tos 00} {totlen 52} {id 28845} {fragoff 0} {mf 0} {df 1} {rf 0} {ttl 64} {proto 6} {cksum bb46} {saddr 192.168.1.5} {daddr 192.168.1.6}} {tcp {sport 3733} {dport 4662} {seq 2054230415} {ack 1135045853} {x2 0} {off 8} {flags a} {win 63700} {cksum a509} {urp 0}} tcp.nop tcp.nop {tcp.timestamp {val 6860018} {ecr 13978115}}
-
- With the Tcl list representation we can do what we like, than go back
- to the more human friedlty representation:
-
- hping3.0.0-alpha> list2apd $list
- ip(ihl=5,ver=4,tos=00,totlen=52,id=28845,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=bb46,saddr=192.168.1.5,daddr=192.168.1.6)+tcp(sport=3733,dport=4662,seq=2054230415,ack=1135045853,x2=0,off=8,flags=a,win=63700,cksum=a509,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=6860018,ecr=13978115)
-
- Simple, isn't it?
-
- Btw, note that for most scripts you don't need to perform this kind of
- stuff, the hping native representation try to balance between the
- human and computer vision of packets.
-
- Finally, 'hping delfield' is able to remove the given layer/field
- from the packet. This is very useful in order to resend a packet
- got with 'hping recv': before to resend it we often need to remove
- the checksum fields from ip/udp/tcp/icmp layers so hping will
- recompute it again.
-
- --
-
- ###############################################
- hping recvraw ifname ?timeout? ?maxpackets?
- ###############################################
-
- 'hping recvraw' works exactly like 'hping recv', but packets
- are returned as raw binary data. This is useful for low-level
- access to packets using the 'binary' Tcl command.
-
- This will be more useful once the commands 'hping build' and 'hping describe'
- commands will be added (for APD -> binary, binary -> APD conversion).
-
- Example:
-
- hping3.0.0-alpha> string length [hping recvraw eth0]
- 1540
-
- --
-
- ######################
- hping sendraw data
- ######################
-
- Send binary data: that's like to call write(2) against a raw socket.
- It can be used in order to build special packets that can't be
- specified using the usual string representation (APD, from Ars Packet
- Description), but will be more useful once all the hping output
- operation will be able to handle layer-2. For now hping3's business
- is only at layer-3.
-
- + See also [Parsing APD fields]. The following is the old page content
|