forked from IETF-OPSAWG-WG/draft-ietf-opsawg-pcap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-gharris-opsawg-pcap.xml
322 lines (250 loc) · 13.4 KB
/
draft-gharris-opsawg-pcap.xml
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
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[]>
<?rfc symrefs='yes' ?>
<?rfc toc='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<?rfc inline='yes' ?>
<?rfc sortrefs='no' ?>
<?rfc strict='yes' ?>
<rfc category='info'
ipr='trust200902'
docName="draft-gharris-opsawg-pcap-00">
<front>
<title abbrev="pcap">PCAP Capture File Format</title>
<author initials='G.' surname='Harris' fullname='Guy Harris'>
<address>
<email>gharris@sonic.net</email>
</address>
</author>
<date />
<abstract>
<t>This document describes the format used by the libpcap library
to record captured packets to a file. Programs using the libpcap
library to read and write those files, and thus reading and
writing files in that format, include tcpdump.</t>
</abstract>
</front>
<!--===========================================================================
MAIN BODY - still within the <rfc> tag
============================================================================-->
<middle>
<section title="Introduction">
<t>In the late 1980's, Van Jacobson, Steve McCanne, and others at
the Network Research Group at Lawrence Berkeley National
Laboratory developed the tcpdump program to capture and dissect
network traces. The code to capture traffic, using low-level
mechanisms in various operating systems, and to read and write
network traces to a file was later put into a library named
libpcap.</t>
<t>This document describes the format used by tcpdump, and other
programs using libpcap, to write network traces.</t>
</section>
<section title='Terminology'>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref
target='RFC2119'/>.</t>
</section>
<section title="General File Structure">
<t>A capture file begins with a File Header, followed by zero or
more Packet Records, one per packet.</t>
<t>All fields in the File Header and in Packet Records will
always be saved according to the characteristics (little endian
/ big endian) of the capturing machine. This refers to all the
fields that are saved as numbers and that span over two or more
octets.</t>
<t>The approach of having the file saved in the native format of
the generating host is more efficient because it avoids translation
of data when reading / writing on the host itself, which is the most
common case when generating/processing capture captures.</t>
</section>
<section title="File Header">
<t>The File Header has the following format:</t>
<figure anchor="file_header" title="File Header" align="center">
<artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 | Magic Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 | Major Version | Minor Version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 | Reserved1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 | Reserved2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 | SnapLen |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 | LinkType |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
</figure>
<t>The File Header length is 24 octets.</t>
<t>The meaning of the fields in the File Header is:
<list style="symbols">
<t>Magic Number (32 bits): an unsigned magic number,
whose value is either the hexadecimal number 0xA1B2C3D4
or the hexadecimal number 0xA1B23C4D. If the value is
0xA1B2C3D4, time stamps in Packet Records (see <xref
target="packet_record"/>) are in seconds and microseconds; if
it is 0xA1B23C4D, time stamps in Packet Records are in
seconds and nanoseconds. These numbers can be used to
distinguish sections that have been saved on little-endian
machines from the ones saved on big-endian machines, and to
heuristically identify pcap files.</t>
<t>Major Version (16 bits): an unsigned value, giving the
number of the current major version of the format. The
value for the current version of the format is 2. This
value should change if the format changes in such a way that
code that reads the new format could not read the old format
(i.e., code to read both formats would have to check the
version number and use different code paths for the two
formats) and code that reads the old format could not read
the new format.</t>
<t>Minor Version (16 bits): an unsigned value, giving the
number of the current minor version of the format. The
value is for the current version of the format is 4. This
value should change if the format changes in such a way that
code that reads the new format could read the old format
without checking the version number but code that reads the
old format could not read all files in the new format.</t>
<t>Reserved1 (32 bits): not used - SHOULD be filled with 0 by
pcap file writers, and MUST be ignored by pcap file
readers. This value was documented by some older implementations
as "gmt to local correction". Some older pcap file writers
stored non-zero values in this field.</t>
<t>Reserved2 (32 bits): not used - SHOULD be filled with 0 by
pcap file writers, and MUST be ignored by pcap file
readers. This value was documented by some older implementations
as "accuracy of timestamps". Some older pcap file writers
stored non-zero values in this field.</t>
<t>SnapLen (32 bits): an unsigned value indicating the
maximum number of octets captured from each packet. The
portion of each packet that exceeds this value will not be
stored in the file. This value MUST NOT be zero; if no
limit was specified, the value should be a number greater
than or equal to the largest packet length in the file.</t>
<t>LinkType (32 bits): an unsigned value that defines, in
the lower 16 bits, the link layer type of packets in the
file, and optionally indicates the length of the Frame Check
Sequence (FCS) of packets in the upper 16 bits. The list of
Standardized Link Layer Type codes is available in <xref
target="LINKTYPES"/>. If bit
5 is set, bits 0 through 3 contain the length of the FCS
field at the end of all packets; if bit 5 is not set, the
length of the FCS field at the end of all packets is
unknown. Bit 4, and bits 6 through 15, SHOULD be filled
with 0 by pcap file writers, and MUST be ignored by pcap
file readers.</t>
</list>
</t>
</section>
<section title="Packet Record">
<t>A Packet Record is the standard container for storing the
packets coming from the network.</t>
<figure anchor="packet_record" title="Packet Record">
<artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 | Timestamp (Seconds) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 | Timestamp (Microseconds or nanoseconds) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 | Captured Packet Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 | Original Packet Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 / /
/ Packet Data /
/ variable length /
/ /
+---------------------------------------------------------------+
</artwork>
</figure>
<t>The Packet Header length is 16 octets.</t>
<t>The meaning of the fields in the Packet Record is:
<list style="symbols">
<t>Timestamp (Seconds) and Timestamp (Microseconds or
nanoseconds): seconds and fraction of a seconds values of a
timestamp. The seconds value is a 32-bit unsigned integer
that represents the number of seconds that have elapsed
since 1970-01-01 00:00:00 UTC, and the microseconds or
nanoseconds value represents the number of microseconds or
nanoseconds that have elapsed since that seconds. Whether
the value represents microseconds or nanoseconds is
specified by the magic number in the File Header.</t>
<t>Captured Packet Length (32 bits): an unsigned value that
indicates the number of octets captured from the packet
(i.e. the length of the Packet Data field). It will be the
minimum value among the Original Packet Length and the
snapshot length for the interface (SnapLen, defined in <xref
target="file_header"/>).</t>
<t>Original Packet Length (32 bits): an unsigned value that
indicates the actual length of the packet when it was
transmitted on the network. It can be different from
the Captured Packet Length if the packet has been truncated
by the capture process.</t>
<t>Packet Data: the data coming from the network, including
link-layer headers. The actual length of this field is
Captured Packet Length. The format of the link-layer
headers depends on the LinkType field specified in the file
header (see <xref target="file_header"/>) and it is
specified in the entry for that format in <xref
target="LINKTYPES"/>.</t>
</list>
</t>
</section>
<section title="Recommended File Name Extension: .pcap">
<t>The recommended file name extension for the "PCAP Capture File
Format" specified in this document is ".pcap".</t>
<t>On Windows and macOS, files are distinguished by an extension to their
filename. Such an extension is technically not actually required, as
applications should be able to automatically detect the pcap file
format through the "magic bytes" at the beginning of the file, as some
other UN*X desktop environments do. However, using name extensions makes
it easier to work with files (e.g. visually distinguish file formats) so
it is recommended - though not required - to use .pcap as the name
extension for files following this specification.</t>
<t>Please note: To avoid confusion (such as the current usage of
.cap for a plethora of different capture file formats) file
name extensions other than .pcap should be avoided.</t>
</section>
<section title="Security Considerations">
<t>TBD.</t>
</section>
<section title="IANA Considerations">
<t>TBD.</t>
<t>[Open issue: decide whether the LinkType values should be IANA
registries. And if so, what the IANA policy for each should be
(see RFC 5226)]</t>
</section>
<section title='Contributors'>
<t>[Insert pcap developers etc. here].</t>
</section>
<section title="Acknowledgments">
<t>The authors wish to thank [insert list here]
and many others for their invaluable comments.</t>
</section>
</middle>
<!--===========================================================================
Back End - still within the <rfc> tag
============================================================================-->
<back>
<references title='Normative References'>
<?rfc include='reference.RFC.2119'?>
</references>
<references title='Informational References'>
<reference anchor="LINKTYPES" target="http://www.tcpdump.org/linktypes.html">
<front>
<title>the tcpdump.org link-layer header types registry</title>
<author initials="" surname="" fullname="">
<organization>The Tcpdump Group</organization>
</author>
<date/>
</front>
</reference>
</references>
</back>
</rfc>