Return to MIGRATION CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libnet / doc

libnet

    1: ===============================================================================
    2:     $Id: MIGRATION,v 1.1.1.1 2012/02/21 22:14:23 misho Exp $
    3:     LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
    4:                                http://www.packetfactory.net/libnet
    5: ===============================================================================
    6: 
    7: 
    8:     MIGRATING YOUR CODE AND QUICKSTART
    9: 
   10:     Using Libnet 1.1 you will find it MUCH simpler to build and write packets
   11:     than before.  Instead of the previous five steps (initialize memory,
   12:     initialize network, build packet, do checksums, write packet) there are
   13:     now only three steps (initialize library, build packet, write packet).  
   14:     In order to port your existing code, you will mainly be REMOVING 
   15:     function calls and variables.
   16: 
   17:     1) Start with code removal:
   18: 
   19:         - Remove all calls to libnet_init_packet() / packet malloc()ing and
   20:           all associated variables.
   21:         - Remove all calls to libnet_open_raw_sock() / libnet_open_link_layer()
   22:           and all associated variables.
   23:         - Remove all calls to libnet_do_checksum() and all associated
   24:           variables.
   25: 
   26:     2) Continue with code addition and modification:
   27: 
   28:         - You will need a single "libnet_t *l" which is your libnet file
   29:           context and an error buffer:
   30: 
   31:             libnet_t *l
   32:             char errbuf[LIBNET_ERRBUF_SIZE];
   33: 
   34:             l = libnet_init(
   35:                     LIBNET_RAW4,    /* or LIBNET_LINK or LIBNET_RAW6 */
   36:                     NULL,           /* or device if you using LIBNET_LINK */
   37:                     errbuf);
   38: 
   39:         - The libnet_build functions are largely unchanged with a few
   40:           important differences:
   41: 
   42:                 1) Packets headers MUST be stacked IN ORDER.  This is
   43:                    intuitive and shouldn't be a problem.  Due to the way
   44:                    individual packet header memory is allocated and how 
   45:                    packet pieces are combined to build a packet they HAVE to 
   46:                    be built IN ORDER, from the high end of the protocol stack 
   47:                    on down.  ie: using the raw interface to build a NTP
   48:                    packet, you would:
   49:                         libnet_build_ntp(...)
   50:                         libnet_build_udp(...)
   51:                         libnet_build_ipv4(...)
   52:                    To build the same packet using the LINK interface on 
   53:                    top of ethernet you would:
   54:                         libnet_build_ntp(...)
   55:                         libnet_build_udp(...)
   56:                         libnet_build_ipv4(...)
   57:                         libnet_build_ethernet(...)
   58:                 1a) There is the option now of using libnet_autobuild_ipv4()
   59:                     and libnet_autobuild_ethernet() which have fewer 
   60:                     arguments and smaller stack frames and are a bit more
   61:                     convenient.
   62:                 2) The libnet_build functions return a libnet_ptag_t datatype
   63:                    on success or -1 on error.  This ptag is your
   64:                    "protocol/packet tag" so you can find this header again
   65:                    if you needed to modify it later on.  If you don't need
   66:                    to modify the packet header you can throw this value
   67:                    away.  You should definitely check for error now on
   68:                    your build functions.  Alot's going on down there fellas.
   69:                 2a) NOTE that after packets are built, they may accessed
   70:                     independently of construction order via the saved ptag.
   71:                 3) They NO LONGER ACCEPT BUFFER ARGUMENTS.  This is ALL
   72:                    done internally.  The last TWO arguments are the libnet
   73:                    context you created in your call to libnet_init() and
   74:                    an OPTIONAL ptag argument.  The ptag argument, if non-zero,
   75:                    specifes a packet tag to an ALREADY EXISTING packet header
   76:                    that will be OVERWRITTEN with the values specified in
   77:                    this libnet_build function call.  This is how you modify
   78:                    existing packet header pieces.  If this ptag is 0,
   79:                    a new protocol block is allocated and the packet is
   80:                    pushed down on the "protocol stack".
   81:                 4) For the functions that build headers that have checksums
   82:                    these are NOW SPECIFIED AS AN ARGUMENT.  This adds more
   83:                    flexibility in how checksums are done (you can leave the
   84:                    field 0, put in a random value, precompute it on your own,
   85:                    or let the library do it).  By default, when you build
   86:                    a header, a "DO_CHECKSUM" flag will be set.  This means
   87:                    the library will compute the checksum for the header
   88:                    and possibly over the data before the packet is written.
   89:                    To clear this flag, there is a special macro you
   90:                    can call on the ptag refering to that header.
   91:                 5) For the functions that have a length, it now specifies
   92:                    the TOTAL packet length from that protocol unit on down.
   93:                    For IP, that would be the entire packet length.  For
   94:                    TCP, that would be TCP and any possible data.
   95:                 6) Nomenclature support for the eventual support of ipv6
   96:                    has been added.
   97: 
   98:             libnet_ptag_t ip_tag;
   99:             libnet_ptag_t tcp_tag;
  100: 
  101:             tcp_tag = libnet_build_tcp(
  102:                 src_prt,            /* source TCP port */
  103:                 dst_prt,            /* destination TCP port */
  104:                 0xffff,             /* sequence number */
  105:                 0x53,               /* acknowledgement number */
  106:                 TH_SYN,             /* control flags */
  107:                 1024,               /* window size */
  108:                 0xd00d,             /* checksum */
  109:                 0,                  /* urgent pointer */
  110:                 LIBNET_TCP_H        /* TCP packet size */
  111:                 NULL,               /* payload (none) */
  112:                 0,                  /* payload length */
  113:                 l,                  /* libnet context */
  114:                 0);                 /* ptag */
  115: 
  116:             ip_tag = libnet_build_ipv4(
  117:                 LIBNET_TCP_H + LIBNET_IPV4_H,/* total packet len */
  118:                 IPTOS_LOWDELAY,     /* tos */
  119:                 ip_id,              /* IP ID */
  120:                 0,                  /* IP Frag */
  121:                 64,                 /* TTL */
  122:                 IPPROTO_TCP,        /* protocol */
  123:                 0,                  /* checksum */
  124:                 src_ip,             /* source ip */
  125:                 dst_ip,             /* dest ip */
  126:                 NULL,               /* payload (none) */
  127:                 0,                  /* payload size */
  128:                 l,                  /* libnet context */
  129:                 0);                 /* ptag */
  130: 
  131:             Now, if you wanted to modify one of these headers in a loop
  132:             somewhere you would:
  133: 
  134:             int i;
  135:             for (ip_tag, tcp_tag = LIBNET_PTAG_INITIALIZER, i = 0; i < 10; i++)
  136:             {
  137:                 tcp_tag = libnet_build_tcp(++src_prt, ..., l, tcp_tag);
  138:                 ip_tag = libnet_build_ipv4(..., ++ip_id, ..., l, ip_tag);
  139:                 /* do something */
  140:             }
  141:             Since we are specifying a ptag for an existing header, the
  142:             build function will NOT create a new header and append it to
  143:             the list, it will FIND the one referenced by the ptag and UPDATE
  144:             it.  Since there is nothing new being created, order is NOT
  145:             important here.
  146: 
  147:             Also note that it's perfectly fine to wrap the loop around the
  148:             initial building of the packets.  Since we're initializing the
  149:             ptags (to be zero), the first call into the builder functions
  150:             will allocate the memory and create the packet blocks.  These
  151:             calls will return ptag values.  The next calls will modify
  152:             these headers since the ptags will not be NULL.
  153: 
  154:     - Finally, we write the packet.  Checksums are computed, by default
  155:       for each protocol header that requires one.  If the user specifies
  156:       a non-zero value, by default, this will be used INSTEAD of a
  157:       libnet computed checksum.  This behavior is overridable with:
  158:       
  159:     Turn ON checksums for header referenced by ptag:
  160:         libnet_toggle_checksum(l, ptag, 1)
  161: 
  162:     Turn OFF checksums for header referenced by ptag:
  163:         libnet_toggle_checksum(l, ptag, 0)
  164: 
  165:     Note, the packet header MUST exist before you can toggle this setting.
  166: 
  167:         int c;
  168:         c = libnet_write(l);
  169: 
  170:     Boom.  You're done.  Now go read the sample code.
  171: 
  172: EOF