libnet4r 0.1

data/libnet/doc/DESIGN_NOTES

@@ -0,0 +1,134 @@
+===============================================================================
+    $Id: DESIGN_NOTES,v 1.3 2004/01/17 07:51:19 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+
+    DESIGN NOTES
+
+    In order to remove most of the decisions a user had to make (how much
+    memory to allocate for a packet, where to build the packet headers, where
+    to do the checksums, how to inject the packet, etc) I decided to move ALL
+    of that logic into the library, behind the scenes.  To initialize 
+    things and get an initial libnet context, the applications programmer
+    calls:
+ 
+        libnet_t *l;
+        l = libnet_init(INJECTION_TYPE, PROTOCOL, DEVICE, ERRBUFFER);
+ 
+    where:
+
+    INJECTION_TYPE = LIBNET_RAW4 (ipv4 raw socket)
+                     LIBNET_RAW6 (ipv6 raw socket)
+                     LIBNET_LINK (link-layer socket)
+                     LIBNET_RAW4_ADV (advanced mode)
+                     LIBNET_RAW6_ADV (advanced mode)
+                     LIBNET_LINK_ADV (advanced mode)
+ 
+    PROTOCOL =       IP protocol to be used for the raw socket.  This is
+                     ignored for the link-layer, and almost always 
+                     IPPROTO_RAW for ipv4.
+ 
+    DEVICE =         The canoical name of the device, used only with the link
+                     layer stuff.  For ipv4 raw socket, you can leave this
+                     NULL.  If it's NULL with the link-layer, libnet will try
+                     to find a suitable device.
+ 
+    ERRBUFFER =      Until we have our libnet context l, this is where
+                     errors will be.
+ 
+    Inside of this newly created context we have a ton of stuff including a
+    file descriptor for the packet device the injection type, the device name
+    (if applicable) a pointer to the libnet protocol block structure and some
+    other ancillary data.
+ 
+    Additionally, we will soon be supporting context manipulation functions
+    that will allow the user to set certain flags inside the context.  This
+    interface will be akin to libnet_toggle_checksum() for those of you who
+    care.
+
+    When a packet is first constructed, the protocol block (pblock) stuff comes
+    into play.  On the outside, to an applications programmer, a packet is
+    constructed more or less like normal (with a few notable exceptions):
+ 
+        libnet_ptag_t ip_tag;
+        ip_tag = libnet_build_ipv4(
+                        LIBNET_UDP_H,
+                        0,
+                        242,
+                        0,
+                        64,
+                        IPPROTO_UDP,
+                        0,              /* NEW: checksum */
+                        src_ip,
+                        dst_ip,
+                        NULL,
+                        0,
+                        l,              /* NEW: libnet context */
+                        0               /* NEW: libnet ptag */
+                        );
+ 
+    The checksum allows an applications programmer to decide if he wants to
+    specify his own random value (useful in NIDS fooling) or precompute the
+    sum elsewhere, or leave it zero and by default libnet will take care of it
+    (although this is over-ridable).  The libnet context is the opague
+    pointer we allocated earlier and will show up in just about every libnet
+    function call from here on out.  The libnet ptag is a way to reference an
+    ALREADY BUILT protocol block.  This is necessary if you want to change 
+    some values of a header inside of a packet injection loop.
+ 
+    So, when you call a build function, internally, it's a completely new
+    system.  If the item you're constructing is NEW, a new pblock will be
+    allocated and linked onto the end of the list.  It may be helpful to think
+    of this as a "protocol stack" because you MUST build your packets IN 
+    ORDER, from the top of the protocol stack on down (i.e.: tcp -> ip ->
+    ethernet).  Once you build a new protocol block, it's "pushed down on the
+    stack" and you move on to the next.  However, this analogy breaks down 
+    because you can modify any one of these items and when they're assembled
+    for the final packet, libnet starts at the head of the list.  It may be
+    MORE helpful to think of the pblock chain as a doubly linked FIFO 
+    queue, because that's what it is. :)
+ 
+    For example:
+ 
+        libnet_ptag_t 1;
+        libnet_ptag_t 2;
+        libnet_ptag_t 3;
+ 
+        1 = libnet_build_data(blah, l, 0);
+        2 = libnet_build_tcp(blah, l, 0);
+        3 = libnet_build_ipv4(blah, l, 0);
+ 
+    Will result in:
+                          ----------      ----------      ----------
+    l->protocol_blocks--->|  data  |----->|  tcp   |----->|   ip   |
+                          | pblock |<-----| pblock |<-----| pblock |----|
+                        --| ptag: 1|      | ptag: 2|      | ptag: 3|    |
+                        | ----------      ----------      ----------    v
+                        |                                             -----
+                        |------------------------------------------->  ---
+                                                                        -
+ 
+    To access and change the ip header, an additional call to libnet_build_ipv4
+    with the ptag argument would be made:
+ 
+        libnet_build_ipv4(blah..., l, 3);
+ 
+    Note that the ptag DOES NOT CHANGE.  Once a pblock is built, its tag is
+    set in stone.
+ 
+    When it comes time to write the packet to the wire,
+    libnet_pblock_coalesce() is called to assemble the packet fragments.
+ 
+        1) Gather up all of the pblock sizes in order to allocate one
+           contiguous block of memory.
+        2) Copy over the packet fragments.
+        3) Check each pblock to see which items need checksums, then perform
+           that checksum over each portion (the entire packet is needed for
+           some checksums).
+ 
+    So that's a quick description of what's going on under the hood.  There's
+    more, but this should be enough to get you started.
+
+EOF

