Annotation of embedaddon/libnet/doc/MIGRATION, revision 1.1
1.1 ! misho 1: ===============================================================================
! 2: $Id: MIGRATION,v 1.2 2004/01/03 20:31:00 mike 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
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to MIGRATION CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libnet / doc