===============================================================================

    $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