hping wiki

Differences for page hping3 API

Current 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