data/libnet/doc/MIGRATION

@@ -0,0 +1,172 @@
+===============================================================================
+    $Id: MIGRATION,v 1.2 2004/01/03 20:31:00 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+
+    MIGRATING YOUR CODE AND QUICKSTART
+
+    Using Libnet 1.1 you will find it MUCH simpler to build and write packets
+    than before.  Instead of the previous five steps (initialize memory,
+    initialize network, build packet, do checksums, write packet) there are
+    now only three steps (initialize library, build packet, write packet).  
+    In order to port your existing code, you will mainly be REMOVING 
+    function calls and variables.
+
+    1) Start with code removal:
+
+        - Remove all calls to libnet_init_packet() / packet malloc()ing and
+          all associated variables.
+        - Remove all calls to libnet_open_raw_sock() / libnet_open_link_layer()
+          and all associated variables.
+        - Remove all calls to libnet_do_checksum() and all associated
+          variables.
+
+    2) Continue with code addition and modification:
+
+        - You will need a single "libnet_t *l" which is your libnet file
+          context and an error buffer:
+
+            libnet_t *l
+            char errbuf[LIBNET_ERRBUF_SIZE];
+
+            l = libnet_init(
+                    LIBNET_RAW4,    /* or LIBNET_LINK or LIBNET_RAW6 */
+                    NULL,           /* or device if you using LIBNET_LINK */
+                    errbuf);
+
+        - The libnet_build functions are largely unchanged with a few
+          important differences:
+
+                1) Packets headers MUST be stacked IN ORDER.  This is
+                   intuitive and shouldn't be a problem.  Due to the way
+                   individual packet header memory is allocated and how 
+                   packet pieces are combined to build a packet they HAVE to 
+                   be built IN ORDER, from the high end of the protocol stack 
+                   on down.  ie: using the raw interface to build a NTP
+                   packet, you would:
+                        libnet_build_ntp(...)
+                        libnet_build_udp(...)
+                        libnet_build_ipv4(...)
+                   To build the same packet using the LINK interface on 
+                   top of ethernet you would:
+                        libnet_build_ntp(...)
+                        libnet_build_udp(...)
+                        libnet_build_ipv4(...)
+                        libnet_build_ethernet(...)
+                1a) There is the option now of using libnet_autobuild_ipv4()
+                    and libnet_autobuild_ethernet() which have fewer 
+                    arguments and smaller stack frames and are a bit more
+                    convenient.
+                2) The libnet_build functions return a libnet_ptag_t datatype
+                   on success or -1 on error.  This ptag is your
+                   "protocol/packet tag" so you can find this header again
+                   if you needed to modify it later on.  If you don't need
+                   to modify the packet header you can throw this value
+                   away.  You should definitely check for error now on
+                   your build functions.  Alot's going on down there fellas.
+                2a) NOTE that after packets are built, they may accessed
+                    independently of construction order via the saved ptag.
+                3) They NO LONGER ACCEPT BUFFER ARGUMENTS.  This is ALL
+                   done internally.  The last TWO arguments are the libnet
+                   context you created in your call to libnet_init() and
+                   an OPTIONAL ptag argument.  The ptag argument, if non-zero,
+                   specifes a packet tag to an ALREADY EXISTING packet header
+                   that will be OVERWRITTEN with the values specified in
+                   this libnet_build function call.  This is how you modify
+                   existing packet header pieces.  If this ptag is 0,
+                   a new protocol block is allocated and the packet is
+                   pushed down on the "protocol stack".
+                4) For the functions that build headers that have checksums
+                   these are NOW SPECIFIED AS AN ARGUMENT.  This adds more
+                   flexibility in how checksums are done (you can leave the
+                   field 0, put in a random value, precompute it on your own,
+                   or let the library do it).  By default, when you build
+                   a header, a "DO_CHECKSUM" flag will be set.  This means
+                   the library will compute the checksum for the header
+                   and possibly over the data before the packet is written.
+                   To clear this flag, there is a special macro you
+                   can call on the ptag refering to that header.
+                5) For the functions that have a length, it now specifies
+                   the TOTAL packet length from that protocol unit on down.
+                   For IP, that would be the entire packet length.  For
+                   TCP, that would be TCP and any possible data.
+                6) Nomenclature support for the eventual support of ipv6
+                   has been added.
+
+            libnet_ptag_t ip_tag;
+            libnet_ptag_t tcp_tag;
+
+            tcp_tag = libnet_build_tcp(
+                src_prt,            /* source TCP port */
+                dst_prt,            /* destination TCP port */
+                0xffff,             /* sequence number */
+                0x53,               /* acknowledgement number */
+                TH_SYN,             /* control flags */
+                1024,               /* window size */
+                0xd00d,             /* checksum */
+                0,                  /* urgent pointer */
+                LIBNET_TCP_H        /* TCP packet size */
+                NULL,               /* payload (none) */
+                0,                  /* payload length */
+                l,                  /* libnet context */
+                0);                 /* ptag */
+
+            ip_tag = libnet_build_ipv4(
+                LIBNET_TCP_H + LIBNET_IPV4_H,/* total packet len */
+                IPTOS_LOWDELAY,     /* tos */
+                ip_id,              /* IP ID */
+                0,                  /* IP Frag */
+                64,                 /* TTL */
+                IPPROTO_TCP,        /* protocol */
+                0,                  /* checksum */
+                src_ip,             /* source ip */
+                dst_ip,             /* dest ip */
+                NULL,               /* payload (none) */
+                0,                  /* payload size */
+                l,                  /* libnet context */
+                0);                 /* ptag */
+
+            Now, if you wanted to modify one of these headers in a loop
+            somewhere you would:
+
+            int i;
+            for (ip_tag, tcp_tag = LIBNET_PTAG_INITIALIZER, i = 0; i < 10; i++)
+            {
+                tcp_tag = libnet_build_tcp(++src_prt, ..., l, tcp_tag);
+                ip_tag = libnet_build_ipv4(..., ++ip_id, ..., l, ip_tag);
+                /* do something */
+            }
+            Since we are specifying a ptag for an existing header, the
+            build function will NOT create a new header and append it to
+            the list, it will FIND the one referenced by the ptag and UPDATE
+            it.  Since there is nothing new being created, order is NOT
+            important here.
+
+            Also note that it's perfectly fine to wrap the loop around the
+            initial building of the packets.  Since we're initializing the
+            ptags (to be zero), the first call into the builder functions
+            will allocate the memory and create the packet blocks.  These
+            calls will return ptag values.  The next calls will modify
+            these headers since the ptags will not be NULL.
+
+    - Finally, we write the packet.  Checksums are computed, by default
+      for each protocol header that requires one.  If the user specifies
+      a non-zero value, by default, this will be used INSTEAD of a
+      libnet computed checksum.  This behavior is overridable with:
+      
+    Turn ON checksums for header referenced by ptag:
+        libnet_toggle_checksum(l, ptag, 1)
+
+    Turn OFF checksums for header referenced by ptag:
+        libnet_toggle_checksum(l, ptag, 0)
+
+    Note, the packet header MUST exist before you can toggle this setting.
+
+        int c;
+        c = libnet_write(l);
+
+    Boom.  You're done.  Now go read the sample code.
+
+EOF

