idnits 2.17.1 draft-tuexen-opsawg-pcapng-04.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 (4 October 2021) is 906 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- No information found for draft-richardson-opsawg-pcapng-extras - is the name correct? Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Tuexen, Ed. 3 Internet-Draft Muenster Univ. of Appl. Sciences 4 Intended status: Informational F. Risso 5 Expires: 7 April 2022 Politecnico di Torino 6 J. Bongertz 7 Airbus DS CyberSecurity 8 G. Combs 9 Wireshark 10 G. Harris 12 E. Chaudron 13 Red Hat 14 M. Richardson 15 Sandelman 16 4 October 2021 18 PCAP Next Generation (pcapng) Capture File Format 19 draft-tuexen-opsawg-pcapng-04 21 Abstract 23 This document describes a format to record captured packets to a 24 file. This format is extensible; Wireshark can currently read and 25 write it, and libpcap can currently read some pcapng files. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 7 April 2022. 44 Copyright Notice 46 Copyright (c) 2021 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2.1. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. General File Structure . . . . . . . . . . . . . . . . . . . 4 64 3.1. General Block Structure . . . . . . . . . . . . . . . . . 4 65 3.2. Block Types . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.3. Logical Block Hierarchy . . . . . . . . . . . . . . . . . 6 67 3.4. Physical File Layout . . . . . . . . . . . . . . . . . . 7 68 3.5. Options . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 3.5.1. Custom Options . . . . . . . . . . . . . . . . . . . 12 70 3.6. Data format . . . . . . . . . . . . . . . . . . . . . . . 13 71 3.6.1. Endianness . . . . . . . . . . . . . . . . . . . . . 13 72 3.6.2. Alignment . . . . . . . . . . . . . . . . . . . . . . 14 73 4. Block Definition . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1. Section Header Block . . . . . . . . . . . . . . . . . . 14 75 4.2. Interface Description Block . . . . . . . . . . . . . . . 18 76 4.3. Enhanced Packet Block . . . . . . . . . . . . . . . . . . 25 77 4.3.1. Enhanced Packet Block Flags Word . . . . . . . . . . 30 78 4.4. Simple Packet Block . . . . . . . . . . . . . . . . . . . 31 79 4.5. Name Resolution Block . . . . . . . . . . . . . . . . . . 33 80 4.6. Interface Statistics Block . . . . . . . . . . . . . . . 37 81 4.7. Decryption Secrets Block . . . . . . . . . . . . . . . . 40 82 4.8. Custom Block . . . . . . . . . . . . . . . . . . . . . . 44 83 5. Vendor-Specific Custom Extensions . . . . . . . . . . . . . . 46 84 5.1. Supported Use-Cases . . . . . . . . . . . . . . . . . . . 46 85 5.2. Controlling Copy Behavior . . . . . . . . . . . . . . . . 47 86 5.3. Strings vs. Octets . . . . . . . . . . . . . . . . . . . 47 87 5.4. Endianness Issues . . . . . . . . . . . . . . . . . . . . 47 88 6. Recommended File Name Extension: .pcapng . . . . . . . . . . 48 89 7. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 49 90 8. Implementations . . . . . . . . . . . . . . . . . . . . . . . 49 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 49 92 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 93 10.1. Standardized Block Type Codes . . . . . . . . . . . . . 50 94 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 53 95 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 96 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 97 13.1. Normative References . . . . . . . . . . . . . . . . . . 53 98 13.2. Informative References . . . . . . . . . . . . . . . . . 53 99 Appendix A. Packet Block (obsolete!) . . . . . . . . . . . . . . 53 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 102 1. Introduction 104 The problem of exchanging packet traces becomes more and more 105 critical every day; unfortunately, no standard solutions exist for 106 this task right now. One of the most accepted packet interchange 107 formats is the one defined by libpcap, which is rather old and is 108 lacking in functionality for more modern applications particularly 109 from the extensibility point of view. 111 This document proposes a new format for recording packet traces. The 112 following goals are being pursued: 114 Extensibility: It should be possible to add new standard 115 capabilities to the file format over time, and third parties 116 should be able to enrich the information embedded in the file with 117 proprietary extensions, with tools unaware of newer extensions 118 being able to ignore them. 120 Portability: A capture trace must contain all the information needed 121 to read data independently from network, hardware and operating 122 system of the machine that made the capture. 124 Merge/Append data: It should be possible to add data at the end of a 125 given file, and the resulting file must still be readable. 127 2. Terminology 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 131 "OPTIONAL" in this document are to be interpreted as described in 132 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 133 capitals, as shown here. 135 2.1. Acronyms 137 The following acronyms are used throughout this document: 139 SHB: Section Header Block 141 IDB: Interface Description Block 143 ISB: Interface Statistics Block 144 EPB: Enhanced Packet Block 146 SPB: Simple Packet Block 148 NRB: Name Resolution Block 150 CB: Custom Block 152 3. General File Structure 154 3.1. General Block Structure 156 A capture file is organized in blocks, that are appended one to 157 another to form the file. All the blocks share a common format, 158 which is shown in Figure 1. 160 1 2 3 161 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 162 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 163 0 | Block Type | 164 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 165 4 | Block Total Length | 166 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 167 8 / Block Body / 168 / variable length, padded to 32 bits / 169 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 170 | Block Total Length | 171 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 173 Figure 1: Basic block structure. 175 The fields have the following meaning: 177 * Block Type (32 bits): a unique unsigned value that identifies the 178 block. Values whose Most Significant Bit (MSB) is equal to 1 are 179 reserved for local use. They can be used to make extensions to 180 the file format to save private data to the file. The list of 181 currently defined types can be found in Section 10.1. 183 * Block Total Length (32 bits): an unsigned value giving the total 184 size of this block, in octets. For instance, the length of a 185 block that does not have a body is 12 octets: 4 octets for the 186 Block Type, 4 octets for the initial Block Total Length and 4 187 octets for the trailing Block Total Length. This value MUST be a 188 multiple of 4. 190 * Block Body: content of the block. 192 * Block Total Length: total size of this block, in octets. This 193 field is duplicated to permit backward file navigation. 195 This structure, shared among all blocks, makes it easy to process a 196 file and to skip unneeded or unknown blocks. Some blocks can contain 197 other blocks inside (nested blocks). Some of the blocks are 198 mandatory, i.e. a capture file is not valid if they are not present, 199 other are optional. 201 The General Block Structure allows defining other blocks if needed. 202 A parser that does not understand them can simply ignore their 203 content. 205 3.2. Block Types 207 The currently standardized Block Type codes are specified in 208 Section 10.1; they have been grouped in the following four 209 categories: 211 The following MANDATORY block MUST appear at least once in each file: 213 * Section Header Block (Section 4.1): it defines the most important 214 characteristics of the capture file. 216 The following OPTIONAL blocks MAY appear in a file: 218 * Interface Description Block (Section 4.2): it defines the most 219 important characteristics of the interface(s) used for capturing 220 traffic. This block is required in certain cases, as described 221 later. 223 * Enhanced Packet Block (Section 4.3): it contains a single captured 224 packet, or a portion of it. It represents an evolution of the 225 original, now obsolete, Packet Block (Appendix A). If this 226 appears in a file, an Interface Description Block is also 227 required, before this block. 229 * Simple Packet Block (Section 4.4): it contains a single captured 230 packet, or a portion of it, with only a minimal set of information 231 about it. If this appears in a file, an Interface Description 232 Block is also required, before this block. 234 * Name Resolution Block (Section 4.5): it defines the mapping from 235 numeric addresses present in the packet capture and the canonical 236 name counterpart. 238 * Interface Statistics Block (Section 4.6): it defines how to store 239 some statistical data (e.g. packet dropped, etc) which can be 240 useful to understand the conditions in which the capture has been 241 made. If this appears in a file, an Interface Description Block 242 is also required, before this block. 244 * Custom Block (Section 4.8): it contains vendor-specific data in a 245 portable fashion. 247 The following OBSOLETE block SHOULD NOT appear in newly written files 248 (but is documented in the Appendix for reference): 250 * Packet Block (Appendix A): it contains a single captured packet, 251 or a portion of it. It is OBSOLETE, and superseded by the 252 Enhanced Packet Block (Section 4.3). 254 The following EXPERIMENTAL blocks are considered interesting but the 255 authors believe that they deserve more in-depth discussion before 256 being defined: 258 * Alternative Packet Blocks 260 * Compression Block 262 * Encryption Block 264 * Fixed Length Block 266 * Directory Block 268 * Traffic Statistics and Monitoring Blocks 270 * Event/Security Blocks 272 Requests for new standardized Block Type codes should be made by 273 creating a pull request to update this document as described in 274 Section 10.1. 276 3.3. Logical Block Hierarchy 278 The blocks build a logical hierarchy as they refer to each other. 279 Figure 2 shows the logical hierarchy of the currently defined blocks 280 in the form of a "tree view": 282 Section Header 283 | 284 +- Interface Description 285 | +- Simple Packet 286 | +- Enhanced Packet 287 | +- Interface Statistics 288 | 289 +- Name Resolution 291 Figure 2: Logical Block Hierarchy of a pcapng File 293 For example: each captured packet refers to a specific capture 294 interface, the interface itself refers to a specific section. 296 3.4. Physical File Layout 298 The file MUST begin with a Section Header Block. However, more than 299 one Section Header Block can be present in the capture file, each one 300 covering the data following it until the next one (or the end of 301 file). A Section includes the data delimited by two Section Header 302 Blocks (or by a Section Header Block and the end of the file), 303 including the first Section Header Block. 305 In case an application cannot read a Section because of different 306 version number, it MUST skip everything until the next Section Header 307 Block. Note that, in order to properly skip the blocks until the 308 next section, all blocks MUST have the fields Type and Length at the 309 beginning. In order to properly skip blocks in the backward 310 direction, all blocks MUST have the Length repeated at the end of the 311 block. These are mandatory requirements that MUST be maintained in 312 future versions of the block format. 314 Figure 3 shows a typical file layout, with a single Section Header 315 that covers the whole file. 317 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 318 | SHB v1.0 | Data | 319 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 321 Figure 3: File structure example: Typical layout with a single 322 Section Header Block 324 Figure 4 shows a file that contains three headers, and is normally 325 the result of file concatenation. An application that understands 326 only version 1.0 of the file format skips the intermediate section 327 and restart processing the packets after the third Section Header. 329 |-- 1st Section --|-- 2nd Section --|-- 3rd Section --| 330 | | 331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 332 | SHB v1.0 | Data | SHB V1.1 | Data | SHB V1.0 | Data | 333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 335 Figure 4: File structure example: three Section Header Blocks in 336 a single file 338 Figure 5 shows a file comparable to a "classic libpcap" file - the 339 minimum for a useful capture file. It contains a single 340 Section Header Block (SHB), a single Interface Description Block 341 (IDB) and a few Enhanced Packet Blocks (EPB). 343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 344 | SHB | IDB | EPB | EPB | ... | EPB | 345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 347 Figure 5: File structure example: a pcapng file similar to a 348 classical libpcap file 350 Figure 6 shows a complex example file. In addition to the minimum 351 file above, it contains packets captured from three interfaces, 352 capturing on the third of which begins after packets have arrived on 353 other interfaces, and also includes some Name Resolution Blocks (NRB) 354 and an Interface Statistics Block (ISB). 356 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 357 | SHB | IDB | IDB | EPB | NRB |...| IDB | EPB | ISB | NRB | EPB | 358 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 360 Figure 6: File structure example: complex pcapng file 362 The last example should make it obvious that the block structure 363 makes the file format very flexible compared to the classical libpcap 364 format. 366 3.5. Options 368 All the block bodies MAY embed optional fields. Optional fields can 369 be used to insert some information that may be useful when reading 370 data, but that is not really needed for packet processing. 371 Therefore, each tool can either read the content of the optional 372 fields (if any), or skip some of them or even all at once. 374 A block that may contain options must be structured so that the 375 number of octets of data in the Block Body that precede the options 376 can be determined from that data; that allows the beginning of the 377 options to be found. That is true for all standard blocks that 378 support options; for Custom Blocks that support options, the Custom 379 Data must be structured in such a fashion. This means that the Block 380 Length field (present in the General Block Structure, see 381 Section 3.1) can be used to determine how many octets of optional 382 fields, if any, are present in the block. That number can be used to 383 determine whether the block has optional fields (if it is zero, there 384 are no optional fields), to check, when processing optional fields, 385 whether any optional fields remain, and to skip all the optional 386 fields at once. 388 Options are a list of Type - Length - Value fields, each one 389 containing a single value: 391 * Option Type (16 bits): an unsigned value that contains the code 392 that specifies the type of the current TLV record. Option types 393 whose Most Significant Bit is equal to one are reserved for local 394 use; therefore, there is no guarantee that the code used is unique 395 among all capture files (generated by other applications), and is 396 most certainly not portable. For cross-platform globally unique 397 vendor-specific extensions, the Custom Option MUST be used 398 instead, as defined in Section 3.5.1). 400 * Option Length (16 bits): an unsigned value that contains the 401 actual length of the following 'Option Value' field without the 402 padding octets. 404 * Option Value (variable length): the value of the given option, 405 padded to a 32-bit boundary. The actual length of this field 406 (i.e. without the padding octets) is specified by the Option 407 Length field. 409 Requests for new standardized option codes for a given block should 410 be made by creating a pull request to update this document as 411 described in Section 10.1. 413 A given option may have a fixed length, in which case all instances 414 of that option have a length that is equal to the specified fixed 415 length, or a variable length, in which case the option has a minimum 416 length and all instances of that option must have a length equal to 417 or greater than the specified minimum length. The length of fixed- 418 length options, and the minimum length of variable-length options, is 419 specified in the description of the option; if the minimum length of 420 a variable-length option is not specified, a zero-length option is 421 valid. Software that reads these files SHOULD report options that 422 have an invalid length as errors; the software MAY stop processing 423 the file if it sees an option that has invalid length, or MAY ignore 424 the option and continue processing it. Software that writes these 425 files MUST NOT write files with options that have invalid lengths. 427 If an option's value is a string, the value is not necessarily zero- 428 terminated. Software that reads these files MUST NOT assume that 429 strings are zero-terminated, and MUST treat a zero-value octet as a 430 string terminator. 432 Some options may be repeated several times; for example, a block can 433 have multiple comments, and an Interface Description Block can give 434 multiple IPv4 or IPv6 addresses for the interface if it has multiple 435 IPv4 or IPv6 addresses assigned to it. Other options may appear at 436 most once in a given block. 438 The option list is terminated by a option which uses the special 'End 439 of Option' code (opt_endofopt). Code that writes pcapng files MUST 440 put an opt_endofopt option at the end of an option list. Code that 441 reads pcapng files MUST NOT assume an option list will have an 442 opt_endofopt option at the end; it MUST also check for the end of the 443 block, and SHOULD treat blocks where the option list has no 444 opt_endofopt option as if the option list had an opt_endofopt option 445 at the end. 447 The format of the optional fields is shown in Figure 7. 449 1 2 3 450 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 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 452 | Option Code | Option Length | 453 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 454 / Option Value / 455 / variable length, padded to 32 bits / 456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 457 / / 458 / . . . other options . . . / 459 / / 460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 461 | Option Code == opt_endofopt | Option Length == 0 | 462 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 464 Figure 7: Options Format 466 The following codes can always be present in any optional field: 468 +==============+=======================+===========+==========+ 469 | Name | Code | Length | Multiple | 470 | | | | allowed? | 471 +==============+=======================+===========+==========+ 472 | opt_endofopt | 0 | 0 | no | 473 +--------------+-----------------------+-----------+----------+ 474 | opt_comment | 1 | variable | yes | 475 +--------------+-----------------------+-----------+----------+ 476 | opt_custom | 2988/2989/19372/19373 | variable, | yes | 477 | | | minimum 4 | | 478 +--------------+-----------------------+-----------+----------+ 480 Table 1: Common Options 482 opt_endofopt: 483 The opt_endofopt option delimits the end of the optional 484 fields. This option MUST NOT be repeated within a given list 485 of options. 487 opt_comment: 488 The opt_comment option is a UTF-8 string containing human- 489 readable comment text that is associated to the current 490 block. Line separators SHOULD be a carriage-return + 491 linefeed ('\r\n') or just linefeed ('\n'); either form may 492 appear and be considered a line separator. The string is not 493 zero-terminated. 495 Examples: "This packet is the beginning of all of our problems", 496 "Packets 17-23 showing a bogus TCP retransmission!\r\n This is 497 reported in bugzilla entry 1486.\nIt will be fixed in the future.". 499 opt_custom: 500 This option is described in detail in Section 3.5.1. 502 3.5.1. Custom Options 504 Customs Options are used for portable, vendor-specific data related 505 to the block they're in. A Custom Option can be in any block type 506 that can have options, can be repeated any number of times in a 507 block, and may come before or after other option types - except the 508 opt_endofopt option, which is always the last option. Different 509 Custom Options, of different type codes and/or different Private 510 Enterprise Numbers, may be used in the same pcapng file. See 511 Section 5 for additional details. 513 1 2 3 514 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 515 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 516 | Custom Option Code | Option Length | 517 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 518 | Private Enterprise Number (PEN) | 519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 520 / Custom Data / 521 / variable length, padded to 32 bits / 522 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 524 Figure 8: Custom Options Format 526 The Custom Option has the following fields: 528 * Custom Option Code: The code number for the Custom Option, which 529 can be one of the following decimal numbers: 531 2988: 532 This option code identifies a Custom Option containing a 533 UTF-8 string in the Custom Data portion. The string is 534 not zero-terminated. This Custom Option can be safely 535 copied to a new file if the pcapng file is manipulated by 536 an application; otherwise 19372 should be used instead. 537 See Section 5.2 for details. 539 2989: 541 This option code identifies a Custom Option containing 542 binary octets in the Custom Data portion. This Custom 543 Option can be safely copied to a new file if the pcapng 544 file is manipulated by an application; otherwise 19372 545 should be used instead. See Section 5.2 for details. 547 19372: 548 This option code identifies a Custom Option containing a 549 UTF-8 string in the Custom Data portion. The string is 550 not zero-terminated. This Custom Option should not be 551 copied to a new file if the pcapng file is manipulated by 552 an application. See Section 5.2 for details. 554 19373: 555 This option code identifies a Custom Option containing 556 binary octets in the Custom Data portion. This Custom 557 Option should not be copied to a new file if the pcapng 558 file is manipulated by an application. See Section 5.2 559 for details. 561 * Option Length: as described in Section 3.1, this contains the 562 length of the option's value, which includes the 4-octet Private 563 Enterprise Number and variable-length Custom Data fields, without 564 the padding octets. 566 * Private Enterprise Number: An IANA-assigned Private Enterprise 567 Number identifying the organization which defined the Custom 568 Option. See Section 5.1 for details. The PEN MUST be encoded 569 using the same endianness as the Section Header Block it is within 570 the scope of. 572 * Custom Data: the custom data, padded to a 32 bit boundary. 574 3.6. Data format 576 3.6.1. Endianness 578 Data contained in each section will always be saved according to the 579 characteristics (little endian / big endian) of the capturing 580 machine. This refers to all the fields that are saved as numbers and 581 that span over two or more octets. 583 The approach of having each section saved in the native format of the 584 generating host is more efficient because it avoids translation of 585 data when reading / writing on the host itself, which is the most 586 common case when generating/processing capture captures. 588 Please note: The endianness is indicated by the Section Header Block 589 (Section 4.1). Since this block can appear several times in a pcapng 590 file, a single file can contain both endianness variants. 592 3.6.2. Alignment 594 All fields of this specification use proper alignment for 16- and 595 32-bit values. This makes it easier and faster to read/write file 596 contents if using techniques like memory mapped files. 598 The alignment octets (marked in this document e.g. with "padded to 32 599 bits") MUST be filled with zeroes. 601 Please note: 64-bit values are not aligned to 64-bit boundaries. 602 This is because the file is naturally aligned to 32-bit boundaries 603 only. Special care MUST be taken when reading and writing such 604 values. (Note also that some 64-bit values are represented as a 605 64-bit integer in the endianness of the machine that wrote the file, 606 and others are represented as 2 32-bit values, one containing the 607 upper 32 bits of the value and one containing the lower 32 bits of 608 the value, each written as 32-bit integers in the endianness of the 609 machine that wrote the file. Neither of these formats guarantee 610 64-bit alignment.) 612 4. Block Definition 614 This section details the format of the blocks currently defined. 616 4.1. Section Header Block 618 The Section Header Block (SHB) is mandatory. It identifies the 619 beginning of a section of the capture file. The Section Header Block 620 does not contain data but it rather identifies a list of blocks 621 (interfaces, packets) that are logically correlated. Its format is 622 shown in Figure 9. 624 1 2 3 625 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 626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 627 0 | Block Type = 0x0A0D0D0A | 628 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 629 4 | Block Total Length | 630 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 631 8 | Byte-Order Magic | 632 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 633 12 | Major Version | Minor Version | 634 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 635 16 | | 636 | Section Length | 637 | | 638 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 639 24 / / 640 / Options (variable) / 641 / / 642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 643 | Block Total Length | 644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 646 Figure 9: Section Header Block Format 648 The meaning of the fields is: 650 * Block Type: The block type of the Section Header Block is the 651 integer corresponding to the 4-char string "\n\r\r\n" 652 (0x0A0D0D0A). This particular value is used for 2 reasons: 654 1. This number is used to detect if a file has been transferred 655 via FTP or HTTP from a machine to another with an 656 inappropriate ASCII conversion. In this case, the value of 657 this field will differ from the standard one ("\n\r\r\n") and 658 the reader can detect a possibly corrupted file. 660 2. This value is palindromic, so that the reader is able to 661 recognize the Section Header Block regardless of the 662 endianness of the section. The endianness is recognized by 663 reading the Byte Order Magic, which is located 8 octets after 664 the Block Type. 666 * Block Total Length: total size of this block, as described in 667 Section 3.1. 669 * Byte-Order Magic (32 bits): an unsigned magic number, whose value 670 is the hexadecimal number 0x1A2B3C4D. This number can be used to 671 distinguish sections that have been saved on little-endian 672 machines from the ones saved on big-endian machines, and to 673 heuristically identify pcapng files. 675 * Major Version (16 bits): an unsigned value, giving the number of 676 the current major version of the format. The value for the 677 current version of the format is 1. 679 * Minor Version (16 bits): an unsigned value, giving the number of 680 the current minor version of the format. The value for the 681 current version of the format is 0. 683 * Section Length (64 bits): a signed value specifying the length in 684 octets of the following section, excluding the Section Header 685 Block itself. This field can be used to skip the section, for 686 faster navigation inside large files. If the Section Length is -1 687 (0xFFFFFFFFFFFFFFFF), this means that the size of the section is 688 not specified, and the only way to skip the section is to parse 689 the blocks that it contains. Please note that if this field is 690 valid (i.e. not negative), its value is always a multiple of 4, as 691 all the blocks are aligned to and padded to 32-bit (4 octet) 692 boundaries. Also, special care should be taken in accessing this 693 field: since the alignment of all the blocks in the file is 694 32-bits, this field is not guaranteed to be aligned to a 64-bit 695 boundary. This could be a problem on 64-bit processors. 697 * Options: optionally, a list of options (formatted according to the 698 rules defined in Section 3.5) can be present. 700 Writers of pcapng files MUST NOT write SHBs with a Major Version 701 other than 1 or a Minor Version other than 0. If they do so, they 702 will write a file that many readers of pcapng files, such as programs 703 using libpcap to read pcapng files (including, but not limited to, 704 tcpdump), Wireshark, and possibly other programs not to be able to 705 read their files. 707 Some pcapng file writers have used a minor version of 2, but the file 708 format did not change incompatibly (new block types were added); 709 Readers of pcapng files MUST treat a Minor Version of 2 as equivalent 710 to a Minor Version of 0 (and, if they also write a pcapng file based 711 on the results of reading one or more pcapng files, they MUST NOT, as 712 per the previous sentence, write an SHB with a Minor Version of 2, 713 even if they read an SHB with a Minor Version of 2). As indicated 714 above, using a minor version number other than 0 when writing a 715 section of a pcapng file will produce a section that most existing 716 software will not be able to read; future versions of some of that 717 software will be able to read sections with a version of 1.2, but 718 older copies of that software that are not updated to the latest 719 version will still not be able to read them. 721 The Major Version would be changed only if a new version of this 722 specification, for a later major version of the file format, were 723 created. Such a version would only be created if the format were to 724 change in such a way that code that reads the new format could not 725 read the old format (i.e., code to read both formats would have to 726 check the version number and use different code paths for the two 727 formats) and code that reads the old format could not read the new 728 format. An incompatible change to the format of an existing block or 729 an existing option would be such a change; the addition of a new 730 block or a new option would not be such a change. An example of such 731 an incomparible change would be the addition of an additional field 732 to the Section Header Block, following the Minor Version field and 733 before the Snaplen field; software expecting the new SHB format would 734 not correctly read the old SHB format, and software expecting the old 735 SHB format would not correctly read the new SHB format. (Note that a 736 change to the SHB must leave the Block Type, Block Total Length, 737 Byte-Order Magic, Major Version, and Minor Version fields at the same 738 offsets from the beginning of the SHB and with the same lengths, must 739 keep the value of the Block TYpe the same, must keep the two 740 posssible values of the Byte-Order Magic the same, depending on the 741 block's byte order, so that the rest of the SHB can be correctly 742 interpreted.) 744 The Minor Version would be changed only if a new version of this 745 specification, for a later minor version of the file format, were 746 created. Such a version would only be created if the format were to 747 change in such a way that code that reads the new format could read 748 the old format without checking the version number but code that 749 reads the old format could not read all files in the new format. A 750 backward-compatible change to the format of an existing block or an 751 existing opption would be such a change; the addition of a new block 752 or a new option would not be such a change. An example of such a 753 backward-compatible but not forward-compatible change would be a 754 change to the Interface Description block (see below) to use the 755 current Reserved field to indicate the presence of additional fields 756 before the Options, with a zero value indicate no such fields are 757 present. 759 I.e., adding new block types or options would not require that either 760 the Major Version or the Minor Version be changed, as code that does 761 not know about the block type or option should just skip it; only if 762 skipping a block or option does not work should the minor version 763 number be changed. 765 Aside from the options defined in Section 3.5, the following options 766 are valid within this block: 768 +==============+======+==========+===================+ 769 | Name | Code | Length | Multiple allowed? | 770 +==============+======+==========+===================+ 771 | shb_hardware | 2 | variable | no | 772 +--------------+------+----------+-------------------+ 773 | shb_os | 3 | variable | no | 774 +--------------+------+----------+-------------------+ 775 | shb_userappl | 4 | variable | no | 776 +--------------+------+----------+-------------------+ 778 Table 2: Section Header Block Options 780 shb_hardware: 781 The shb_hardware option is a UTF-8 string containing the 782 description of the hardware used to create this section. The 783 string is not zero-terminated. 785 Examples: "x86 Personal Computer", "Sun Sparc Workstation". 787 shb_os: 788 The shb_os option is a UTF-8 string containing the name of 789 the operating system used to create this section. The string 790 is not zero-terminated. 792 Examples: "Windows XP SP2", "openSUSE 10.2". 794 shb_userappl: 795 The shb_userappl option is a UTF-8 string containing the name 796 of the application used to create this section. The string 797 is not zero-terminated. 799 Examples: "dumpcap V0.99.7". 801 [Open issue: does a program which re-writes a capture file change the 802 original hardware/os/application info?] 804 4.2. Interface Description Block 806 An Interface Description Block (IDB) is the container for information 807 describing an interface on which packet data is captured. 809 Tools that write / read the capture file associate an incrementing 810 unsigned 32-bit number (starting from '0') to each Interface 811 Definition Block, called the Interface ID for the interface in 812 question. This number is unique within each Section and identifies 813 the interface to which the IDB refers; it is only unique inside the 814 current section, so, two Sections can have different interfaces 815 identified by the same Interface ID values. This unique identifier 816 is referenced by other blocks, such as Enhanced Packet Blocks and 817 Interface Statistic Blocks, to indicate the interface to which the 818 block refers (such the interface that was used to capture the packet 819 that an Enhanced Packet Block contains or to which the statistics in 820 an Interface Statistic Block refer). 822 There must be an Interface Description Block for each interface to 823 which another block refers. Blocks such as an Enhanced Packet Block 824 or an Interface Statistics Block contain an Interface ID value 825 referring to a particular interface, and a Simple Packet Block 826 implicitly refers to an interface with an Interface ID of 0. If the 827 file does not contain any blocks that use an Interface ID, then the 828 file does not need to have any IDBs. 830 An Interface Description Block is valid only inside the section to 831 which it belongs. The structure of a Interface Description Block is 832 shown in Figure 10. 834 1 2 3 835 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 836 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 837 0 | Block Type = 0x00000001 | 838 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 839 4 | Block Total Length | 840 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 841 8 | LinkType | Reserved | 842 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 843 12 | SnapLen | 844 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 845 16 / / 846 / Options (variable) / 847 / / 848 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 849 | Block Total Length | 850 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 852 Figure 10: Interface Description Block Format 854 The meaning of the fields is: 856 * Block Type: The block type of the Interface Description Block is 857 1. 859 * Block Total Length: total size of this block, as described in 860 Section 3.1. 862 * LinkType (16 bits): an unsigned value that defines the link layer 863 type of this interface. The list of Standardized Link Layer Type 864 codes is available in [LINKTYPES]. 866 * Reserved (16 bits): not used - MUST be filled with 0 by pcapng 867 file writers, and MUST be ignored by pcapng file readers. 869 * SnapLen (32 bits): an unsigned value indicating the maximum number 870 of octets captured from each packet. The portion of each packet 871 that exceeds this value will not be stored in the file. A value 872 of zero indicates no limit. 874 * Options: optionally, a list of options (formatted according to the 875 rules defined in Section 3.5) can be present. 877 In addition to the options defined in Section 3.5, the following 878 options are valid within this block: 880 +================+======+=====================+===================+ 881 | Name | Code | Length | Multiple allowed? | 882 +================+======+=====================+===================+ 883 | if_name | 2 | variable | no | 884 +----------------+------+---------------------+-------------------+ 885 | if_description | 3 | variable | no | 886 +----------------+------+---------------------+-------------------+ 887 | if_IPv4addr | 4 | 8 | yes | 888 +----------------+------+---------------------+-------------------+ 889 | if_IPv6addr | 5 | 17 | yes | 890 +----------------+------+---------------------+-------------------+ 891 | if_MACaddr | 6 | 6 | no | 892 +----------------+------+---------------------+-------------------+ 893 | if_EUIaddr | 7 | 8 | no | 894 +----------------+------+---------------------+-------------------+ 895 | if_speed | 8 | 8 | no | 896 +----------------+------+---------------------+-------------------+ 897 | if_tsresol | 9 | 1 | no | 898 +----------------+------+---------------------+-------------------+ 899 | if_tzone | 10 | 4 | no | 900 +----------------+------+---------------------+-------------------+ 901 | if_filter | 11 | variable, minimum 1 | no | 902 +----------------+------+---------------------+-------------------+ 903 | if_os | 12 | variable | no | 904 +----------------+------+---------------------+-------------------+ 905 | if_fcslen | 13 | 1 | no | 906 +----------------+------+---------------------+-------------------+ 907 | if_tsoffset | 14 | 8 | no | 908 +----------------+------+---------------------+-------------------+ 909 | if_hardware | 15 | variable | no | 910 +----------------+------+---------------------+-------------------+ 911 | if_txspeed | 16 | 8 | no | 912 +----------------+------+---------------------+-------------------+ 913 | if_rxspeed | 17 | 8 | no | 914 +----------------+------+---------------------+-------------------+ 916 Table 3: Interface Description Block Options 918 if_name: 919 The if_name option is a UTF-8 string containing the name of 920 the device used to capture data. The string is not zero- 921 terminated. 923 Examples: "eth0", 924 "\Device\NPF_{AD1CE675-96D0-47C5-ADD0-2504B9126B68}". 926 if_description: 928 The if_description option is a UTF-8 string containing the 929 description of the device used to capture data. The string 930 is not zero-terminated. 932 Examples: "Wi-Fi", "Local Area Connection", "Wireless Network 933 Connection", "First Ethernet Interface". 935 if_IPv4addr: 936 The if_IPv4addr option is an IPv4 network address and 937 corresponding netmask for the interface. The first four 938 octets are the IP address, and the next four octets are the 939 netmask. This option can be repeated multiple times within 940 the same Interface Description Block when multiple IPv4 941 addresses are assigned to the interface. Note that the IP 942 address and netmask are both treated as four octets, one for 943 each octet of the address or mask; they are not 32-bit 944 numbers, and thus the endianness of the SHB does not affect 945 this field's value. 947 Examples: '192 168 1 1 255 255 255 0'. 949 if_IPv6addr: 950 The if_IPv6addr option is an IPv6 network address and 951 corresponding prefix length for the interface. The first 16 952 octets are the IP address and the next octet is the prefix 953 length. This option can be repeated multiple times within 954 the same Interface Description Block when multiple IPv6 955 addresses are assigned to the interface. 957 Example: 2001:0db8:85a3:08d3:1319:8a2e:0370:7344/64 is written (in 958 hex) as '20 01 0d b8 85 a3 08 d3 13 19 8a 2e 03 70 73 44 40'. 960 if_MACaddr: 961 The if_MACaddr option is the Interface Hardware MAC address 962 (48 bits), if available. 964 Example: '00 01 02 03 04 05'. 966 if_EUIaddr: 967 The if_EUIaddr option is the Interface Hardware EUI address 968 (64 bits), if available. 970 Example: '02 34 56 FF FE 78 9A BC'. 972 if_speed: 973 The if_speed option is a 64-bit unsigned value indicating the 974 interface speed, in bits per second. 976 Example: the 64-bit decimal number 100000000 for 100Mbps. 978 if_tsresol: 979 The if_tsresol option identifies the resolution of 980 timestamps. If the Most Significant Bit is equal to zero, 981 the remaining bits indicates the resolution of the timestamp 982 as a negative power of 10 (e.g. 6 means microsecond 983 resolution, timestamps are the number of microseconds since 984 1970-01-01 00:00:00 UTC). If the Most Significant Bit is 985 equal to one, the remaining bits indicates the resolution as 986 negative power of 2 (e.g. 10 means 1/1024 of second). If 987 this option is not present, a resolution of 10^-6 is assumed 988 (i.e. timestamps have the same resolution of the standard 989 'libpcap' timestamps). 991 Example: '6'. 993 if_tzone: 994 The if_tzone option identifies the time zone for GMT support 995 (TODO: specify better). 997 Example: TODO: give a good example. 999 if_filter: 1000 The if_filter option identifies the filter (e.g. "capture 1001 only TCP traffic") used to capture traffic. The first octet 1002 of the Option Data keeps a code of the filter used (e.g. if 1003 this is a libpcap string, or BPF bytecode, and more). More 1004 details about this format will be presented in Appendix XXX 1005 (TODO). (TODO: better use different options for different 1006 fields? e.g. if_filter_pcap, if_filter_bpf, ...) 1008 Example: '00'"tcp port 23 and host 192.0.2.5". 1010 if_os: 1011 The if_os option is a UTF-8 string containing the name of the 1012 operating system of the machine in which this interface is 1013 installed. This can be different from the same information 1014 that can be contained by the Section Header Block 1015 (Section 4.1) because the capture can have been done on a 1016 remote machine. The string is not zero-terminated. 1018 Examples: "Windows XP SP2", "openSUSE 10.2". 1020 if_fcslen: 1021 The if_fcslen option is an 8-bit unsigned integer value that 1022 specifies the length of the Frame Check Sequence (in bits) 1023 for this interface. For link layers whose FCS length can 1024 change during time, the Enhanced Packet Block epb_flags 1025 Option can be used in each Enhanced Packet Block (see 1026 Section 4.3.1). 1028 Example: '4'. 1030 if_tsoffset: 1031 The if_tsoffset option is a 64-bit signed integer value that 1032 specifies an offset (in seconds) that must be added to the 1033 timestamp of each packet to obtain the absolute timestamp of 1034 a packet. If the option is missing, the timestamps stored in 1035 the packet MUST be considered absolute timestamps. The time 1036 zone of the offset can be specified with the option if_tzone. 1037 TODO: won't a if_tsoffset_low for fractional second offsets 1038 be useful for highly synchronized capture systems? 1040 Example: '1234'. 1042 if_hardware: 1043 The if_hardware option is a UTF-8 string containing the 1044 description of the interface hardware. The string is not 1045 zero-terminated. 1047 Examples: "Broadcom NetXtreme", "Intel(R) PRO/1000 MT Network 1048 Connection", "NETGEAR WNA1000Mv2 N150 Wireless USB Micro Adapter". 1050 if_txspeed: 1051 The if_txrxspeeds option is a 64-bit unsigned value 1052 indicating the interface transmit speed in bits per second. 1054 Example: the 64-bit decimal number 1024000 for 1024Kbps. 1056 if_rxspeed: 1057 The if_rxspeed option is a 64-bit unsigned value indicating 1058 the interface receive speed, in bits per second. 1060 Example: the 64-bit decimal number 8192000 for 8192Kbps. 1062 If the interface transmit speed and receive speed are the same, the 1063 if_speed option MUST be used and the if_txspeed and if_rxspeed 1064 options MUST NOT be used. If the transmit speed is unknown, the 1065 if_speed and if_txspeed options MUST NOT be used; if the receive 1066 speed is unknown, the if_speed and if_rxspeed options MUST NOT be 1067 used. 1069 4.3. Enhanced Packet Block 1071 An Enhanced Packet Block (EPB) is the standard container for storing 1072 the packets coming from the network. The Enhanced Packet Block is 1073 optional because packets can be stored either by means of this block 1074 or the Simple Packet Block, which can be used to speed up capture 1075 file generation; or a file may have no packets in it. The format of 1076 an Enhanced Packet Block is shown in Figure 11. 1078 The Enhanced Packet Block is an improvement over the original, now 1079 obsolete, Packet Block (Appendix A): 1081 * it stores the Interface Identifier as a 32-bit integer value. 1082 This is a requirement when a capture stores packets coming from a 1083 large number of interfaces; 1085 * unlike the Packet Block (Appendix A), the number of packets 1086 dropped by the capture system between this packet and the previous 1087 one is not stored in the header, but rather in an option of the 1088 block itself. 1090 1 2 3 1091 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 1092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1093 0 | Block Type = 0x00000006 | 1094 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1095 4 | Block Total Length | 1096 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1097 8 | Interface ID | 1098 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1099 12 | Timestamp (High) | 1100 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1101 16 | Timestamp (Low) | 1102 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1103 20 | Captured Packet Length | 1104 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1105 24 | Original Packet Length | 1106 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1107 28 / / 1108 / Packet Data / 1109 / variable length, padded to 32 bits / 1110 / / 1111 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1112 / / 1113 / Options (variable) / 1114 / / 1115 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1116 | Block Total Length | 1117 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1119 Figure 11: Enhanced Packet Block Format 1121 The Enhanced Packet Block has the following fields: 1123 * Block Type: The block type of the Enhanced Packet Block is 6. 1125 * Block Total Length: total size of this block, as described in 1126 Section 3.1. 1128 * Interface ID (32 bits): an unsigned value that specifies the 1129 interface on which this packet was received or transmitted; the 1130 correct interface will be the one whose Interface Description 1131 Block (within the current Section of the file) is identified by 1132 the same number (see Section 4.2) of this field. The interface ID 1133 MUST be valid, which means that an matching interface description 1134 block MUST exist. 1136 * Timestamp (High) and Timestamp (Low): upper 32 bits and lower 32 1137 bits of a 64-bit timestamp. The timestamp is a single 64-bit 1138 unsigned integer that represents the number of units of time that 1139 have elapsed since 1970-01-01 00:00:00 UTC. The length of a unit 1140 of time is specified by the 'if_tsresol' option (see Figure 10) of 1141 the Interface Description Block referenced by this packet. Note 1142 that, unlike timestamps in the libpcap file format, timestamps in 1143 Enhanced Packet Blocks are not saved as two 32-bit values that 1144 represent the seconds and microseconds that have elapsed since 1145 1970-01-01 00:00:00 UTC. Timestamps in Enhanced Packet Blocks are 1146 saved as two 32-bit words that represent the upper and lower 32 1147 bits of a single 64-bit quantity. 1149 * Captured Packet Length (32 bits): an unsigned value that indicates 1150 the number of octets captured from the packet (i.e. the length of 1151 the Packet Data field). It will be the minimum value among the 1152 Original Packet Length and the snapshot length for the interface 1153 (SnapLen, defined in Figure 10). The value of this field does not 1154 include the padding octets added at the end of the Packet Data 1155 field to align the Packet Data field to a 32-bit boundary. 1157 * Original Packet Length (32 bits): an unsigned value that indicates 1158 the actual length of the packet when it was transmitted on the 1159 network. It can be different from the Captured Packet Length if 1160 the packet has been truncated by the capture process. 1162 * Packet Data: the data coming from the network, including link- 1163 layer headers. The actual length of this field is Captured Packet 1164 Length plus the padding to a 32-bit boundary. The format of the 1165 link-layer headers depends on the LinkType field specified in the 1166 Interface Description Block (see Section 4.2) and it is specified 1167 in the entry for that format in [LINKTYPES]. 1169 * Options: optionally, a list of options (formatted according to the 1170 rules defined in Section 3.5) can be present. 1172 In addition to the options defined in Section 3.5, the following 1173 options are valid within this block: 1175 +===============+======+========================+===================+ 1176 | Name | Code | Length | Multiple | 1177 | | | | allowed? | 1178 +===============+======+========================+===================+ 1179 | epb_flags | 2 | 4 | no | 1180 +---------------+------+------------------------+-------------------+ 1181 | epb_hash | 3 | variable, minimum hash | yes | 1182 | | | type-dependent | | 1183 +---------------+------+------------------------+-------------------+ 1184 | epb_dropcount | 4 | 8 | no | 1185 +---------------+------+------------------------+-------------------+ 1186 | epb_packetid | 5 | 8 | no | 1187 +---------------+------+------------------------+-------------------+ 1188 | epb_queue | 6 | 4 | no | 1189 +---------------+------+------------------------+-------------------+ 1190 | epb_verdict | 7 | variable, minimum | yes | 1191 | | | verdict type-dependent | | 1192 +---------------+------+------------------------+-------------------+ 1194 Table 4: Enhanced Packet Block Options 1196 epb_flags: 1197 The epb_flags option is a 32-bit flags word containing link- 1198 layer information. A complete specification of the allowed 1199 flags can be found in Section 4.3.1. 1201 Example: '0'. 1203 epb_hash: 1204 The epb_hash option contains a hash of the packet. The first 1205 octet specifies the hashing algorithm, while the following 1206 octets contain the actual hash, whose size depends on the 1207 hashing algorithm, and hence from the value in the first 1208 octet. The hashing algorithm can be: 2s complement 1209 (algorithm octet = 0, size = XXX), XOR (algorithm octet = 1, 1210 size=XXX), CRC32 (algorithm octet = 2, size = 4), MD-5 1211 (algorithm octet = 3, size = 16), SHA-1 (algorithm octet = 4, 1212 size = 20), Toeplitz (algorithm octet = 5, size = 4). The 1213 hash covers only the packet, not the header added by the 1214 capture driver: this gives the possibility to calculate it 1215 inside the network card. The hash allows easier comparison/ 1216 merging of different capture files, and reliable data 1217 transfer between the data acquisition system and the capture 1218 library. 1220 Examples: '02 EC 1D 87 97', '03 45 6E C2 17 7C 10 1E 3C 2E 99 6E C2 1221 9A 3D 50 8E'. 1223 epb_dropcount: 1224 The epb_dropcount option is a 64-bit unsigned integer value 1225 specifying the number of packets lost (by the interface and 1226 the operating system) between this packet and the preceding 1227 one for the same interface or, for the first packet for an 1228 interface, between this packet and the start of the capture 1229 process. 1231 Example: '0'. 1233 epb_packetid: 1234 The epb_packetid option is a 64-bit unsigned integer that 1235 uniquely identifies the packet. If the same packet is seen 1236 by multiple interfaces and there is a way for the capture 1237 application to correlate them, the same epb_packetid value 1238 must be used. An example could be a router that captures 1239 packets on all its interfaces in both directions. When a 1240 packet hits interface A on ingress, an EPB entry gets 1241 created, TTL gets decremented, and right before it egresses 1242 on interface B another EPB entry gets created in the trace 1243 file. In this case, two packets are in the capture file, 1244 which are not identical but the epb_packetid can be used to 1245 correlate them. 1247 Example: '0'. 1249 epb_queue: 1250 The epb_queue option is a 32-bit unsigned integer that 1251 identifies on which queue of the interface the specific 1252 packet was received. 1254 Example: '0'. 1256 epb_verdict: 1257 The epb_verdict option stores a verdict of the packet. The 1258 verdict indicates what would be done with the packet after 1259 processing it. For example, a firewall could drop the 1260 packet. This verdict can be set by various components, i.e. 1261 Hardware, Linux's eBPF TC or XDP framework, etc. etc. The 1262 first octet specifies the verdict type, while the following 1263 octets contain the actual verdict data, whose size depends on 1264 the verdict type, and hence from the value in the first 1265 octet. The verdict type can be: Hardware (type octet = 0, 1266 size = variable), Linux_eBPF_TC (type octet = 1, size = 8 1267 (64-bit unsigned integer), value = TC_ACT_* as defined in the 1268 Linux pck_cls.h (https://git.kernel.org/pub/scm/linux/kernel/ 1269 git/torvalds/linux.git/tree/include/uapi/linux/pkt_cls.h) 1270 include), Linux_eBPF_XDP (type octet = 2, size = 8 (64-bit 1271 unsigned integer), value = xdp_action as defined in the Linux 1272 pbf.h (https://git.kernel.org/pub/scm/linux/kernel/git/torval 1273 ds/linux.git/tree/include/uapi/linux/bpf.h) include). 1275 Example: '02 00 00 00 00 00 00 00 02' for Linux_eBPF_XDP with verdict 1276 XDP_PASS. 1278 4.3.1. Enhanced Packet Block Flags Word 1280 The Enhanced Packet Block Flags Word is a 32-bit value that contains 1281 link-layer information about the packet. 1283 The word is encoded as an unsigned 32-bit integer, using the 1284 endianness of the Section Header Block scope it is in. In the 1285 following table, the bits are numbered with 0 being the least- 1286 significant bit and 31 being the most-significant bit of the 32-bit 1287 unsigned integer. The meaning of the bits is the following: 1289 +========+======================================================+ 1290 | Bit | Description | 1291 | Number | | 1292 +========+======================================================+ 1293 | 0-1 | Inbound / Outbound packet (00 = information not | 1294 | | available, 01 = inbound, 10 = outbound) | 1295 +--------+------------------------------------------------------+ 1296 | 2-4 | Reception type (000 = not specified, 001 = unicast, | 1297 | | 010 = multicast, 011 = broadcast, 100 = | 1298 | | promiscuous). | 1299 +--------+------------------------------------------------------+ 1300 | 5-8 | FCS length, in octets (0000 if this information is | 1301 | | not available). This value overrides the if_fcslen | 1302 | | option of the Interface Description Block, and is | 1303 | | used with those link layers (e.g. PPP) where the | 1304 | | length of the FCS can change during time. | 1305 +--------+------------------------------------------------------+ 1306 | 9-15 | Reserved (MUST be set to zero). | 1307 +--------+------------------------------------------------------+ 1308 | 16-31 | link-layer-dependent errors (Bit 31 = symbol error, | 1309 | | Bit 30 = preamble error, Bit 29 = Start Frame | 1310 | | Delimiter error, Bit 28 = unaligned frame error, Bit | 1311 | | 27 = wrong Inter Frame Gap error, Bit 26 = packet | 1312 | | too short error, Bit 25 = packet too long error, Bit | 1313 | | 24 = CRC error, other?? are 16 bit enough?). | 1314 +--------+------------------------------------------------------+ 1316 Table 5 1318 NOTE: in earlier versions of this specification, the bits were 1319 specified as being numbered with 0 being the most-significant bit and 1320 31 being the least-significant bit of the 32-bit unsigned integer, 1321 rather than with 0 being the least-significant bit and 31 being the 1322 most-significant bit. Several implementations number the bits with 0 1323 being the least-significant bit, and no known implementations number 1324 them with 0 being the most-significant bit, so the specification was 1325 changed to reflect that reality. 1327 4.4. Simple Packet Block 1329 The Simple Packet Block (SPB) is a lightweight container for storing 1330 the packets coming from the network. Its presence is optional. 1332 A Simple Packet Block is similar to an Enhanced Packet Block (see 1333 Section 4.3), but it is smaller, simpler to process and contains only 1334 a minimal set of information. This block is preferred to the 1335 standard Enhanced Packet Block when performance or space occupation 1336 are critical factors, such as in sustained traffic capture 1337 applications. A capture file can contain both Enhanced Packet Blocks 1338 and Simple Packet Blocks: for example, a capture tool could switch 1339 from Enhanced Packet Blocks to Simple Packet Blocks when the hardware 1340 resources become critical. 1342 The Simple Packet Block does not contain the Interface ID field. 1343 Therefore, it MUST be assumed that all the Simple Packet Blocks have 1344 been captured on the interface previously specified in the first 1345 Interface Description Block. 1347 Figure 12 shows the format of the Simple Packet Block. 1349 1 2 3 1350 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 1351 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1352 0 | Block Type = 0x00000003 | 1353 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1354 4 | Block Total Length | 1355 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1356 8 | Original Packet Length | 1357 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1358 12 / / 1359 / Packet Data / 1360 / variable length, padded to 32 bits / 1361 / / 1362 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1363 | Block Total Length | 1364 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1365 Figure 12: Simple Packet Block Format 1367 The Simple Packet Block has the following fields: 1369 * Block Type: The block type of the Simple Packet Block is 3. 1371 * Block Total Length: total size of this block, as described in 1372 Section 3.1. 1374 * Original Packet Length (32 bits): an unsigned value indicating the 1375 actual length of the packet when it was transmitted on the 1376 network. It can be different from length of the Packet Data 1377 field's length if the packet has been truncated by the capture 1378 process, in which case the SnapLen value in Section 4.2 will be 1379 less than this Original Packet Length value, and the SnapLen value 1380 MUST be used to determine the size of the Packet Data field 1381 length. 1383 * Packet Data: the data coming from the network, including link- 1384 layer headers. The length of this field can be derived from the 1385 field Block Total Length, present in the Block Header, and it is 1386 the minimum value among the SnapLen (present in the Interface 1387 Description Block) and the Original Packet Length (present in this 1388 header). The format of the data within this Packet Data field 1389 depends on the LinkType field specified in the Interface 1390 Description Block (see Section 4.2) and it is specified in the 1391 entry for that format in [LINKTYPES]. 1393 The Simple Packet Block does not contain the timestamp because this 1394 is often one of the most costly operations on PCs. Additionally, 1395 there are applications that do not require it; e.g. an Intrusion 1396 Detection System is interested in packets, not in their timestamp. 1398 A Simple Packet Block cannot be present in a Section that has more 1399 than one interface because of the impossibility to refer to the 1400 correct one (it does not contain any Interface ID field). 1402 The Simple Packet Block is very efficient in term of disk space: a 1403 snapshot whose length is 100 octets requires only 16 octets of 1404 overhead, which corresponds to an efficiency of more than 86%. 1406 4.5. Name Resolution Block 1408 The Name Resolution Block (NRB) is used to support the correlation of 1409 numeric addresses (present in the captured packets) and their 1410 corresponding canonical names and it is optional. Having the literal 1411 names saved in the file prevents the need for performing name 1412 resolution at a later time, when the association between names and 1413 addresses may be different from the one in use at capture time. 1414 Moreover, the NRB avoids the need for issuing a lot of DNS requests 1415 every time the trace capture is opened, and also provides name 1416 resolution when reading the capture with a machine not connected to 1417 the network. 1419 A Name Resolution Block is often placed at the beginning of the file, 1420 but no assumptions can be taken about its position. Multiple NRBs 1421 can exist in a pcapng file, either due to memory constraints or 1422 because additional name resolutions were performed by file processing 1423 tools, like network analyzers. 1425 A Name Resolution Block need not contain any Records, except the 1426 nrb_record_end Record which MUST be the last Record. The addresses 1427 and names in NRB Records MAY be repeated multiple times; i.e., the 1428 same IP address may resolve to multiple names, the same name may 1429 resolve to the multiple IP addresses, and even the same address-to- 1430 name pair may appear multiple times, in the same NRB or across NRBs. 1432 The format of the Name Resolution Block is shown in Figure 13. 1434 1 2 3 1435 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 1436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1437 0 | Block Type = 0x00000004 | 1438 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1439 4 | Block Total Length | 1440 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1441 8 | Record Type | Record Value Length | 1442 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1443 12 / Record Value / 1444 / variable length, padded to 32 bits / 1445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1446 . . 1447 . . . . other records . . . . 1448 . . 1449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1450 | Record Type = nrb_record_end | Record Value Length = 0 | 1451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1452 / / 1453 / Options (variable) / 1454 / / 1455 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1456 | Block Total Length | 1457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1459 Figure 13: Name Resolution Block Format 1461 The Name Resolution Block has the following fields: 1463 * Block Type: The block type of the Name Resolution Block is 4. 1465 * Block Total Length: total size of this block, as described in 1466 Section 3.1. 1468 This is followed by zero or more Name Resolution Records (in the TLV 1469 format), each of which contains an association between a network 1470 address and a name. An nrb_record_end MUST be added after the last 1471 Record, and MUST exist even if there are no other Records in the NRB. 1472 There are currently three possible types of records: 1474 +=================+========+==========+ 1475 | Name | Code | Length | 1476 +=================+========+==========+ 1477 | nrb_record_end | 0x0000 | 0 | 1478 +-----------------+--------+----------+ 1479 | nrb_record_ipv4 | 0x0001 | variable | 1480 +-----------------+--------+----------+ 1481 | nrb_record_ipv6 | 0x0002 | variable | 1482 +-----------------+--------+----------+ 1484 Table 6: Name Resolution Block Records 1486 nrb_record_end: 1487 The nrb_record_end record delimits the end of name resolution 1488 records. This record is needed to determine when the list of 1489 name resolution records has ended and some options (if any) 1490 begin. 1492 nrb_record_ipv4: 1493 The nrb_record_ipv4 record specifies an IPv4 address 1494 (contained in the first 4 octets), followed by one or more 1495 zero-terminated UTF-8 strings containing the DNS entries for 1496 that address. The minimum valid Record Length for this 1497 Record Type is thus 6: 4 for the IP octets, 1 character, and 1498 a zero-value octet terminator. Note that the IP address is 1499 treated as four octets, one for each octet of the IP address; 1500 it is not a 32-bit word, and thus the endianness of the SHB 1501 does not affect this field's value. 1503 Example: '127 0 0 1'"localhost". 1505 [Open issue: is an empty string (i.e., just a zero-value octet) 1506 valid?] 1508 nrb_record_ipv6: 1509 The nrb_record_ipv6 record specifies an IPv6 address 1510 (contained in the first 16 octets), followed by one or more 1511 zero-terminated strings containing the DNS entries for that 1512 address. The minimum valid Record Length for this Record 1513 Type is thus 18: 16 for the IP octets, 1 character, and a 1514 zero-value octet terminator. 1516 Example: '20 01 0d b8 00 00 00 00 00 00 00 00 12 34 56 78'"somehost". 1518 [Open issue: is an empty string (i.e., just a zero-value octet) 1519 valid?] 1520 Record Types other than those specified earlier MUST be ignored and 1521 skipped past. More Record Types will likely be defined in the 1522 future, and MUST NOT break backwards compatibility. 1524 Each Record Value is aligned to and padded to a 32-bit boundary. The 1525 corresponding Record Value Length reflects the actual length of the 1526 Record Value; it does not include the lengths of the Record Type 1527 field, the Record Value Length field, any padding for the Record 1528 Value, or anything after the Record Value. For Record Types with 1529 name strings, the Record Length does include the zero-value octet 1530 terminating that string. A Record Length of 0 is valid, unless 1531 indicated otherwise. 1533 After the list of Name Resolution Records, optionally, a list of 1534 options (formatted according to the rules defined in Section 3.5) can 1535 be present. 1537 In addition to the options defined in Section 3.5, the following 1538 options are valid within this block: 1540 +===============+======+==========+===================+ 1541 | Name | Code | Length | Multiple allowed? | 1542 +===============+======+==========+===================+ 1543 | ns_dnsname | 2 | variable | no | 1544 +---------------+------+----------+-------------------+ 1545 | ns_dnsIP4addr | 3 | 4 | no | 1546 +---------------+------+----------+-------------------+ 1547 | ns_dnsIP6addr | 4 | 16 | no | 1548 +---------------+------+----------+-------------------+ 1550 Table 7: Name Resolution Block Options 1552 ns_dnsname: 1553 The ns_dnsname option is a UTF-8 string containing the name 1554 of the machine (DNS server) used to perform the name 1555 resolution. The string is not zero-terminated. 1557 Example: "our_nameserver". 1559 ns_dnsIP4addr: 1560 The ns_dnsIP4addr option specifies the IPv4 address of the 1561 DNS server. Note that the IP address is treated as four 1562 octets, one for each octet of the IP address; it is not a 1563 32-bit word, and thus the endianness of the SHB does not 1564 affect this field's value. 1566 Example: '192 168 0 1'. 1568 ns_dnsIP6addr: 1569 The ns_dnsIP6addr option specifies the IPv6 address of the 1570 DNS server. 1572 Example: '20 01 0d b8 00 00 00 00 00 00 00 00 12 34 56 78'. 1574 4.6. Interface Statistics Block 1576 The Interface Statistics Block (ISB) contains the capture statistics 1577 for a given interface and it is optional. The statistics are 1578 referred to the interface defined in the current Section identified 1579 by the Interface ID field. An Interface Statistics Block is normally 1580 placed at the end of the file, but no assumptions can be taken about 1581 its position - it can even appear multiple times for the same 1582 interface. 1584 The format of the Interface Statistics Block is shown in Figure 14. 1586 1 2 3 1587 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 1588 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1589 0 | Block Type = 0x00000005 | 1590 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1591 4 | Block Total Length | 1592 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1593 8 | Interface ID | 1594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1595 12 | Timestamp (High) | 1596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1597 16 | Timestamp (Low) | 1598 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1599 20 / / 1600 / Options (variable) / 1601 / / 1602 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1603 | Block Total Length | 1604 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1606 Figure 14: Interface Statistics Block Format 1608 The fields have the following meaning: 1610 * Block Type: The block type of the Interface Statistics Block is 5. 1612 * Block Total Length: total size of this block, as described in 1613 Section 3.1. 1615 * Interface ID: specifies the interface these statistics refers to; 1616 the correct interface will be the one whose Interface Description 1617 Block (within the current Section of the file) is identified by 1618 same number (see Section 4.2) of this field. 1620 * Timestamp: time this statistics refers to. The format of the 1621 timestamp is the same already defined in the Enhanced Packet Block 1622 (Section 4.3); the length of a unit of time is specified by the 1623 'if_tsresol' option (see Figure 10) of the Interface Description 1624 Block referenced by this packet. 1626 * Options: optionally, a list of options (formatted according to the 1627 rules defined in Section 3.5) can be present. 1629 All the statistic fields are defined as options in order to deal with 1630 systems that do not have a complete set of statistics. Therefore, In 1631 addition to the options defined in Section 3.5, the following options 1632 are valid within this block: 1634 +==================+======+========+===================+ 1635 | Name | Code | Length | Multiple allowed? | 1636 +==================+======+========+===================+ 1637 | isb_starttime | 2 | 8 | no | 1638 +------------------+------+--------+-------------------+ 1639 | isb_endtime | 3 | 8 | no | 1640 +------------------+------+--------+-------------------+ 1641 | isb_ifrecv | 4 | 8 | no | 1642 +------------------+------+--------+-------------------+ 1643 | isb_ifdrop | 5 | 8 | no | 1644 +------------------+------+--------+-------------------+ 1645 | isb_filteraccept | 6 | 8 | no | 1646 +------------------+------+--------+-------------------+ 1647 | isb_osdrop | 7 | 8 | no | 1648 +------------------+------+--------+-------------------+ 1649 | isb_usrdeliv | 8 | 8 | no | 1650 +------------------+------+--------+-------------------+ 1652 Table 8: Interface Statistics Block Options 1654 isb_starttime: 1655 The isb_starttime option specifies the time the capture 1656 started; time will be stored in two blocks of four octets 1657 each. The format of the timestamp is the same as the one 1658 defined in the Enhanced Packet Block (Section 4.3); the 1659 length of a unit of time is specified by the 'if_tsresol' 1660 option (see Figure 10) of the Interface Description Block 1661 referenced by this packet. 1663 Example: '96 c3 04 00 73 89 6a 65', in Little Endian, decodes to 1664 2012-06-29 06:17:00.834163 UTC. 1666 isb_endtime: 1667 The isb_endtime option specifies the time the capture ended; 1668 time will be stored in two blocks of four octets each. The 1669 format of the timestamp is the same as the one defined in the 1670 Enhanced Packet Block (Section 4.3); the length of a unit of 1671 time is specified by the 'if_tsresol' option (see Figure 10) 1672 of the Interface Description Block referenced by this packet. 1674 Example: '97 c3 04 00 aa 47 ca 64', in Little Endian, decodes to 1675 2012-06-29 07:28:25.298858 UTC. 1677 isb_ifrecv: 1678 The isb_ifrecv option specifies the 64-bit unsigned integer 1679 number of packets received from the physical interface 1680 starting from the beginning of the capture. 1682 Example: the decimal number 100. 1684 isb_ifdrop: 1685 The isb_ifdrop option specifies the 64-bit unsigned integer 1686 number of packets dropped by the interface due to lack of 1687 resources starting from the beginning of the capture. 1689 Example: '0'. 1691 isb_filteraccept: 1692 The isb_filteraccept option specifies the 64-bit unsigned 1693 integer number of packets accepted by filter starting from 1694 the beginning of the capture. 1696 Example: the decimal number 100. 1698 isb_osdrop: 1699 The isb_osdrop option specifies the 64-bit unsigned integer 1700 number of packets dropped by the operating system starting 1701 from the beginning of the capture. 1703 Example: '0'. 1705 isb_usrdeliv: 1707 The isb_usrdeliv option specifies the 64-bit unsigned integer 1708 number of packets delivered to the user starting from the 1709 beginning of the capture. The value contained in this field 1710 can be different from the value 'isb_filteraccept - 1711 isb_osdrop' because some packets could still be in the OS 1712 buffers when the capture ended. 1714 Example: '0'. 1716 All the fields that refer to packet counters are 64-bit values, 1717 represented with the octet order of the current section. Special 1718 care must be taken in accessing these fields: since all the blocks 1719 are aligned to a 32-bit boundary, such fields are not guaranteed to 1720 be aligned on a 64-bit boundary. 1722 4.7. Decryption Secrets Block 1724 A Decryption Secrets Block (DSB) stores (session) secrets that enable 1725 decryption of packets within the capture file. The format of these 1726 secrets is defined by the Secrets Type. 1728 Multiple DSBs can exist in a pcapng file, but they SHOULD be written 1729 before packet blocks that require those secrets. Tools MAY limit 1730 decryption to secrets that appear before packet blocks. 1732 The structure of a Decryption Secrets Block is shown in Figure 15. 1734 1 2 3 1735 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 1736 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1737 0 | Block Type = 0x0000000A | 1738 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1739 4 | Block Total Length | 1740 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1741 8 | Secrets Type | 1742 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1743 12 | Secrets Length | 1744 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1745 16 / / 1746 / Secrets Data / 1747 / (variable length, padded to 32 bits) / 1748 / / 1749 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1750 / / 1751 / Options (variable) / 1752 / / 1753 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1754 / Block Total Length / 1755 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1757 Figure 15: Decryption Secrets Block Format 1759 The Decryption Secrets Block has the following fields. 1761 * Block Type: The block type of the Decryption Secrets Block is 10. 1763 * Block Total Length: total size of this block, as described in 1764 Section 3.1. 1766 * Secrets Type (32 bits): an unsigned integer identifier that 1767 describes the format of the following Secrets field. Requests for 1768 new Secrets Type codes should be made by creating a pull request 1769 to update this document as described in Section 10.1. 1771 * Secrets Length (32 bits): an unsigned integer that indicates the 1772 size of the following Secrets field, without any padding octets. 1774 * Secrets Data: binary data containing secrets, padded to a 32 bit 1775 boundary. 1777 * Options: optionally, a list of options (formatted according to the 1778 rules defined in Section 3.5) can be present. No DSB-specific 1779 options are currently defined. 1781 The following is a list of Secrets Types. 1783 0x544c534b: 1784 TLS Key Log. This format is described at NSS Key Log Format 1785 (https://developer.mozilla.org/en- 1786 US/docs/Mozilla/Projects/NSS/Key_Log_Format). Every line 1787 MUST be properly terminated with either carriage return and 1788 linefeed ('\r\n') or linefeed ('\n'). Tools MUST be able to 1789 handle both line endings. 1791 0x57474b4c: 1792 WireGuard Key Log. Every line consists of the key type, 1793 equals sign ('='), and the base64-encoded 32-byte key with 1794 optional spaces before and in between. The key type is one 1795 of LOCAL_STATIC_PRIVATE_KEY, REMOTE_STATIC_PUBLIC_KEY, 1796 LOCAL_EPHEMERAL_PRIVATE_KEY, or PRESHARED|_KEY. This matches 1797 the output of extract-handshakes.sh 1798 (https://git.zx2c4.com/WireGuard/tree/contrib/examples/ 1799 extract-handshakes/README), which is part of the WireGuard 1800 (https://www.wireguard.com/) project. A PRESHARED_KEY line 1801 is linked to a session matched by a previous 1802 LOCAL_EPHEMERAL_PRIVATE_KEY line. Every line MUST be 1803 properly terminated with either carriage return and linefeed 1804 ('\r\n') or linefeed ('\n'). Tools MUST be able to handle 1805 both line endings. 1807 Warning: LOCAL_STATIC_PRIVATE_KEY and potentially PRESHARED_KEY are 1808 long-term secrets, users SHOULD only store non-production keys, or 1809 ensure proper protection of the pcapng file. 1811 0x5a4e574b: 1812 ZigBee NWK Key and ZigBee PANID for that network. Network 1813 Key as described in the ZigBee Specification 1814 (https://zigbeealliance.org/) 05-3473-21 (R21) section 4.2.2. 1815 The NWK Key is a 16 octet binary AES-128 key used to secure 1816 NWK Level frames within a single PAN. The NWK key is 1817 immediately followed by the 2 octet (16 bit) network PANID in 1818 little endian format. If and when the NWK Key changes a new 1819 DSB will contain the new NWK Key. 1821 0x5a415053: 1822 ZigBee APS Key. Application Support Link Key as described in 1823 the ZigBee Specification (https://zigbeealliance.org/) 1824 05-3473-21 (R21) section 4.4. Each 16 octet binary AES-128 1825 key secures frames exchanged between a pair of network nodes. 1826 The APS Key is immediately followed by the 2 octet (16 bit) 1827 network PANID in little endian format. The PANID is followed 1828 by the 2 octet (16 bit) short addresses, in little endian 1829 format, of the nodes to which the APS Key applies. The 1830 numerically lower short address shall come first. There is a 1831 APS Key DSB for each node pair for which the Link Key is 1832 known. As new links are formed, new DSBs contain the new 1833 Keys. If the APS Key changes for an existing link, it is 1834 contained in a new DSB with the new APS Key. 1836 0 1 2 3 1837 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 1838 +---------------------------------------------------------------+ 1839 0 | Block Type = 0x0000000A | 1840 +---------------------------------------------------------------+ 1841 4 | Block Total Length | 1842 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1843 8 | Secrets Type = 0x5a4e574b | 1844 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1845 12 | Secrets Length | 1846 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1847 16 | AES-128 | 1848 | NKW Key | 1849 | (16 octets) | 1850 | (128 bits) | 1851 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1852 32 | PAN ID | padding (0) | 1853 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1854 36 / / 1855 / Options (variable) / 1856 / / 1857 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1858 / Block Total Length / 1859 +---------------------------------------------------------------+ 1861 Figure 16: ZigBee NWK Key Data Format 1863 0 1 2 3 1864 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 1865 +---------------------------------------------------------------+ 1866 0 | Block Type = 0x0000000A | 1867 +---------------------------------------------------------------+ 1868 4 | Block Total Length | 1869 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1870 8 | Secrets Type = 0x5a415053 | 1871 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1872 12 | Secrets Length | 1873 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1874 16 | AES-128 | 1875 | APS Key | 1876 | (16 octets) | 1877 | (128 bits) | 1878 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1879 32 | PAN ID | Low Node Short Address | 1880 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1881 36 | High Node Short Address | padding (0) | 1882 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1883 40 / / 1884 / Options (variable) / 1885 / / 1886 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1887 / Block Total Length / 1888 +---------------------------------------------------------------+ 1890 Figure 17: ZigBee APS Key Data Format 1892 4.8. Custom Block 1894 A Custom Block (CB) is the container for storing custom data that is 1895 not part of another block; for storing custom data as part of another 1896 block, see Section 3.5.1. The Custom Block is optional, can be 1897 repeated any number of times, and can appear before or after any 1898 other block except the first Section Header Block which must come 1899 first in the file. Different Custom Blocks, of different type codes 1900 and/or different Private Enterprise Numbers, may be used in the same 1901 pcapng file. The format of a Custom Block is shown in Figure 18. 1903 1 2 3 1904 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 1905 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1906 0 | Block Type = 0x00000BAD or 0x40000BAD | 1907 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1908 4 | Block Total Length | 1909 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1910 8 | Private Enterprise Number (PEN) | 1911 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1912 12 / / 1913 / Custom Data / 1914 / variable length, padded to 32 bits / 1915 / / 1916 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1917 / / 1918 / Options (variable) / 1919 / / 1920 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1921 | Block Total Length | 1922 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1924 Figure 18: Custom Block Format 1926 The Custom Block uses the type code 0x00000BAD (2989 in decimal) for 1927 a custom block that pcapng re-writers can copy into new files, and 1928 the type code 0x40000BAD (1073744813 in decimal) for one that should 1929 not be copied. See Section 5.2 for details. 1931 The Custom Block has the following fields: 1933 * Block Type: The block type of the Custom Block is 0x00000BAD or 1934 0x40000BAD, as described previously. 1936 * Block Total Length: total size of this block, as described in 1937 Section 3.1. 1939 * Private Enterprise Number (32 bits): An IANA-assigned Private 1940 Enterprise Number identifying the organization which defined the 1941 Custom Block. See Section 5.1 for details. The PEN MUST be 1942 encoded using the same endianness as the Section Header Block it 1943 is within the scope of. 1945 * Custom Data: the custom data, padded to a 32 bit boundary. 1947 * Options: optionally, a list of options (formatted according to the 1948 rules defined in Section 3.5) can be present. Note that custom 1949 options for the Custom Block still use the custom option format 1950 and type code, as described in Section 3.5.1. 1952 5. Vendor-Specific Custom Extensions 1954 This section uses the term "vendor" to describe an organization which 1955 extends the pcapng file with custom, proprietary blocks or options. 1956 It should be noted, however, that the "vendor" is just an abstract 1957 entity that agrees on a custom extension format: for example it may 1958 be a manufacturer, industry association, an individual user, or 1959 collective group of users. 1961 5.1. Supported Use-Cases 1963 There are two different supported use-cases for vendor-specific 1964 custom extensions: local and portable. Local use means the custom 1965 data is only expected to be usable on the same machine, and the same 1966 application, which encoded it into the file. This limitation is due 1967 to the lack of a common registry for the local use number codes (the 1968 block or option type code numbers with the Most Significant Bit set). 1969 Since two different vendors may choose the same number, one vendor's 1970 application reading the other vendor's file would result in decoding 1971 failure. Therefore, vendors SHOULD instead use the portable method, 1972 as described next. 1974 The portable use-case supports vendor-specific custom extensions in 1975 pcapng files which can be shared across systems, organizations, etc. 1976 To avoid number space collisions, an IANA-registered Private 1977 Enterprise Number (PEN) is encoded into the Custom Block or Custom 1978 Option, using the PEN that belongs to the vendor defining the 1979 extension. Anyone can register a new PEN with IANA, for free, by 1980 filling out the online request form at http://pen.iana.org/pen/ 1981 PenApplication.page (http://pen.iana.org/pen/PenApplication.page). 1983 5.2. Controlling Copy Behavior 1985 Both Custom Blocks and Custom Options support two different codes to 1986 distinguish their "copy" behavior: a code for when the block or 1987 option can be safely copied into a new pcapng file by a pcapng 1988 manipulating application, and a code for when it should not be 1989 copied. A common reason for not copying a Custom Block or Custom 1990 Option is because it depends on other blocks or options in some way 1991 that would invalidate the custom data if the other blocks/options 1992 were removed or re-ordered. For example, if a Custom Block's data 1993 includes an Interface ID number in its Custom Data portion, then it 1994 cannot be safely copied by a pcapng application that merges pcapng 1995 files, because the merging application might re-order or remove one 1996 or more of the Interface Description Blocks, and thereby change the 1997 Interface IDs that the Custom Block depends upon. The same issue 1998 arises if a Custom Block or Custom Option depends on the presence of, 1999 or specific ordering of, other standard-based or custom-defined 2000 blocks or options. 2002 Note that the copy semantics is not related to privacy - there is no 2003 guarantee that a pcapng anonymizer will remove a Custom Block or 2004 Custom Option, even if the appropriate code is used requesting it not 2005 be copied; and the original pcapng file can be shared anyway. If the 2006 Custom Data portion of the Custom Block or Custom Option contains 2007 sensitive information, then it should be encrypted in some fashion. 2009 5.3. Strings vs. Octets 2011 For the Custom Options, there are two Custom Data formats supported: 2012 a UTF-8 string and a binary data payload. The rationale for this 2013 separation is that a pcapng display application which does not 2014 understand the specific PEN's Custom Option can still display the 2015 data as a string if it's a string type code, rather than as hex-ascii 2016 of the octets. 2018 5.4. Endianness Issues 2020 Implementers writing Custom Blocks or binary data Custom Options 2021 should be aware that a pcapng file can be re-written by machines 2022 using a different endianness than the original file, which means all 2023 known fields of the pcapng file will change endianness in the new 2024 file. Since the Custom Data payload of the Custom Block or the 2025 binary data Custom Option might be an arbitrary sequence of unknown 2026 octets to such machines, they cannot convert multi-octet values 2027 inside the Custom Data, or in the Options section of a Custom 2028 Block,into the appropriate endianness. 2030 For example, a little-endian machine can create a new pcapng file and 2031 add some binary data Custom Options to some non-Custom Block(s) in 2032 the file. This file can then be sent to a big-endian host, which 2033 will convert the Option Code, Option Length, and PEN fields of the 2034 options to big-endian format if it re-writes the file. However, if 2035 the software reading the file does not understand the contents of all 2036 of the Custom Options, it will leave the Custom Data payload of the 2037 options alone (as little-endian format). If this file then gets sent 2038 to a little-endian machine, then, when that little-endian machine 2039 reads the file, it will, if the software reading the file understands 2040 the contents of all the Custom Options, it will detect that the file 2041 format is big-endian, and swap the endianness while it parses the 2042 file - but that will cause the Custom Data payload to be incorrect 2043 since it was already in little-endian format. 2045 In addition, a little-endian machine can create a pcapng file and 2046 write some binary data Custom Blocks, containing options, to the 2047 file. The file can then be sent to a big-endian host, which, if the 2048 software reading the file does not understand the contents of the 2049 Custom Blocks, will leave the Custom Data and Options alone (as 2050 little-endina format). If this file then gets sent to a little- 2051 endian machine, then, when that little-endian machine reads the file, 2052 it will, if the software reading the file understands the contents of 2053 all the Custom Blocks, it will detect that the file format is big- 2054 endian, and swap the endianness while it parses the file - but that 2055 will cause the Custom Data payload, the Option Code and Option Length 2056 values in the Options, and the PEN in any Custom Options to be 2057 incorrect since they were already in little-endian format. 2059 Therefore, the vendor should either encode the Custom Data of their 2060 Custom Blocks and Custom Options, the Option Code and Option Length 2061 fields of options in Custom Blocks, and the PEN field of Custom 2062 Options in Custom Blocks in a consistent manner, such as always in 2063 big-endian or always in little-endian format, regardless of the host 2064 platform's endianness, or should encode some flag in the Custom Data 2065 payload to indicate in which endianness the rest of the payload is 2066 written. 2068 The PEN field of a Custom Block, or of a Custom Option not contained 2069 in a Custom Block, MUST be converted by code that reads pcapng files, 2070 so this is not an issue for that field, except for Custom Options in 2071 Custom Blocks. This is also not an issue for the Custom Data payload 2072 of UTF-8 string Custom Options. 2074 6. Recommended File Name Extension: .pcapng 2076 The recommended file name extension for the "PCAP Next Generation 2077 Capture File Format" specified in this document is ".pcapng". 2079 On Windows and macOS, files are distinguished by an extension to 2080 their filename. Such an extension is technically not actually 2081 required, as applications should be able to automatically detect the 2082 pcapng file format through the "magic bytes" at the beginning of the 2083 file, as some other UN*X desktop environments do. However, using 2084 name extensions makes it easier to work with files (e.g. visually 2085 distinguish file formats) so it is recommended - though not required 2086 - to use .pcapng as the name extension for files following this 2087 specification. 2089 Please note: To avoid confusion (such as the current usage of .cap 2090 for a plethora of different capture file formats) file name 2091 extensions other than .pcapng should be avoided. 2093 7. Conclusions 2095 The file format proposed in this document should be very versatile 2096 and satisfy a wide range of applications. In the simplest case, it 2097 can contain a raw capture of the network data, made of a series of 2098 Simple Packet Blocks. In the most complex case, it can be used as a 2099 repository for heterogeneous information. In every case, the file 2100 remains easy to parse and an application can always skip the data it 2101 is not interested in; at the same time, different applications can 2102 share the file, and each of them can benefit of the information 2103 produced by the others. Two or more files can be concatenated 2104 obtaining another valid file. 2106 8. Implementations 2108 Some known implementations that read or write the pcapng file format 2109 are listed on the pcapng GitHub wiki 2110 (https://github.com/pcapng/pcapng/wiki/Implementations). 2112 9. Security Considerations 2114 TBD. 2116 10. IANA Considerations 2118 TBD. 2120 [Open issue: decide whether the block types, option types, NRB Record 2121 types, etc. should be IANA registries. And if so, what the IANA 2122 policy for each should be (see RFC 5226)] 2124 10.1. Standardized Block Type Codes 2126 Every Block is uniquely identified by a 32-bit integer value, stored 2127 in the Block Header. 2129 As pointed out in Section 3.1, Block Type codes whose Most 2130 Significant Bit (bit 31) is set to 1 are reserved for local use by 2131 the application. 2133 All the remaining Block Type codes (0x00000000 to 0x7FFFFFFF) are 2134 standardized by this document. Requests for new Block Type codes, 2135 Option Type codes, and Secrets Type codes should be made by creating 2136 a pull request to update this document at github.com/pcapng/pcapng 2137 (https://github.com/pcapng/pcapng). The pull request should add a 2138 description of the new block, option, or secret type to Section 4. 2139 The pull request description should contain a clear request for a new 2140 type code assignment. 2142 The following is a list of the Standardized Block Type Codes: 2144 +=====================+=============================================+ 2145 |Block Type Code |Description | 2146 +=====================+=============================================+ 2147 |0x00000000 |Reserved ??? | 2148 +---------------------+---------------------------------------------+ 2149 |0x00000001 |Interface Description Block (Section 4.2) | 2150 +---------------------+---------------------------------------------+ 2151 |0x00000002 |Packet Block (Appendix A) | 2152 +---------------------+---------------------------------------------+ 2153 |0x00000003 |Simple Packet Block (Section 4.4) | 2154 +---------------------+---------------------------------------------+ 2155 |0x00000004 |Name Resolution Block (Section 4.5) | 2156 +---------------------+---------------------------------------------+ 2157 |0x00000005 |Interface Statistics Block (Section 4.6) | 2158 +---------------------+---------------------------------------------+ 2159 |0x00000006 |Enhanced Packet Block (Section 4.3) | 2160 +---------------------+---------------------------------------------+ 2161 |0x00000007 |IRIG Timestamp Block (requested by Gianluca | 2162 | |Varenni , CACE| 2163 | |Technologies LLC); code also used for Socket | 2164 | |Aggregation Event Block | 2165 | |(https://github.com/google/linux- | 2166 | |sensor/blob/master/hone-pcapng.txt) | 2167 +---------------------+---------------------------------------------+ 2168 |0x00000008 |ARINC 429 (https://en.wikipedia.org/wiki/ | 2169 | |ARINC_429) in AFDX Encapsulation Information | 2170 | |Block (requested by Gianluca Varenni | 2171 | |, CACE | 2172 | |Technologies LLC) | 2173 +---------------------+---------------------------------------------+ 2174 |0x00000009 |[systemd Journal Export | 2175 | |Block][I-D.richardson-opsawg-pcapng-extras] | 2176 +---------------------+---------------------------------------------+ 2177 |0x0000000A |Decryption Secrets Block (Section 4.7) | 2178 +---------------------+---------------------------------------------+ 2179 |0x00000101 |Hone Project (https://github.com/HoneProject)| 2180 | |Machine Info Block | 2181 | |(https://github.com/HoneProject/Linux- | 2182 | |Sensor/wiki/Augmented-PCAP-Next-Generation- | 2183 | |Dump-File-Format) (see also Google version | 2184 | |(https://github.com/google/linux- | 2185 | |sensor/blob/master/hone-pcapng.txt)) | 2186 +---------------------+---------------------------------------------+ 2187 |0x00000102 |Hone Project (https://github.com/HoneProject)| 2188 | |Connection Event Block | 2189 | |(https://github.com/HoneProject/Linux- | 2190 | |Sensor/wiki/Augmented-PCAP-Next-Generation- | 2191 | |Dump-File-Format) (see also Google version | 2192 | |(https://github.com/google/linux- | 2193 | |sensor/blob/master/hone-pcapng.txt)) | 2194 +---------------------+---------------------------------------------+ 2195 |0x00000201 |Sysdig (https://github.com/draios/sysdig) | 2196 | |Machine Info Block | 2197 +---------------------+---------------------------------------------+ 2198 |0x00000202 |Sysdig (https://github.com/draios/sysdig) | 2199 | |Process Info Block, version 1 | 2200 +---------------------+---------------------------------------------+ 2201 |0x00000203 |Sysdig (https://github.com/draios/sysdig) FD | 2202 | |List Block | 2203 +---------------------+---------------------------------------------+ 2204 |0x00000204 |Sysdig (https://github.com/draios/sysdig) | 2205 | |Event Block | 2206 +---------------------+---------------------------------------------+ 2207 |0x00000205 |Sysdig (https://github.com/draios/sysdig) | 2208 | |Interface List Block | 2209 +---------------------+---------------------------------------------+ 2210 |0x00000206 |Sysdig (https://github.com/draios/sysdig) | 2211 | |User List Block | 2212 +---------------------+---------------------------------------------+ 2213 |0x00000207 |Sysdig (https://github.com/draios/sysdig) | 2214 | |Process Info Block, version 2 | 2215 +---------------------+---------------------------------------------+ 2216 |0x00000208 |Sysdig (https://github.com/draios/sysdig) | 2217 | |Event Block with flags | 2218 +---------------------+---------------------------------------------+ 2219 |0x00000209 |Sysdig (https://github.com/draios/sysdig) | 2220 | |Process Info Block, version 3 | 2221 +---------------------+---------------------------------------------+ 2222 |0x00000210 |Sysdig (https://github.com/draios/sysdig) | 2223 | |Process Info Block, version 4 | 2224 +---------------------+---------------------------------------------+ 2225 |0x00000211 |Sysdig (https://github.com/draios/sysdig) | 2226 | |Process Info Block, version 5 | 2227 +---------------------+---------------------------------------------+ 2228 |0x00000212 |Sysdig (https://github.com/draios/sysdig) | 2229 | |Process Info Block, version 6 | 2230 +---------------------+---------------------------------------------+ 2231 |0x00000213 |Sysdig (https://github.com/draios/sysdig) | 2232 | |Process Info Block, version 7 | 2233 +---------------------+---------------------------------------------+ 2234 |0x00000BAD |Custom Block that rewriters can copy into new| 2235 | |files (Section 4.8) | 2236 +---------------------+---------------------------------------------+ 2237 |0x40000BAD |Custom Block that rewriters should not copy | 2238 | |into new files (Section 4.8) | 2239 +---------------------+---------------------------------------------+ 2240 |0x0A0D0D0A |Section Header Block (Section 4.1) | 2241 +---------------------+---------------------------------------------+ 2242 |0x0A0D0A00-0x0A0D0AFF|Reserved. Used to detect trace files | 2243 | |corrupted because of file transfers using the| 2244 | |HTTP protocol in text mode. | 2245 +---------------------+---------------------------------------------+ 2246 |0x000A0D0A-0xFF0A0D0A|Reserved. Used to detect trace files | 2247 | |corrupted because of file transfers using the| 2248 | |HTTP protocol in text mode. | 2249 +---------------------+---------------------------------------------+ 2250 |0x000A0D0D-0xFF0A0D0D|Reserved. Used to detect trace files | 2251 | |corrupted because of file transfers using the| 2252 | |HTTP protocol in text mode. | 2253 +---------------------+---------------------------------------------+ 2254 |0x0D0D0A00-0x0D0D0AFF|Reserved. Used to detect trace files | 2255 | |corrupted because of file transfers using the| 2256 | |FTP protocol in text mode. | 2257 +---------------------+---------------------------------------------+ 2258 |0x80000000-0xFFFFFFFF|Reserved for local use. | 2259 +---------------------+---------------------------------------------+ 2261 Table 9: Standardized Block Type Codes 2263 [Open issue: reserve 0x40000000-0x7FFFFFFF for do-not-copy-bit range 2264 of base types?] 2266 11. Contributors 2268 Loris Degioanni and Gianluca Varenni were coauthoring this document 2269 before it was submitted to the IETF. 2271 12. Acknowledgments 2273 The authors wish to thank Anders Broman, Ulf Lamping, Richard Sharpe 2274 and many others for their invaluable comments. 2276 13. References 2278 13.1. Normative References 2280 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2281 Requirement Levels", BCP 14, RFC 2119, 2282 DOI 10.17487/RFC2119, March 1997, 2283 . 2285 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2286 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2287 May 2017, . 2289 13.2. Informative References 2291 [I-D.richardson-opsawg-pcapng-extras] 2292 "*** BROKEN REFERENCE ***". 2294 [LINKTYPES] 2295 The Tcpdump Group, "the tcpdump.org link-layer header 2296 types registry", . 2298 Appendix A. Packet Block (obsolete!) 2300 The Packet Block is obsolete, and MUST NOT be used in new files. Use 2301 the Enhanced Packet Block or Simple Packet Block instead. This 2302 section is for historical reference only. 2304 A Packet Block was a container for storing packets coming from the 2305 network. 2307 1 2 3 2308 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 2309 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2310 0 | Block Type = 0x00000002 | 2311 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2312 4 | Block Total Length | 2313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2314 8 | Interface ID | Drops Count | 2315 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2316 12 | Timestamp (High) | 2317 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2318 16 | Timestamp (Low) | 2319 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2320 20 | Captured Packet Length | 2321 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2322 24 | Original Packet Length | 2323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2324 28 / / 2325 / Packet Data / 2326 / variable length, padded to 32 bits / 2327 / / 2328 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2329 / / 2330 / Options (variable) / 2331 / / 2332 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2333 | Block Total Length | 2334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2336 Figure 19: Packet Block Format 2338 The Packet Block has the following fields: 2340 * Block Type: The block type of the Packet Block is 2. 2342 * Block Total Length: total size of this block, as described in 2343 Section 3.1. 2345 * Interface ID: specifies the interface this packet comes from; the 2346 correct interface will be the one whose Interface Description 2347 Block (within the current Section of the file) is identified by 2348 the same number (see Section 4.2) of this field. The interface ID 2349 MUST be valid, which means that an matching interface description 2350 block MUST exist. 2352 * Drops Count: a local drop counter. It specifies the number of 2353 packets lost (by the interface and the operating system) between 2354 this packet and the preceding one. The value xFFFF (in 2355 hexadecimal) is reserved for those systems in which this 2356 information is not available. 2358 * Timestamp (High) and Timestamp (Low): timestamp of the packet. 2359 The format of the timestamp is the same as was already defined for 2360 the Enhanced Packet Block (Section 4.3). 2362 * Captured Packet Length: number of octets captured from the packet 2363 (i.e. the length of the Packet Data field). It will be the 2364 minimum value among the Original Packet Length and the snapshot 2365 length for the interface (SnapLen, defined in Figure 10). The 2366 value of this field does not include the padding octets added at 2367 the end of the Packet Data field to align the Packet Data field to 2368 a 32-bit boundary. 2370 * Original Packet Length: actual length of the packet when it was 2371 transmitted on the network. It can be different from Captured 2372 Packet Length if the packet has been truncated by the capture 2373 process. 2375 * Packet Data: the data coming from the network, including link- 2376 layer headers. The actual length of this field is Captured Packet 2377 Length plus the padding to a 32-bit boundary. The format of the 2378 link-layer headers depends on the LinkType field specified in the 2379 Interface Description Block (see Section 4.2) and it is specified 2380 in the entry for that format in [LINKTYPES]. 2382 * Options: optionally, a list of options (formatted according to the 2383 rules defined in Section 3.5) can be present. 2385 In addition to the options defined in Section 3.5, the following 2386 options were valid within this block: 2388 +============+======+==========+===================+ 2389 | Name | Code | Length | Multiple allowed? | 2390 +============+======+==========+===================+ 2391 | pack_flags | 2 | 4 | no | 2392 +------------+------+----------+-------------------+ 2393 | pack_hash | 3 | variable | yes | 2394 +------------+------+----------+-------------------+ 2396 Table 10: Packet Block Options 2398 pack_flags: 2400 The pack_flags option is the same as the epb_flags of the 2401 enhanced packet block. 2403 Example: '0'. 2405 pack_hash: 2406 The pack_hash option is the same as the epb_hash of the 2407 enhanced packet block. 2409 Examples: '02 EC 1D 87 97', '03 45 6E C2 17 7C 10 1E 3C 2E 99 6E C2 2410 9A 3D 50 8E'. 2412 Authors' Addresses 2414 Michael Tuexen (editor) 2415 Muenster University of Applied Sciences 2416 Stegerwaldstrasse 39 2417 48565 Steinfurt 2418 Germany 2420 Email: tuexen@fh-muenster.de 2422 Fulvio Risso 2423 Politecnico di Torino 2424 Corso Duca degli Abruzzi, 24 2425 10129 Torino 2426 Italy 2428 Email: fulvio.risso@polito.it 2430 Jasper Bongertz 2431 Airbus Defence and Space CyberSecurity 2432 Kanzlei 63c 2433 40667 Meerbusch 2434 Germany 2436 Email: jasper@packet-foo.com 2438 Gerald Combs 2439 Wireshark Foundation 2440 339 Madson Pl 2441 Davis, CA 95618 2442 United States of America 2444 Email: gerald@wireshark.org 2445 Guy Harris 2447 Email: gharris@sonic.net 2449 Eelco Chaudron 2450 Red Hat 2451 De Entree 238 2452 1101 EE Amsterdam 2453 Netherlands 2455 Email: eelco@redhat.com 2457 Michael C. Richardson 2458 Sandelman Software Works 2460 Email: mcr+ietf@sandelman.ca 2461 URI: http://www.sandelman.ca/