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