data/libnet/doc/PACKET_BUILDING

@@ -0,0 +1,161 @@
+===============================================================================
+    $Id: PACKET_BUILDING,v 1.2 2004/01/03 20:31:00 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+
+    ADDING A NEW PACKET BUILDER
+
+    Adding a new packet building module is usually pretty simple.  It depends
+    completely on the complexity of the protocol.  The following document
+    shows you how to add a packet builder for a simple protocol with a
+    static header size, but these concepts can be extended to a complex 
+    protocol also.
+
+    1) Start by defining your protocol header format in libnet-headers.h:
+
+    #define LIBNET_XXX_H 0xSIZE
+
+    struct XXX_hdr
+    {
+        u_char  field1;
+        u_short field2;
+        u_long  field3;
+    };
+
+    2) Add a pblock definition to libnet-structures.h (appened to the list):
+
+    #define LIBNET_PBLOCK_XXX_H            0xNUMBER 
+
+    3) Then work from the following template for libnet_build_XXX.c:
+
+#if (HAVE_CONFIG_H)
+#include "../include/config.h"
+#endif
+#include "../include/libnet.h"
+
+
+libnet_ptag_t
+libnet_build_XXX(u_char arg1, u_short arg2, u_long arg3, u_char *payload,
+            u_long payload_s, libnet_t *l, libnet_ptag_t ptag)
+{
+    /*
+     *  n is the size of the protocol unit.  This is usually the header size
+     *  plus the payload size.  This is also how many bytes are allocated on
+     *  the heap to hold this protocol unit.
+     */
+    u_long n;
+
+    /*
+     *  h is used inside the pblock structure to let libnet know how big
+     *  much data to checksum.  This is different for different protocols.
+     *  The IPv4 checksum covers the IP header only, while TCP and UDP
+     *  checksums cover header and data.
+     */
+    u_short h;
+
+    /*
+     *  p will be used to refer to the protocol block that will either be
+     *  allocated if the function's pt argument is 0, or located if ptag refers
+     *  to a previously created protocol unit.
+     */
+    libnet_pblock_t *p;
+
+    /*
+     *  XXX_hdr is the header structure that will be overlaid onto the
+     *  allocated memory by way of a memcpy.
+     */
+    struct libnet_XXX_hdr XXX_hdr;
+
+    /*
+     *  Here we sanity check to make sure we have a live l.
+     */
+    if (l == NULL)
+    { 
+        return (-1);
+    }
+
+    n = LIBNET_XXX_H + payload_s;
+    h = 0;          /* no checksum by default */
+
+    /*
+     *  Find the existing protocol block if a ptag is specified, or create
+     *  a new one.
+     */
+    p = libnet_pblock_probe(l, pt, n, LIBNET_PBLOCK_XXX_H);
+    if (p == NULL)
+    {
+        return (-1);
+    }
+
+    /*
+     *  Build your packet here.  Be sure to call appropriate endian conversion
+     *  routines.
+     */
+    XXX_hdr.field1 = arg1;
+    XXX_hdr.field2 = htons(arg2);
+    XXX_hdr.field3 = htonl(arg3);
+
+    /*
+     *  Appened the protocol unit to the list.
+     */
+    n = libnet_pblock_append(l, p, (u_char *)&XXX_hdr, LIBNET_XXX_H);
+    if (n == -1)
+    {
+        goto bad;
+    }
+
+    /*
+     *  Sanity check the payload arguments.
+     */
+    if ((payload && !payload_s) || (!payload && payload_s))
+    {
+        sprintf(l->err_buf, "%s(): payload inconsistency\n", __FUNCTION__);
+        goto bad;
+    }
+
+    /*
+     *  Append the payload to the list if it exists.
+     */
+    if (payload && payload_s)
+    {
+        n = libnet_pblock_append(l, p, payload, payload_s);
+        if (n == -1)
+        {
+            goto bad;
+        }
+    }
+
+    /*
+     *  If this packet header has a checksum field, you'll add this
+     *  and you'll have to edit libnet_checksum.c to add it to the switch
+     *  table.  You might have to define the protocol number too.
+     */
+    if (sum == 0 && l->injection_type != LIBNET_RAW4)
+    {
+        /*
+         *  If checksum is zero, by default libnet will compute a checksum
+         *  for the user.  The programmer can override this by calling
+         *  libnet_toggle_checksum(l, ptag, 1);
+         */
+        libnet_pblock_setflags(p, LIBNET_PBLOCK_DO_CHECKSUM);
+    }
+
+    /*
+     *  Update the protocol block's meta information and return the protocol
+     *  tag id of this pblock.  This tag will be used to locate the pblock
+     *  in order to modify the protocol header in subsequent calls.
+     */
+    return (pt ? pt : libnet_pblock_update(l, p, h, LIBNET_PBLOCK_XXX_H));
+bad:
+    libnet_pblock_delete(l, p);
+    return (-1);
+
+}
+    4) Add it to src/Makefile.am and then automake from the TLD.
+    5) Test the shit out of it.
+    6) Send it over to mike@infonexus.com.
+
+
+EOF

