                                   spak v0.6b
                                   2 Mar 1998


                               Table of Contents

  I.......................................................Introduction
  II......................................................Compiling
  III.....................................................Usage
     A....................................................makeip
     B....................................................maketcp
     C....................................................makeudp
     D....................................................makearp
     E....................................................makeeth
     F....................................................sendpacket
     G....................................................senteth
     H....................................................option file format
  IV......................................................Contact Information
  V.......................................................Notes
  VI......................................................Acknowledgements
  VII.....................................................BUGS


I. Introduction

Spak (Send PAcKet) is a collection of programs that can be used to create and
send a packet over a network.  Spak is designed to be very modular and allow
as much control over the design of the packet as possible.  The modules
included with this release are:

makeip       Make an IP packet
maketcp      Make a TCP packet
makeudp      Make a UDP packet
makearp      Make an ARP/RARP packet
makeeth      Make an Ethernet frame
sendpacket   Send a packet to a socket
sendeth      Send an Ethernet frame

Spak was designed to be used as part of a firewall testing project to create
arbitrary packets, but there are undoubtedly other uses, ("good" and "bad"),
that this sort of program may be used to accomplish.  It is the authors desire
that this program will be used to learn about various protocols or for testing
purposes and not for malicious behavior.

WARNING: Spak is in the process of being developed and has not been tested
         extensively.  For this reason it is in BETA stage which means there
         may be bugs in the code and unimplemented features.  Unless you are
         helping with the development, or just want to use the program for
         experimental use, please wait until version 1.0 is released.  Please
         see the BUGS section (Section VII) for a list of bugs and
         unimplemented options.


II. Compiling

Spak was developed and tested under Linux 2.0.x, SunOS 5.5.1, and BSDI 3.1
systems.  

To compile Spak, follow these steps:

1.  Visit http://www.cs.purdue.edu/homes/steinkf/software/spak to get the
    latest version.
