diff options
-rw-r--r-- | README.md | 2 | ||||
-rw-r--r-- | debian/libnet1-doc.docs | 2 | ||||
-rw-r--r-- | doc/MIGRATION | 170 | ||||
-rw-r--r-- | doc/MIGRATION.md | 175 | ||||
-rw-r--r-- | doc/Makefile.am | 2 | ||||
-rw-r--r-- | doc/libnet.Pod | 2 |
6 files changed, 179 insertions, 174 deletions
@@ -28,7 +28,7 @@ Online documentation is available at https://codedocs.xyz/libnet/libnet/ > **NOTE:** Legacy code written for *libnet-1.0.x* is unfortunately > **incompatible** with *libnet-1.1.x* and later. -> See the [MIGRATION](doc/MIGRATION) guide for porting help. +> See the [Migration Guide](doc/MIGRATION.md) for porting help. Building diff --git a/debian/libnet1-doc.docs b/debian/libnet1-doc.docs index 840f83e..933f564 100644 --- a/debian/libnet1-doc.docs +++ b/debian/libnet1-doc.docs @@ -2,7 +2,7 @@ README doc/CONTRIB doc/TODO doc/DESIGN_NOTES -doc/MIGRATION +doc/MIGRATION.md doc/PACKET_BUILDING doc/PORTED doc/RAWSOCKET_NON_SEQUITUR diff --git a/doc/MIGRATION b/doc/MIGRATION deleted file mode 100644 index bfcc722..0000000 --- a/doc/MIGRATION +++ /dev/null @@ -1,170 +0,0 @@ -=============================================================================== - $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 TO LIBNET 1.1 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. diff --git a/doc/MIGRATION.md b/doc/MIGRATION.md new file mode 100644 index 0000000..9a1863f --- /dev/null +++ b/doc/MIGRATION.md @@ -0,0 +1,175 @@ +Migrating Your Code to libnet 1.1 or Later +========================================== +by Mike D. Schiffman <mike@infonexus.com> + +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. + + +Cleanup +------- + +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 + + +Code Changes +------------ + +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. + i.e.: 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(...) + + > **Note:** 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. A lot's going on + down there fellas. + + > **Note:** that after packets are built, they may be 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. + +### Example + + 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. + +### Writing the Packet + +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 possible to override 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. diff --git a/doc/Makefile.am b/doc/Makefile.am index 41e0224..8ed2ef1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ SUBDIRS = man -dist_doc_DATA = MIGRATION RAWSOCKET_NON_SEQUITUR +dist_doc_DATA = MIGRATION.md RAWSOCKET_NON_SEQUITUR EXTRA_DIST = fixmanpages.in libnet.Pod EXTRA_DIST += api-main.md api-head.html api-foot.html api-style.css DISTCLEANFILES = libnet.tag diff --git a/doc/libnet.Pod b/doc/libnet.Pod index 67643b9..cb80bbb 100644 --- a/doc/libnet.Pod +++ b/doc/libnet.Pod @@ -43,7 +43,7 @@ F<libnet/libnet-functions.h>, F<libnet/libnet-macros.h> or any of the others. =head1 BACKWARDS COMPATIBILITY Your old code (circa libnet B<1.0.x>) WILL NOT WORK with libnet> B<E<gt>=1.1.x>. -See B<doc/MIGRATION> for easy steps on porting your old code. +See B<doc/MIGRATION.md> for easy steps on porting your old code. =head1 SEE ALSO |