idnits 2.17.1 draft-gharris-opsawg-pcap-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (22 December 2020) is 1219 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'LINKTYPES' is mentioned on line 257, but not defined == Outdated reference: A later version (-05) exists of draft-tuexen-opsawg-pcapng-02 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group G. Harris, Ed. 3 Internet-Draft 4 Intended status: Informational M. Richardson 5 Expires: 25 June 2021 Sandelman 6 22 December 2020 8 PCAP Capture File Format 9 draft-gharris-opsawg-pcap-00 11 Abstract 13 This document describes the format used by the libpcap library to 14 record captured packets to a file. Programs using the libpcap 15 library to read and write those files, and thus reading and writing 16 files in that format, include tcpdump. 18 Discussion Venues 20 This note is to be removed before publishing as an RFC. 22 Discussion of this document takes place on the OPSAWG Working Group 23 mailing list (opsawg@ietf.org), which is archived at 24 https://mailarchive.ietf.org/arch/browse/opsawg/. 26 Source for this draft and an issue tracker can be found at 27 https://github.com/pcapng/pcapng. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 25 June 2021. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. General File Structure . . . . . . . . . . . . . . . . . . . 3 65 4. File Header . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 5. Packet Record . . . . . . . . . . . . . . . . . . . . . . . . 5 67 6. Recommended File Name Extension: .pcap . . . . . . . . . . . 7 68 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7 71 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 72 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 11.1. Normative References . . . . . . . . . . . . . . . . . . 8 74 11.2. Informative References . . . . . . . . . . . . . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 77 1. Introduction 79 In the late 1980's, Van Jacobson, Steve McCanne, and others at the 80 Network Research Group at Lawrence Berkeley National Laboratory 81 developed the tcpdump program to capture and dissect network traces. 82 The code to capture traffic, using low-level mechanisms in various 83 operating systems, and to read and write network traces to a file was 84 later put into a library named libpcap. 86 This document describes the format used by tcpdump, and other 87 programs using libpcap, to read and write network traces. 89 2. Terminology 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 93 "OPTIONAL" in this document are to be interpreted as described in 94 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 95 capitals, as shown here. 97 3. General File Structure 99 A capture file begins with a File Header, followed by zero or more 100 Packet Records, one per packet. 102 All fields in the File Header and in Packet Records will always be 103 saved according to the characteristics (little endian / big endian) 104 of the capturing machine. This refers to all the fields that are 105 saved as numbers and that span over two or more octets. 107 The approach of having the file saved in the native format of the 108 generating host is more efficient because it avoids translation of 109 data when reading / writing on the host itself, which is the most 110 common case when generating/processing capture captures. 112 The packets are shown in traditional IETF diagram, with the bits 113 numbered from the left to the right. The bit numbering does not 114 reflect the binary value position, as IETF protocols are 115 traditionally in big-endian network-byte order. The most significant 116 bit is therefore on the left in this diagram as if the file is being 117 stored on a big-endian system. 119 4. File Header 121 The File Header has the following format: 123 1 2 3 124 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 125 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 126 0 | Magic Number | 127 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 128 4 | Major Version | Minor Version | 129 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 130 8 | Reserved1 | 131 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 132 12 | Reserved2 | 133 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 134 16 | SnapLen | 135 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 136 20 | FCS |f| LinkType | 137 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 139 Figure 1: File Header 141 The File Header length is 24 octets. 143 The meaning of the fields in the File Header is: 145 Magic Number (32 bits): an unsigned magic number, whose value is 146 either the hexadecimal number 0xA1B2C3D4 or the hexadecimal number 147 0xA1B23C4D. 149 If the value is 0xA1B2C3D4, time stamps in Packet Records (see 150 Figure 2) are in seconds and microseconds; if it is 0xA1B23C4D, 151 time stamps in Packet Records are in seconds and nanoseconds. 153 These numbers can be used to distinguish sections that have been 154 saved on little-endian machines from the ones saved on big-endian 155 machines, and to heuristically identify pcap files. 157 Major Version (16 bits): an unsigned value, giving the number of the 158 current major version of the format. The value for the current 159 version of the format is 2. This value should change if the 160 format changes in such a way that code that reads the new format 161 could not read the old format (i.e., code to read both formats 162 would have to check the version number and use different code 163 paths for the two formats) and code that reads the old format 164 could not read the new format. 166 Minor Version (16 bits): an unsigned value, giving the number of the 167 current minor version of the format. The value is for the current 168 version of the format is 4. This value should change if the 169 format changes in such a way that code that reads the new format 170 could read the old format without checking the version number but 171 code that reads the old format could not read all files in the new 172 format. 174 Reserved1 (32 bits): not used - SHOULD be filled with 0 by pcap file 175 writers, and MUST be ignored by pcap file readers. This value was 176 documented by some older implementations as "gmt to local 177 correction". Some older pcap file writers stored non-zero values 178 in this field. 180 Reserved2 (32 bits): not used - SHOULD be filled with 0 by pcap file 181 writers, and MUST be ignored by pcap file readers. This value was 182 documented by some older implementations as "accuracy of 183 timestamps". Some older pcap file writers stored non-zero values 184 in this field. 186 SnapLen (32 bits): an unsigned value indicating the maximum number 187 of octets captured from each packet. The portion of each packet 188 that exceeds this value will not be stored in the file. This 189 value MUST NOT be zero; if no limit was specified, the value 190 should be a number greater than or equal to the largest packet 191 length in the file. 193 LinkType (32 bits): an unsigned value that defines, in the lower 28 194 bits, the link layer type of packets in the file. 196 Frame Cyclic Sequence present (4 bits): if the "f" bit is set, then 197 the FCS bits provide the number of bytes of FCS that are appended 198 to each packet. 200 valid values are between 0 and 7, with ethernet typically having a 201 length of 4 bytes. 203 5. Packet Record 205 A Packet Record is the standard container for storing the packets 206 coming from the network. 208 1 2 3 209 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 210 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 211 0 | Timestamp (Seconds) | 212 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 213 4 | Timestamp (Microseconds or nanoseconds) | 214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 215 8 | Captured Packet Length | 216 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 217 12 | Original Packet Length | 218 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 219 16 / / 220 / Packet Data / 221 / variable length / 222 / / 223 +---------------------------------------------------------------+ 225 Figure 2: Packet Record 227 The Packet Header length is 16 octets. 229 The meaning of the fields in the Packet Record is: 231 Timestamp (Seconds) and Timestamp (Microseconds or nanoseconds): sec 232 onds and fraction of a seconds values of a timestamp. 234 The seconds value is a 32-bit unsigned integer that represents the 235 number of seconds that have elapsed since 1970-01-01 00:00:00 UTC, 236 and the microseconds or nanoseconds value represents the number of 237 microseconds or nanoseconds that have elapsed since that seconds. 239 Whether the value represents microseconds or nanoseconds is 240 specified by the magic number in the File Header. 242 Captured Packet Length (32 bits): an unsigned value that indicates 243 the number of octets captured from the packet (i.e. the length of 244 the Packet Data field). It will be the minimum value among the 245 Original Packet Length and the snapshot length for the interface 246 (SnapLen, defined in Figure 1). 248 Original Packet Length (32 bits): an unsigned value that indicates 249 the actual length of the packet when it was transmitted on the 250 network. It can be different from the Captured Packet Length if 251 the packet has been truncated by the capture process. 253 Packet Data: the data coming from the network, including link-layer 254 headers. The actual length of this field is Captured Packet 255 Length. The format of the link-layer headers depends on the 256 LinkType field specified in the file header (see Figure 1) and it 257 is specified in the entry for that format in [LINKTYPES]. 259 6. Recommended File Name Extension: .pcap 261 The recommended file name extension for the "PCAP Capture File 262 Format" specified in this document is ".pcap". 264 On Windows and macOS, files are distinguished by an extension to 265 their filename. Such an extension is technically not actually 266 required, as applications should be able to automatically detect the 267 pcap file format through the "magic bytes" at the beginning of the 268 file, as some other UN*X desktop environments do. However, using 269 name extensions makes it easier to work with files (e.g. visually 270 distinguish file formats) so it is recommended - though not required 271 - to use .pcap as the name extension for files following this 272 specification. 274 Please note: To avoid confusion (such as the current usage of .cap 275 for a plethora of different capture file formats) file name 276 extensions other than .pcap should be avoided. 278 There is new work to create the PCAP Next Generation capture File 279 Format (see [I-D.tuexen-opsawg-pcapng]). The new file format is not 280 compatible with this specification, but many programs read both 281 transparently. Files of that type will usually start with a 282 Section Header Block, with a magic number of 0x0A0D0D0A. 284 7. Security Considerations 286 TBD. 288 8. IANA Considerations 290 TBD. 292 [Open issue: decide whether the LinkType values should be IANA 293 registries. And if so, what the IANA policy for each should be (see 294 RFC 5226)] 296 9. Contributors 298 [Insert pcap developers etc. here]. 300 10. Acknowledgments 302 The authors wish to thank [insert list here] and many others for 303 their invaluable comments. 305 11. References 307 11.1. Normative References 309 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 310 Requirement Levels", BCP 14, RFC 2119, 311 DOI 10.17487/RFC2119, March 1997, 312 . 314 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 315 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 316 May 2017, . 318 11.2. Informative References 320 [I-D.tuexen-opsawg-pcapng] 321 Tuexen, M., Risso, F., Bongertz, J., Combs, G., Harris, 322 G., and M. Richardson, "PCAP Next Generation (pcapng) 323 Capture File Format", Work in Progress, Internet-Draft, 324 draft-tuexen-opsawg-pcapng-02, 28 September 2020, 325 . 328 Authors' Addresses 330 Guy Harris (editor) 332 Email: gharris@sonic.net 334 Michael C. Richardson 335 Sandelman Software Works Inc 337 Email: mcr+ietf@sandelman.ca 338 URI: http://www.sandelman.ca/