data/libnet/doc/PORTED

@@ -0,0 +1,45 @@
+===============================================================================
+    $Id: PORTED,v 1.2 2004/01/03 20:31:00 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+
+    1.1.0 PORTED OPERATING SYSTEMS
+ 
+    If you verify libnet building and running successfully (sample code works)
+    on a platform not listed here please send email to mike@infonexus.com.
+
+    - BSD/OS
+      4.x
+
+    - Cygwin
+      - requires winpcap (http://netgroup-serv.polito.it/winpcap) and pcap
+        header files copied to /usr/include/pcap/ and the library files to 
+        be copied to /usr/lib/
+
+    - FreeBSD
+      version?
+
+    - HPUX
+      11.0
+
+    - Linux
+      2.0.x
+      2.2.x
+      2.4.x
+
+    - OpenBSD
+      2.x
+      3.x
+
+    - OS/X
+      version?
+
+    - Solaris
+      2.x
+      7
+      8
+      9
+
+EOF

data/libnet/doc/RAWSOCKET_NON_SEQUITUR

@@ -0,0 +1,41 @@
+===============================================================================
+    $Id: RAWSOCKET_NON_SEQUITUR,v 1.2 2004/01/03 20:31:00 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+    Raw sockets are horribly non-standard across implementations.  Here is
+    an incomplete list of some of the differences (corrections welcomed):
+
+    Linux 2.2+:
+
+    IP fragmentation:       performed if packet is larger than MTU
+    IP checksum:            always filled in
+    IP total length:        always filled in
+    IP ID:                  filled in when zero
+    IP source address:      filled in when zero
+    IP destination address: filled in when zero
+    Max packet size before kernel complains: 1500 bytes
+
+    Solaris 2.6+:
+
+    IP fragmentation bits:  can't specify 
+    IP fragmentation:       performed if packet is larger than MTU
+    IP DF bit:              always set
+    IP checksum:            always filled in
+    Max packet size before kernel complains: ?
+
+    OpenBSD 2.8+:
+
+    IP fragmentation:       performed if packet is larger than MTU
+    Max packet size before kernel complains: 8192 bytes
+
+  Solaris,
+    for example, has terrible support for this packet interface.  Older OpenBSD
+    versions and recent FreeBSD versions have the BSD_BYTE_SWAP issue where
+    the ip_len and ip_frag fields need to be in little endian order.  Linux
+    apparently doesn't allow for the injection of broadcast IP datagrams.
+    Whenever complete control over the IP header is desired, use the link
+    layer API.
+
+EOF

data/libnet/doc/TODO

@@ -0,0 +1,96 @@
+===============================================================================
+    $Id: TODO,v 1.2 2004/01/03 20:31:00 mike Exp $
+    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
+                               http://www.packetfactory.net/libnet
+===============================================================================
+
+
+    1.1.x TODO LIST
+ 
+    * Update the man page!
+
+    - Add a programmer's man page detailing the pblock architecture.
+
+    - Fix plist memory leak.
+
+    - Fix IPv6.  According to RFC 2992:
+      "Another difference from IPv4 raw sockets is that complete packets
+      (that is, IPv6 packets with extension headers) cannot be read or
+      written using the IPv6 raw sockets API.  Instead, ancillary data
+      objects are used to transfer the extension headers, as described
+      later in this document.  Should an application need access to the
+      complete IPv6 packet, some other technique, such as the datalink
+      interfaces BPF or DLPI, must be used.
+
+      All fields in the IPv6 header that an application might want to
+      change (i.e., everything other than the version number) can be
+      modified using ancillary data and/or socket options by the
+      application for output.  All fields in a received IPv6 header (other
+      than the version number and Next Header fields) and all extension
+      headers are also made available to the application as ancillary data
+      on input.  Hence there is no need for a socket option similar to the
+      IPv4 IP_HDRINCL socket option."
+
+    - Add self-throttling logic to libnet_write()/libnet_init()?  Advanced
+      mode thing?
+
+    - Prune the include list in libnet.h.in.  Also add conditionals
+      around the headers we use for building the library, but not when
+      using it.
+
+    - Data marshalling API for unaligned structures (like STP).
+
+    - Make cisco ISL work.  The issue is that we have build our Ethernet
+      frame first, then encapsulate it inside of an ISL envelope.
+        - We have to compute CRCs for both Ethernet and ISL.
+
+    - Tune advanced interface functionality that allow the application
+      programmer to get inside libnet_t.
+
+    - Test HPUX 11 port.
+
+    - Test cywin32 port.
+
+    - Flesh out the advanced mode.
+
+    - Consider making a flag for "strict mode" where libnet will check
+      things like when you build an IP options list there is an IP
+      header preceding it (likewise for TCP)...  Other "smart" things
+      could happen in this mode too.  When in non-strict mode, libnet
+      will be less rigid but prone to user-error mode.
+
+    - If we have a problem building a header we might end up freeing it
+      creating a NULL entry on the list and preventing us from getting to
+      entries beyond it (to free or whatever).  Maybe we should mark it
+      bad or something and rely on the cleanup at the end to free it up?
+
+    - Fix checksum support for CDP
+
+    - Verify Checksuming:
+      Currently verified working on OpenBSD/Linux/Solaris:
+      - raw  IP/UDP         [with and without data]
+      - raw  IP/TCP         [with and without data]
+      - raw  IP/ICMP        [with and without data]
+      - raw  IP/OSPF
+        - hello packet      [with no auth data]
+        - hello packet      [with no auth data and LSA sub-header (LSA check = bad)]
+      - link IP/UDP         [with and without data]
+      - link IP/TCP         [with and without data]
+
+    - Update the rest of the libnet_link_* files for the new format, already
+      ported:
+      - bpf                 [works]
+      - linux packet socket [works]
+      - linux sock packet   [works]
+      - dlpi                [works]
+
+    - Port link stuff to use writev() in libnet_write() (sendto can't hang).
+
+    - Get IPsec code working.
+
+    - Add the following packet builders:
+      - SNMP
+
+    - Update __libnet_handle_dump to dump everything in l verbosely.
+
+EOF