Annotation of embedaddon/libnet/doc/MIGRATION, revision 1.1.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