=============================================================================== $Id: MIGRATION,v 1.2 2004/01/03 20:31:00 mike Exp $ LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman 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