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

    $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