2.  Unpack the source somewhere on the system that will be used to compile it.
3.  Edit config.h and make any changes that you want.  The most important
    option in this file is the selection of your operating system.  To define
    a system type, remove the leading /* (if any) in front of the system name.
    Only one system type should be defined.  To undefine a system, put a /* in
    front of the #define <system> line.
4.  (optional) Edit the files ending in _conf.h to change the default behavior
    of the various programs.  Most of these defaults may be overwritten by
    command-line options to the various programs, but you have the option of
    setting them in the _conf.h files if you want.  For example, the con-
    figuration file for the makeudp program is makeudp_conf.h.
5.  Copy the appropriate make file to Makefile.  For example, if you are
    compiling Spak on a Linux system, you would issue the following command:

      cp Makefile.LINUX Makefile

    Make files for SunOS/Solaris and BSDI 3.1 systems are also included.
6.  Look over the Makefile to see if there is anything you want to change.
    If you are having problems compiling on a Linux system, you may want to
    add -D__BSD_SOURCE to your COPT line, (see Makefile.LINUX for more
    information).
7.  Type make to build the program.  You should not get any warnings or
    errors.

You should now have the executable files maketcp, makeip, makeudp, makeeth,
makearp, sendeth, and sendpacket.  Install these wherever you want.  The
contrib directory contains some simple scripts which can be used as examples
when creating your own packet generation routines.


III. Usage

The core programs released with the Spak program are probably not very useful
when taken individually, but when used together, (i.e. called from a shell
script), they can create an infinite number of valid--and invalid--packets,
and send them to a network such as the Internet.  For example, to create a
TCP/IP packet, one would first use the maketcp program to create a TCP packet
containing header information and data, (if any).  This packet would be used
as input to the makeip program.  After makeip is run, a complete IP packet
containing the TCP packet would be generated and the sendpacket program would
be called with the output of the makeip program as input to send the newly
created packet to a socket (See Fig. 1).


   Step 1        Step 2 (maketcp)     Step 3 (makeip)      Step 4 (sendpacket)
 __________       ______________       _____________
|File      |     |File generated|     |File generated|     File generated
|containing|     |by maketcp.   |     |by makeip.    |     in Step 3 is sent
|data to   | --> |File created  | --> |File created  | --> to a socket, (to
|send      |     |in Step 1 is  |     |in Step 2 is  |     the network).
 ----------      |used as input.|     |used as input.|
                  --------------       --------------

  Raw Data          TCP packet           IP Packet

                                     Fig. 1


For more examples of this process including scripts to generate some packets,
please view the README in the contrib directory which should be part of this
release.

A. makeip

  The makeip program generates an IP packet.  You must supply the makeip
  program with a source and destination address for the packet to have.  You
  may also supply several other optional arguments in order to create a packet
  that matches your specifications.  The format of the makeip program is as
  follows:

  makeip <src> <dest> [optional_arguments]

  The <src> argument is the source address for the packet.  This may either be
  an numerical address in the form xxx.xxx.xxx.xxx where the x's are a valid
  IP number, (e.g. 192.168.2.1), or a valid word address which can be resolved
  to an IP number, (e.g. lore.cs.purdue.edu).  The <dest> argument is the
  destination address for the packet and can be in the same forms as the <src>
  argument.  Valid [optional_arguments] are nothing or any of the following:

  [-h] [-v] [-vr <version>] [-p <protocol>] [-pr <priority>] [-id <id>]
  [-hl <hdr_len>] [-c <hdr_cksum>] [-tl <total_len>] [-s6] [-s7] [-sd] [-sf]
  [-smf] [-snf] [-sr] [-st] [-fo <frag_offset>] [-ttl <time>]
  [-i <input_file>] [-o <output_file>] [-of <opt_file>]

  -c    Set the header checksum to <hdr_cksum>.
  -fo   Set the fragment offset to <fragment_offset>.
  -h    Print a help message.
  -hl   Set the header length to <hdr_len>.
  -i    Read the packet data from the file <input_file>.  If <input_file> is
        -, the data will be read from stdin.
  -id   Set the packet ID to <id>.
  -o    Send the output to the file <output_file>.  If this argument is not
        given, the packet will be written to stdout.
  -of   Set the options listed in <opt_file>, (under construction).
  -p    Set the protocol to <protocol>, (number).
  -pr   Set the priority to <priority>.
  -tl   Set the total packet length.
  -ttl  Set time to live to <time>.
  -s6   Set the 6th bit in the type of service field.
  -s7   Set the 7th bit in the type of service field.
  -sd   Set the "low delay" bit.
  -sf   Set the first bit in the flag field.
  -sdf  Set the "don't fragment" bit.
  -smf  Set the "more fragments" bit.
  -sr   Set the "high reliability" bit.
  -st   Set the "high throughput" bit.
  -vr   Set the IP version to <version>.
  -v    Turn on verbose mode, (print packet data).

  For more information about the various header settings, you may read RFC
  791 which may be found at ftp://ds.internic.net/rfc/rfc791.txt.  If an
  argument is not specifically set, it defaults to a normal value.

  The -i argument is especially important because it allows you to attach an
  IP header, (which makeip generates), to a packet that was created by another
  program such as maketcp.

B. maketcp

  The maketcp program generates an TCP packet.  You must supply the maketcp
  program with a source and destination address for the packet to have, and
  source and destination ports for the packet.  You may also supply several
  other optional arguments in order to create a packet that matches your
  specifications.  The format of the maketcp program is as follows:

  maketcp <src> <src_port> <dest> <dest_port> [optional_arguments]

  The <src> argument is the source address for the packet.  This may either be
  an numerical address in the form xxx.xxx.xxx.xxx where the x's are a valid
  IP number, (e.g. 192.168.2.1), or a valid word address which can be resolved
  to an IP number, (e.g. lore.cs.purdue.edu). The <dest> argument is the
  destination address for the packet and can be in the same forms as the <src>
  argument.  The <src_port> and <dest port> arguments specify the source and
  destination ports to use.  These arguments may be a number or word, (e.g.
  ftp for port 21).  Valid [optional_arguments] are nothing or any of the
  following:

  -a        Set the acknowledge number to <ack_num>.  Default: random
  -do       Set the data offset to <offset>.  Default: 0
  -h        Print this help message.
  -c        Set the header checksum to <hdr_cksum>.  Default: correct value
  -i        Read the packet data from the file <input_file>.  If <input_file>
            is -, the data will be read from stdin.
  -o        Send the output to <output_file>.  If this argument is not given,
            the output will be sent to stdout.
  -r1 - -r6 Set reserved bits, (-r5 sets bit 5).  Default: not set
  -s        Set the sequence number to <seq_num>.  Default: random
  -sa       Set the ACK bit.  Default: not set
  -sf       Set the FIN bit.  Default: not set
  -sp       Set the PSH bit.  Default: not set
  -sr       Set the RST bit.  Default: not set
  -ss       Set the SYN bit.  Default: not set
  -su       Set the URG bit.  Default: not set
  -uo       Set the urgent offset to <offset>.  Default: 0
  -v        Turn on verbose mode, (print packet data).
  -w        Set the window size to <win_size>.  Default: 512

  For more information about the various header settings, you may read RFC
  793 which may be found at ftp://ds.internic.net/rfc/rfc793.txt.  If an
  argument is not specifically set, it defaults to a normal value.

C. makeudp

  The makeudp program generates a UDP packet.  You must supply the makeudp
  program with a destination port for the packet to have.  You may also supply
  several other optional arguments in order to create a packet that matches
  your specifications.  The format of the makeudp program is as follows:

  makeudp <d_port> [optional_arguments]

  The <d_port> argument is the destination port for the packet.  This
  argument may either be a number or word, (e.g. ftp for port 21).  Valid
  [optional_arguments] are nothing or any of the following:

   -c        Set the header checksum to <hdr_cksum>.  Default: Correct value
             if -ps and -pd are specified, otherwise 0.
   -h        Print a help message.
   -i        Read the packet data from the file <input_file>.  If <input_file>
             is -, stdin will be used.
   -l        Set the header length to <length>.  Default: correct value
   -o        Print the packet data to <output_file>.  Default: stdout
   -pd       Set the pseudo-header destination address to <destination>, (in
             numerical or word form).
   -pl       Set the length of the header as stored in the pseudo-header to
             <length>.  Default: correct value
   -pp       Set the protocol as stored in the pseudo-header to <protocol>.
             Default: 17
   -ps       Set the source address of the packet as stored in the pseudo-
             to <source>.
   -pz       Set the value of the 8-bit 0 padding in the pseudo-header to
             <value>.  Defalt: 0
   -s        Set the source port to <src_port>.  Default: 0
   -v        Turn on verbose mode, (print packet data).

  For more information about the various header settings, you may read RFC
  768 which may be found at ftp://ds.internic.net/rfc/rfc768.txt.  If an
  argument is not specifically set, it defaults to a normal value.

D. makearp

  The makearp program generates an ARP packet.  You may supply several
  optional arguments to makearp in order to create a packet that matches
  your specifications.  The format of the makearp program is as follows:

  makearp [optional arguments]

  Valid [optional_arguments] are nothing or any of the following:

  [-ht <hw_type>] [-pt <prot_type] [-hl <len>] [-pl <len>] [-op <operation>]
  [-o <output_file>] [-v]

  -h   Print a usage summary.
  -hl  Set the length of the hardware address to <len>.  If not specified,
       this defaults to the correct value.
  -ht  Set the hardware type to <hardware_type>.  Currently, the only type
       supported by Spak is 802.3 frames, (which is a hardware type of 1).
  -pl  Set the length of protocol address.  If not specified, thos defaults to
       the correct value.
  -pt  Set the protocol type to <protocol_type>.  Currently, the only type
       supported by Spak is IP, (which is a protocol type of 2048).
  -o   Print the packet data to <output_file>.  If this is not specified, the
       packet will be printed to the screen (STDOUT).
  -op  Set the operation to <operation>.  Valid options are 1 for an ARP
       request, 2 for an ARP reply, 3 for a RARP request, and 4 for a RARP
       reply.
  -v   Turn on verbose mode, (print packet data).

  For a harware type of 1 (Ethernet), the following flags are valid:

  [-sm <src_mac>] [-dm <dst_mac>]

   -dm  Set the destination MAC address of the frame to <dest_mac>.  The
        <dest_mac> argument takes the form a:b:c:d:e:f where a through f are
        two digit hexadecimal numbers.
   -sm  Set the source MAC address of the frame to <src_mac>.  The <src_mac>
        argument takes the form a:b:c:d:e:f where a through f are two digit
        hexadecimal numbers.


  For a protocol type of 0x0800, (IP), the following flags are valid:

  [-si <source>] [-di <destination>]

   -di  Set the destination IP address to <destination>.  The <destination>
        argument should be a valid IP number or host name.
   -si  Set the source IP address to <source>.  The <source> argument should
        be a valid IP number or host name.

E. makeeth

  The makeeth program generates an Ethernet frame.  You may supply several
  optional arguments to makeeth in order to create a frame that matches
  your specifications.  The format of the makeeth program is as follows:

  makeeth [optional arguments]

  Valid [optional_arguments] are nothing or any of the following:

  [-s <src_mac>] [-d <dest_mac>] [-t <ether_type>] [<-v>] [-i <input_file>]
  [-o <out_file>]

  -d  Set the destination MAC address of the frame to <dest_mac>.  The
      <dest_mac> argument takes the form a:b:c:d:e:f where a through f are
      two digit hexadecimal numbers.
  -i  Read the frame data from the file <input_file>.  If <input_file> is -,
      then stdin is used.
  -o  Write the frame data to <out_file>.
  -s  Set the source MAC address of the frame to <src_mac>.  The <src_mac>
      argument takes the form a:b:c:d:e:f where a through f are two digit
      hexadecimal numbers.  If <src_mac> is -, then the source MAC address
      is guessed by the program.
  -t  Set the protocol of the frame data to <ether_type>.  The <ether_type>
      argument should be a hexidecimal number.
  -v  Turn on verbose mode, (print frame data).

F. sendpacket

  The sendpacket program reads a packet from a file and sends it to a socket.
  The destination address of the packet and the file to read the packet from
  must be given.  The format of the sendpacket program is as follows:

  sendpacket <dest> [input_file]

  The <dest> argument is the destination address for the packet.  This may
  either be a numerical address in the form xxx.xxx.xxx.xxx where the x's are
  a valid IP number, (e.g. 192.168.2.1), or a valid word address which can be
  resolved to an IP number, (e.g. lore.cs.purdue.edu).  The [input_file]
  argument is the file which contains the data to send.  If this is not given,
  data is read from stdin.

G. sendeth

  The sendeth program reads a frame from a file and sends it to a socket.
  The format of the sendpacket program is as follows:

  sendeth [optional arguments]

  Valid [optional_arguments] are nothing or any of the following:

  [-d <device>] [-i <input_file>] [-v | -vv]

  -d   Sets the device through which to send data out to <device>.
  -i   Read the frame data from the file <input_file>.  If <input_file> is -,
       or this argument is not given, stdin is used.
  -v   Verbose output.
  -vv  Very verbose output, (packet data is printed if possible).

H. option file format

  The option file is used by makeip and maketcp to add options to the headers.
  The format of this file is a series of 8-bit decimal numbers in ASCII
  format seperated by white space.  Comments can appear anywhere in the file
  and are denoted by the # character.  As soon as a # character is found,
  the rest of the line is ignored.  The option data MUST be in network byte
  order.  If AUTO_OPT_PAD is set in config.h, then the options will
  automatically be padded so they end on a 32-bit boundary.  For example, to
  set the MTU on a TCP packet to 1460, your options file would contain the
  following line:

  2 4 5 180

  A sample options file, named options, is contained in the main Spak
  release.

  If you have a better solution to the format of this file, please E-Mail
  xenon@xenos.net.


IV. Contact Information

All bug reports, comments, and questions about makeip, maketcp, makeudp,
sendpacket, and the other Spak files should be directed to Karyl F. Stein at
xenon@xenos.net.

All correspondence regarding files in the contrib directory should be sent to
the contact listed in those files or in the README in the contrib directory.

If you are submitting a bug report, please include as much information as
possible about the bug including the machine, OS, and compiler being used as
well as any error messages you receive.

If you would like to add something to the next Spak release be it a patch,
an improvement on an existing file, (not in the contrib directory), a Makefile
for a specific OS or hardware, or anything else, please contact the main Spak
contact listed above.


V. Notes

This is the second BETA release of this software.  The programs should be
mostly operational and not contain bugs, but they are not widely tested yet.
If you need to use these programs for anything besides personal education,
please wait until a stable version (1.0) is released.


VI. Acknowledgements

I would like to thank the following people or organizations for their
contributions to the Spak program:

* Purdue University for offering their resources for development and testing,
  and for giving me college credit to write parts of Spak.

* Jamal Hadi Salim for his testing, bug fixing, makeeth, and sendeth, makearp,
  and other programs and functions.

* Mahesh Tripunit for his initial work on spoofing MAC addresses under
  Solaris.

The following sources were used to create these programs:

* For a description of the protocols and the design of the packets:

  Comer, Douglas E., "Internetworking with TCP/IP," Prentice Hall, Englewood
       Cliffs, New Jersey, 1995.

* For a description of the IP header:

  ftp://ds.internic.net/rfc/rfc791.txt

* For a description of the TCP header:

  ftp://ds.internic.net/rfc/rfc793.txt

* For a description of the UDP header:

  ftp://ds.internic.net/rfc/rfc768.txt

* For further explanation of how to create and send packets:

  Claerhout, Brecht, "A short overview of IP spoofing: PART I."  This
  document is only available online, (as far as I know) as:
  http://main.succeed.net/~coder/spoofit/spoofit.html.

* The following sniffers were used for testing purposes:

  Sniffit (http://reptile.rug.ac.be/~coder/sniffit/sniffit.html) by Brecht
  Claerhout.

  Tcpdump (ftp://ftp.ee.lbl.gov/) by various authors.


VII. BUGS

The following bugs are known to exist in this version of Spak:

* The sendeth program does NOT work under BSDI, FreeBSD, SunOS, etc. systems.
  The next version should fix this.
* The setting of destination MAC and IP addresses, if not given, (i.e. the
  program is supposed to "guess" a correct value), is not fully implemented
  and does NOT work.
* There are some missing header declarations in Linux libc pre 5.4.33 which
  will give errors during compilation.  I lost the errors and need those to
  fix the source so it compiles cleanly, (and I don't want to install an old
  libc just to find out).  If you have problems, please let me know and I'll
  wrap in a fix for the next version.
