forked from the-tcpdump-group/tcpdump-htdocs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpcap.html
732 lines (673 loc) · 31.1 KB
/
pcap.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
<!DOCTYPE html>
<!--
Created by : Luis MartinGarcia <http://www.aldabaknocking.com>
Original design : "Collaboration" by Free CSS Templates (later "TEMPLATED")
Original license : Creative Commons Attribution 2.5 License
-->
<html lang="en">
<!-- HEAD -->
<head>
<meta charset="utf-8">
<title>Programming with pcap | TCPDUMP & LIBPCAP</title>
<meta name="description" content="Web site of Tcpdump and Libpcap">
<link href="style.css" rel="stylesheet" type="text/css" media="screen">
<link href="images/T-32x32.png" rel="shortcut icon" type="image/png">
</head>
<!-- END OF HTML HEAD -->
<!-- BODY -->
<body>
<!-- TOP MENU -->
<div id="menu">
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="security.html">Security</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="manpages/">Man Pages</a></li>
<li><a href="ci.html">CI</a></li>
<li><a href="linktypes.html">Link-Layer Header Types</a></li>
<li><a href="bpfexam/">BPF Exam</a></li>
<li><a href="related.html">See Also</a></li>
<li><a href="old_releases.html">Old Releases</a></li>
</ul>
</div>
<!-- END OF TOP MENU -->
<!-- PAGE HEADER -->
<div id="splash">
<br><img src="images/logo.png" alt="">
</div>
<div id="logo">
<hr>
</div>
<!-- END OF PAGE HEADER -->
<!-- PAGE CONTENTS -->
<div id="page">
<div class="post">
<h1 class="title">Programming with pcap</h1>
<div class="entry">
Tim Carstens<br>
timcarst <b>at</b> yahoo <b>dot</b> com<br>
Further editing and development by Guy Harris<br>
guy <b>at</b> alum <b>dot</b> mit <b>dot</b> edu
<p>Ok, let's begin by defining who this document is
written for. Obviously, some basic knowledge of C is required, unless you
only wish to know the basic theory. You do not need to be a code ninja;
for the areas likely to be understood only by more experienced programmers, I'll
be sure to describe concepts in greater detail. Additionally, some basic
understanding of networking might help, given that this is a packet sniffer and
all. All of the code examples presented here have been tested on FreeBSD
4.3 with a default kernel.
</div>
</div>
<div class="post">
<h2 class="title">Getting Started: The format of a pcap application</h2>
<div class="entry">
<p>The first thing to understand is the
general layout of a pcap sniffer. The flow of code is as follows:
<ol>
<li>We begin by determining which interface we want to sniff
on. In Linux this may be something like <code>eth0</code>, in BSD it may
be <code>xl1</code>, etc.
We can either define this device in a string, or we can ask pcap to
provide us with the name of an interface that will do the job.
<li>Initialize pcap. This is where we actually tell pcap
what device we are sniffing on. We can, if we want to, sniff on multiple
devices. How do we differentiate between them? Using file handles.
Just like opening a file for reading or writing, we must name our sniffing
"session" so we can tell it apart from other such sessions.
<li>In the event that we only want to sniff specific traffic (e.g.:
only TCP/IP packets, only packets going to port 23, etc) we must create a rule
set, "compile" it, and apply it. This is a three phase process, all of
which is closely related. The rule set is kept in a string, and is
converted into a format that pcap can read (hence compiling it). The
compilation is actually just done by calling a function within our program; it
does not involve the use of an external application. Then we tell pcap
to apply it to whichever session we wish for it to filter.
<li>Finally, we tell pcap to enter it's primary execution loop.
In this state, pcap waits until it has received however many packets we want
it to. Every time it gets a new packet in, it calls another function
that we have already defined. The function that it calls can do anything
we want; it can dissect the packet and print it to the user, it can save it in
a file, or it can do nothing at all.
<li>After our sniffing needs are satisfied, we close our
session and are complete.
</ol>
<p>This is actually a very
simple process. Five steps total, one of which is optional (step 3,
in case you were wondering). Let's take a look at each of the steps and how
to implement them.
</div>
</div>
<div class="post">
<h2 class="title">Setting the device</h2>
<div class="entry">
<p>This is terribly simple. There are two techniques
for setting the device that we wish to sniff on.
<p>The first is that we can
simply have the user tell us. Consider the following program:
<pre>
#include <stdio.h>
#include <pcap.h>
int main(int argc, char *argv[])
{
char *dev = argv[1];
printf("Device: %s\n", dev);
return(0);
}
</pre>
<p>The user specifies the device by passing the name of it as the first argument to
the program. Now the string <code>dev</code> holds the name of the interface that we
will sniff on in a format that pcap can understand (assuming, of course, the
user gave us a real interface).
<p>The other technique is
equally simple. Look at this program:
<pre>
#include <stdio.h>
#include <pcap.h>
int main(int argc, char *argv[])
{
char *dev, errbuf[PCAP_ERRBUF_SIZE];
dev = pcap_lookupdev(errbuf);
if (dev == NULL) {
fprintf(stderr, "Couldn't find default device: %s\n", errbuf);
return(2);
}
printf("Device: %s\n", dev);
return(0);
}
</pre>
<p>In this case, pcap just sets the device on its own. "But wait, Tim," you
say. "What is the deal with the <code>errbuf</code> string?" Most of the pcap
commands allow us to pass them a string as an argument. The purpose of
this string? In the event that the command fails, it will populate the
string with a description of the error. In this case, if
<a href="manpages/pcap_lookupdev.3pcap.html"><b>pcap_lookupdev</b></a>(3PCAP)
fails, it will store an error message in <code>errbuf</code>. Nifty, isn't it?
And that's how we set our device.
</div>
</div>
<div class="post">
<h2 class="title">Opening the device for sniffing</h2>
<div class="entry">
<p>The task of creating a sniffing session is really quite
simple. For this, we use
<a href="manpages/pcap_open_live.3pcap.html"><b>pcap_open_live</b></a>(3PCAP).
The prototype of this function is as follows:
<pre>
pcap_t *pcap_open_live(char *device, int snaplen, int promisc, int to_ms,
char *ebuf)
</pre>
<p>The first argument is the device that we specified in the previous
section. <code>snaplen</code> is an integer which defines the maximum number of
bytes to be captured by pcap. <code>promisc</code>, when set to true, brings the
interface into promiscuous mode (however, even if it is set to false, it
is possible under specific cases for the interface to be in promiscuous
mode, anyway). <code>to_ms</code> is the read time out in milliseconds (a value of 0
means no time out; on at least some platforms, this means that you may
wait until a sufficient number of packets arrive before seeing any
packets, so you should use a non-zero timeout). Lastly, <code>ebuf</code> is a
string we can store any error messages within (as we did above with
<code>errbuf</code>). The function returns our session handler.
<p>To demonstrate, consider this code snippet:
<pre>
#include <pcap.h>
...
pcap_t *handle;
handle = pcap_open_live(dev, BUFSIZ, 1, 1000, errbuf);
if (handle == NULL) {
fprintf(stderr, "Couldn't open device %s: %s\n", dev, errbuf);
return(2);
}
</pre>
<p>This code fragment opens the device stored in the string <code>dev</code>, tells it to
read however many bytes are specified in <code>BUFSIZ</code> (which is usually defined in
<code>/usr/include/stdio.h</code> via <code>pcap.h</code>).
We are telling it to put the device into promiscuous mode, to sniff until an
error occurs, and if there is an error, store it in the string <code>errbuf</code>; it
uses that string to print an error message.
<p>A note about promiscuous vs. non-promiscuous sniffing: The two
techniques are very different in style. In standard, non-promiscuous
sniffing, a host is sniffing only traffic that is directly related to
it. Only traffic to, from, or routed through the host will be picked up
by the sniffer. Promiscuous mode, on the other hand, sniffs all traffic
on the wire. In a non-switched environment, this could be all network
traffic. The obvious advantage to this is that it provides more packets
for sniffing, which may or may not be helpful depending on the reason
you are sniffing the network. However, there are regressions.
Promiscuous mode sniffing is detectable; a host can test with strong
reliability to determine if another host is doing promiscuous sniffing.
Second, it only works in a non-switched environment (such as a hub, or a
switch that is being ARP flooded). Third, on high traffic networks, the
host can become quite taxed for system resources.
<p>Not all devices provide the same type of link-layer headers in the
packets you read. Ethernet devices, and some non-Ethernet devices,
might provide Ethernet headers, but other device types, such as loopback
devices in BSD and OS X, PPP interfaces, and Wi-Fi interfaces when
capturing in monitor mode, don't.
<p>You need to determine the type of link-layer headers the device
provides, and use that type when processing the packet contents. The
<a href="manpages/pcap_datalink.3pcap.html"><b>pcap_datalink</b></a>(3PCAP)
routine returns a value indicating the type of
link-layer headers; see <a href="linktypes.html">the list of link-layer
header type values</a>. The values it returns are the <code>DLT_</code>
values in that list.
<p>If your program doesn't support the link-layer header type provided
by the device, it has to give up; this would be done with code such as
<pre>
if (pcap_datalink(handle) != DLT_EN10MB) {
fprintf(stderr, "Device %s doesn't provide Ethernet headers - not supported\n", dev);
return(2);
}
</pre>
<p>which fails if the device doesn't supply Ethernet headers. This
would be appropriate for the code below, as it assumes Ethernet headers.
</div>
</div>
<div class="post">
<h2 class="title">Filtering traffic</h2>
<div class="entry">
<p>Often times our sniffer may only be interested in specific
traffic. For instance, there may be times when all we want is to sniff on
port 23 (telnet) in search of passwords. Or perhaps we want to hijack a
file being sent over port 21 (FTP). Maybe we only want DNS traffic (port
53 UDP). Whatever the case, rarely do we just want to blindly sniff <i>all</i>
network traffic. Enter
<a href="manpages/pcap_compile.3pcap.html"><b>pcap_compile</b></a>(3PCAP)
and
<a href="manpages/pcap_setfilter.3pcap.html"><b>pcap_setfilter</b></a>(3PCAP).
<p>The process is quite simple. After we have already called <b>pcap_open_live</b>()
and have a working sniffing session, we can apply our
filter. Why not just use our own <code>if</code>/<code>else if</code> statements? Two reasons.
First, pcap's filter is far more efficient, because it does it directly
with the BPF filter; we eliminate numerous steps by having the BPF
driver do it directly. Second, this is a <em>lot</em> easier :)
<p>Before applying our filter, we must "compile" it. The
filter expression is kept in a regular string (<code>char</code> array). The syntax
is documented quite well in
<span class=manref><a href="manpages/pcap-filter.7.html"><b>pcap-filter</b></a>(7)</span>;
I leave you to
read it on your own. However, we will use simple test expressions, so
perhaps you are sharp enough to figure it out from my
examples.
<p>To compile the program we call <b>pcap_compile</b>(). The prototype defines it as:
<pre>
int pcap_compile(pcap_t *p, struct bpf_program *fp, char *str, int optimize,
bpf_u_int32 netmask)
</pre>
<p>The first argument is our session handle (<code>pcap_t *handle</code> in our
previous example). Following that is a reference to the place we will
store the compiled version of our filter. Then comes the expression
itself, in regular string format. Next is an integer that decides if
the expression should be "optimized" or not (0 is false, 1 is
true—standard stuff). Finally, we must specify the network mask of the
network the filter applies to. The function returns -1 on failure; all
other values imply success.
<p>After the expression has been compiled, it is time to apply
it. Enter <b>pcap_setfilter</b>().
Following our format of explaining pcap, we shall look at the prototype:
<pre>
int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
</pre>
<p>This is very straightforward. The first argument is our session handler,
the second is a reference to the compiled version of the expression (presumably
the same variable as the second argument to <b>pcap_compile</b>()).
<p>Perhaps another code sample would help to better understand:
<pre>
#include <pcap.h>
...
pcap_t *handle; /* Session handle */
char dev[] = "rl0"; /* Device to sniff on */
char errbuf[PCAP_ERRBUF_SIZE]; /* Error string */
struct bpf_program fp; /* The compiled filter expression */
char filter_exp[] = "port 23"; /* The filter expression */
bpf_u_int32 mask; /* The netmask of our sniffing device */
bpf_u_int32 net; /* The IP of our sniffing device */
if (pcap_lookupnet(dev, &net, &mask, errbuf) == -1) {
fprintf(stderr, "Can't get netmask for device %s\n", dev);
net = 0;
mask = 0;
}
handle = pcap_open_live(dev, BUFSIZ, 1, 1000, errbuf);
if (handle == NULL) {
fprintf(stderr, "Couldn't open device %s: %s\n", dev, errbuf);
return(2);
}
if (pcap_compile(handle, &fp, filter_exp, 0, net) == -1) {
fprintf(stderr, "Couldn't parse filter %s: %s\n", filter_exp, pcap_geterr(handle));
return(2);
}
if (pcap_setfilter(handle, &fp) == -1) {
fprintf(stderr, "Couldn't install filter %s: %s\n", filter_exp, pcap_geterr(handle));
return(2);
}
</pre>
<p>This program preps the sniffer to sniff all traffic coming from or going to port
23, in promiscuous mode, on the device <code>rl0</code>.
<p>You may notice that the previous example contains a function that we
have not yet discussed.
<a href="manpages/pcap_lookupnet.3pcap.html"><b>pcap_lookupnet</b></a>(3PCAP)
is a function that, given the
name of a device, returns one of its IPv4 network numbers and
corresponding network mask (the network number is the IPv4 address ANDed
with the network mask, so it contains only the network part of the
address). This was essential because we needed to know the network mask
in order to apply the filter. This function is described in the
Miscellaneous section at the end of the document.
<p>It has been my experience that this filter does not work across all
operating systems. In my test environment, I found that OpenBSD 2.9
with a default kernel does support this type of filter, but FreeBSD 4.3
with a default kernel does not. Your mileage may vary.
</div>
</div>
<div class="post">
<h2 class="title">The actual sniffing</h2>
<div class="entry">
<p>At this point we have learned how to define a device,
prepare it for sniffing, and apply filters about what we should and should not
sniff for. Now it is time to actually capture some packets.
<p>There are two main techniques for capturing packets. We can either
capture a single packet at a time, or we can enter a loop that waits for
<i>n</i> number of packets to be sniffed before being done. We will
begin by looking at how to capture a single packet, then look at methods
of using loops. For this we use
<a href="manpages/pcap_next_ex.3pcap.html"><b>pcap_next</b></a>(3PCAP).
<p>The prototype is fairly simple:
<pre>
u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
</pre>
<p>The first argument is our session handler. The second argument is a
pointer to a structure that holds general information about the packet,
specifically the time in which it was sniffed, the length of this packet, and
the length of this specific portion (in case it is fragmented, for example).
<b>pcap_next</b>()
returns a <code>u_char</code> pointer to the packet that is described by this
structure. We'll discuss the technique for actually reading the packet
itself later.
<p>Here is a simple demonstration of using <b>pcap_next</b>() to sniff a packet.
<pre>
#include <pcap.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
pcap_t *handle; /* Session handle */
char *dev; /* The device to sniff on */
char errbuf[PCAP_ERRBUF_SIZE]; /* Error string */
struct bpf_program fp; /* The compiled filter */
char filter_exp[] = "port 23"; /* The filter expression */
bpf_u_int32 mask; /* Our netmask */
bpf_u_int32 net; /* Our IP */
struct pcap_pkthdr header; /* The header that pcap gives us */
const u_char *packet; /* The actual packet */
/* Define the device */
dev = pcap_lookupdev(errbuf);
if (dev == NULL) {
fprintf(stderr, "Couldn't find default device: %s\n", errbuf);
return(2);
}
/* Find the properties for the device */
if (pcap_lookupnet(dev, &net, &mask, errbuf) == -1) {
fprintf(stderr, "Couldn't get netmask for device %s: %s\n", dev, errbuf);
net = 0;
mask = 0;
}
/* Open the session in promiscuous mode */
handle = pcap_open_live(dev, BUFSIZ, 1, 1000, errbuf);
if (handle == NULL) {
fprintf(stderr, "Couldn't open device %s: %s\n", dev, errbuf);
return(2);
}
/* Compile and apply the filter */
if (pcap_compile(handle, &fp, filter_exp, 0, net) == -1) {
fprintf(stderr, "Couldn't parse filter %s: %s\n", filter_exp, pcap_geterr(handle));
return(2);
}
if (pcap_setfilter(handle, &fp) == -1) {
fprintf(stderr, "Couldn't install filter %s: %s\n", filter_exp, pcap_geterr(handle));
return(2);
}
/* Grab a packet */
packet = pcap_next(handle, &header);
/* Print its length */
printf("Jacked a packet with length of [%d]\n", header.len);
/* And close the session */
pcap_close(handle);
return(0);
}
</pre>
<p>This application sniffs on whatever device is returned by <b>pcap_lookupdev</b>()
by
putting it into promiscuous mode. It finds the first packet to come across
port 23 (telnet) and tells the user the size of the packet (in bytes).
Again, this program includes a new call,
<a href="manpages/pcap_close.3pcap.html"><b>pcap_close</b></a>(3PCAP),
which we will discuss
later (although it really is quite self explanatory).
<p>The other technique we can use is more complicated, and
probably more useful. Few sniffers (if any) actually use <b>pcap_next</b>().
More often than not, they use
<a href="manpages/pcap_loop.3pcap.html"><b>pcap_loop</b></a>(3PCAP)
or
<a href="manpages/pcap_loop.3pcap.html"><b>pcap_dispatch</b></a>(3PCAP)
(which then themselves use <b>pcap_loop</b>()).
To understand the use of these two functions,
you must understand the idea of a callback function.
<p>Callback functions are not anything new, and are very common in many
APIs. The concept behind a callback function is fairly simple.
Suppose I have a program that is waiting for an event of some sort. For
the purpose of this example, let's pretend that my program wants a user
to press a key on the keyboard. Every time they press a key, I want to
call a function which then will determine that to do. The function I am
utilizing is a callback function. Every time the user presses a key, my
program will call the callback function. Callbacks are used in pcap,
but instead of being called when a user presses a key, they are called
when pcap sniffs a packet. The two functions that one can use to define
their callback are <b>pcap_loop</b>() and <b>pcap_dispatch</b>(),
these are very similar in their usage of callbacks. Both of
them call a callback function every time a packet is sniffed that meets
our filter requirements (if any filter exists, of course. If not, then
<i>all</i> packets that are sniffed are sent to the callback.)
<p>The prototype for <b>pcap_loop</b>() is below:
<pre>
int pcap_loop(pcap_t *p, int cnt, pcap_handler callback, u_char *user)
</pre>
<p>The first argument is our session handle. Following that is an
integer that tells <b>pcap_loop</b>() how many packets it should sniff for
before returning (a negative value means it should sniff until an error
occurs). The third argument is the name of the callback function (just
its identifier, no parentheses). The last argument is useful in some
applications, but many times is simply set as <code>NULL</code>. Suppose we have
arguments of our own that we wish to send to our callback function, in
addition to the arguments that <b>pcap_loop</b>() sends. This is where we do
it. Obviously, you must typecast to a <code>u_char</code> pointer to ensure the
results make it there correctly; as we will see later, pcap makes use of
some very interesting means of passing information in the form of a
<code>u_char</code> pointer. After we show an example of how pcap does it, it should
be obvious how to do it here. If not, consult your local C reference
text, as an explanation of pointers is beyond the scope of this
document. <b>pcap_dispatch</b>() is almost identical in usage. The only
difference between these two functions is that <b>pcap_dispatch</b>()
will only process the first batch of packets that it receives from the system, while
<b>pcap_loop</b>() will continue processing
packets or batches of packets until the count of packets runs out. For
a more in depth discussion of their differences, see the man page.
<p>Before we can provide an example of using <b>pcap_loop</b>(),
we must examine the format of our callback function. We
cannot arbitrarily define our callback's prototype; otherwise, <b>pcap_loop</b>()
would not know how to use the function. So we use this format as the prototype
for our callback function:
<pre>
void got_packet(u_char *args, const struct pcap_pkthdr *header,
const u_char *packet);
</pre>
<p>Let's examine this in more detail. First, you'll notice that the function
has a <code>void</code> return type. This is logical, because <b>pcap_loop</b>()
wouldn't know how to handle a return value anyway. The first argument
corresponds to the last argument of <b>pcap_loop</b>().
Whatever value is passed as the last argument to <b>pcap_loop</b>()
is passed to the first argument of our callback function
every time the function is called. The second argument is the pcap header,
which contains information about when the packet was sniffed, how large it is,
etc. The <code>pcap_pkthdr</code> structure is defined in <code>pcap.h</code> as:
<pre>
struct pcap_pkthdr {
struct timeval ts; /* time stamp */
bpf_u_int32 caplen; /* length of portion present */
bpf_u_int32 len; /* length this packet (off wire) */
};
</pre>
<p>These values should be fairly self explanatory. The last argument is
the most interesting of them all, and the most confusing to the average
novice pcap programmer. It is another pointer to a <code>u_char</code>, and it
points to the first byte of a chunk of data containing the entire
packet, as sniffed by <b>pcap_loop</b>().
<p>But how do you make use of this variable (named <code>packet</code> in
our prototype)? A packet contains many attributes, so as you can
imagine, it is not really a string, but actually a collection of
structures (for instance, a TCP/IP packet would have an Ethernet header,
an IP header, a TCP header, and lastly, the packet's payload). This
<code>u_char</code> pointer points to the serialized version of these structures. To
make any use of it, we must do some interesting typecasting.
<p>First, we must have the actual structures
defined before we can typecast to them. The following are the structure
definitions that I use to describe a TCP/IP packet over Ethernet.
<pre>
/* Ethernet addresses are 6 bytes */
#define ETHER_ADDR_LEN 6
/* Ethernet header */
struct sniff_ethernet {
u_char ether_dhost[ETHER_ADDR_LEN]; /* Destination host address */
u_char ether_shost[ETHER_ADDR_LEN]; /* Source host address */
u_short ether_type; /* IP? ARP? RARP? etc */
};
/* IP header */
struct sniff_ip {
u_char ip_vhl; /* version << 4 | header length >> 2 */
u_char ip_tos; /* type of service */
u_short ip_len; /* total length */
u_short ip_id; /* identification */
u_short ip_off; /* fragment offset field */
#define IP_RF 0x8000 /* reserved fragment flag */
#define IP_DF 0x4000 /* don't fragment flag */
#define IP_MF 0x2000 /* more fragments flag */
#define IP_OFFMASK 0x1fff /* mask for fragmenting bits */
u_char ip_ttl; /* time to live */
u_char ip_p; /* protocol */
u_short ip_sum; /* checksum */
struct in_addr ip_src,ip_dst; /* source and dest address */
};
#define IP_HL(ip) (((ip)->ip_vhl) & 0x0f)
#define IP_V(ip) (((ip)->ip_vhl) >> 4)
/* TCP header */
typedef u_int tcp_seq;
struct sniff_tcp {
u_short th_sport; /* source port */
u_short th_dport; /* destination port */
tcp_seq th_seq; /* sequence number */
tcp_seq th_ack; /* acknowledgement number */
u_char th_offx2; /* data offset, rsvd */
#define TH_OFF(th) (((th)->th_offx2 & 0xf0) > 4)
u_char th_flags;
#define TH_FIN 0x01
#define TH_SYN 0x02
#define TH_RST 0x04
#define TH_PUSH 0x08
#define TH_ACK 0x10
#define TH_URG 0x20
#define TH_ECE 0x40
#define TH_CWR 0x80
#define TH_FLAGS (TH_FIN|TH_SYN|TH_RST|TH_ACK|TH_URG|TH_ECE|TH_CWR)
u_short th_win; /* window */
u_short th_sum; /* checksum */
u_short th_urp; /* urgent pointer */
};
</pre>
<p>So how does all of this relate to pcap and our mysterious <code>u_char</code>
pointer? Well, those structures define the headers that appear in the
data for the packet. So how can we break it apart? Be prepared to
witness one of the most practical uses of pointers (for all of those new
C programmers who insist that pointers are useless, I smite you).
<p>Again, we're going to assume that we are dealing with a TCP/IP packet
over Ethernet. This same technique applies to any packet; the only
difference is the structure types that you actually use. So let's begin
by defining the variables and compile-time definitions we will need to
deconstruct the packet data.
<p><pre>
/* ethernet headers are always exactly 14 bytes */
#define SIZE_ETHERNET 14
const struct sniff_ethernet *ethernet; /* The ethernet header */
const struct sniff_ip *ip; /* The IP header */
const struct sniff_tcp *tcp; /* The TCP header */
const char *payload; /* Packet payload */
u_int size_ip;
u_int size_tcp;
</pre><p>
<p>And now we do our magical typecasting:
<pre>
ethernet = (struct sniff_ethernet*)(packet);
ip = (struct sniff_ip*)(packet + SIZE_ETHERNET);
size_ip = IP_HL(ip)*4;
if (size_ip < 20) {
printf(" * Invalid IP header length: %u bytes\n", size_ip);
return;
}
tcp = (struct sniff_tcp*)(packet + SIZE_ETHERNET + size_ip);
size_tcp = TH_OFF(tcp)*4;
if (size_tcp < 20) {
printf(" * Invalid TCP header length: %u bytes\n", size_tcp);
return;
}
payload = (u_char *)(packet + SIZE_ETHERNET + size_ip + size_tcp);
</pre>
<p>How does this work? Consider the layout of the packet data in memory.
The <code>u_char</code> pointer is really just a variable containing an address in
memory. That's what a pointer is; it points to a location in memory.
<p>For the sake of simplicity, we'll say that the address this pointer is
set to is the value X. Well, if our three structures are just sitting
in line, the first of them (<code>sniff_ethernet</code>) being located in memory at
the address X, then we can easily find the address of the structure
after it; that address is X plus the length of the Ethernet header,
which is 14, or <code>SIZE_ETHERNET</code>.
<p>Similarly if we have the address of that header, the address of the
structure after it is the address of that header plus the length of that
header. The IP header, unlike the Ethernet header, does
<strong>not</strong> have a fixed length; its length is given, as a
count of 4-byte words, by the header length field of the IP header. As
it's a count of 4-byte words, it must be multiplied by 4 to give the
size in bytes. The minimum length of that header is 20 bytes.
<p>The TCP header also has a variable length; its length is given, as a
number of 4-byte words, by the "data offset" field of the TCP header,
and its minimum length is also 20 bytes.
<p>So let's make a chart:
<p>
<table class=byte_array>
<tr>
<th>Variable</th>
<th>Location (in bytes)</th>
</tr>
<tr>
<td><code>sniff_ethernet</code></td>
<td>X</td>
</tr>
<tr>
<td><code>sniff_ip</code></td>
<td>X + <code>SIZE_ETHERNET</code></td>
</tr>
<tr>
<td><code>sniff_tcp</code></td>
<td>X + <code>SIZE_ETHERNET</code> + {IP header length}</td>
</tr>
<tr>
<td><code>payload</code></td>
<td>X + <code>SIZE_ETHERNET</code> + {IP header length} + {TCP header length}</td>
</tr>
</table>
<p>The <code>sniff_ethernet</code> structure, being the first in line, is simply at
location X. <code>sniff_ip</code>, who follows directly after <code>sniff_ethernet</code>, is at
the location X, plus however much space the Ethernet header consumes (14
bytes, or <code>SIZE_ETHERNET</code>). <code>sniff_tcp</code> is after both <code>sniff_ip</code> and
<code>sniff_ethernet</code>, so it is location at X plus the sizes of the Ethernet
and IP headers (14 bytes, and 4 times the IP header length,
respectively). Lastly, the payload (which doesn't have a single
structure corresponding to it, as its contents depends on the protocol
being used atop TCP) is located after all of them.
<p>So at this point, we know how to set our
callback function, call it, and find out the attributes about the packet that
has been sniffed. It's now the time you have been waiting for: writing a
useful packet sniffer. Because of the length of the source code, I'm not
going to include it in the body of this document. Simply download
<a href="other/sniffex.c"><code>sniffex.c</code></a> and try it out.
</div>
</div>
<div class="post">
<h2 class="title">Wrapping Up</h2>
<div class="entry">
<p>At this point you should be able to write a
sniffer using pcap. You have learned the basic concepts behind opening a
pcap session, learning general attributes about it, sniffing packets, applying
filters, and using callbacks. Now it's time to get out there and sniff those
wires!
<p>This document is Copyright 2002 Tim Carstens.
All rights reserved. Redistribution and use, with or without modification,
are permitted provided that the following conditions are met:
<ol>
<li>Redistribution must retain the above copyright notice and this list of
conditions.
<li>The name of Tim Carstens may not be used to endorse or
promote products derived from this document without specific prior written
permission.</ol>
/* Insert 'wh00t' for the BSD license here */
</div>
</div>
</div>
<!-- END OF PAGE CONTENTS -->
<!-- FOOTER -->
<div id="footer">
<p>
© 2010–2023 The Tcpdump Group. Designed by
<a class=away href="https://www.luismg.com/">Luis MartinGarcia</a>;
based on a template by TEMPLATED.
</p>
</div>
<!-- END OF FOOTER -->
</body>
<!-- END OF HTML BODY -->
</html>