draft-gharris-opsawg-pcap.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[]>
<?rfc symrefs='yes' ?>
<?rfc toc='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<?rfc inline='yes' ?>
<?rfc sortrefs='no' ?>
<?rfc strict='yes' ?>

<rfc category='info'
     ipr='trust200902'
     docName="draft-gharris-opsawg-pcap-00">

  <front>

    <title abbrev="pcap">PCAP Capture File Format</title>

    <author initials='G.' surname='Harris' fullname='Guy Harris'>
      <address>
        <email>gharris@sonic.net</email>
      </address>
    </author>

    <date />

    <abstract>
      <t>This document describes the format used by the libpcap library
      to record captured packets to a file.  Programs using the libpcap
      library to read and write those files, and thus reading and
      writing files in that format, include tcpdump.</t>
    </abstract>

  </front>

<!--===========================================================================

    MAIN BODY - still within the <rfc> tag

============================================================================-->

  <middle>

    <section title="Introduction">

      <t>In the late 1980's, Van Jacobson, Steve McCanne, and others at
      the Network Research Group at Lawrence Berkeley National
      Laboratory developed the tcpdump program to capture and dissect
      network traces.  The code to capture traffic, using low-level
      mechanisms in various operating systems, and to read and write
      network traces to a file was later put into a library named
      libpcap.</t>

      <t>This document describes the format used by tcpdump, and other
      programs using libpcap, to write network traces.</t>

    </section>

    <section title='Terminology'>

      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
      document are to be interpreted as described in <xref
      target='RFC2119'/>.</t>

    </section>

    <section title="General File Structure">

        <t>A capture file begins with a File Header, followed by zero or
        more Packet Records, one per packet.</t>

        <t>All fields in the File Header and in Packet Records will
        always be saved according to the characteristics (little endian
        / big endian) of the capturing machine.  This refers to all the
        fields that are saved as numbers and that span over two or more
        octets.</t>

        <t>The approach of having the file saved in the native format of
        the generating host is more efficient because it avoids translation
        of data when reading / writing on the host itself, which is the most
        common case when generating/processing capture captures.</t>

    </section>

    <section title="File Header">

        <t>The File Header has the following format:</t>

        <figure anchor="file_header" title="File Header" align="center">
          <artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                          Magic Number                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |          Major Version        |         Minor Version         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                           Reserved1                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                           Reserved2                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                            SnapLen                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 |                           LinkType                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
        </figure>

        <t>The File Header length is 24 octets.</t>

        <t>The meaning of the fields in the File Header is:
          <list style="symbols">

            <t>Magic Number (32 bits): an unsigned magic number,
            whose value is either the hexadecimal number 0xA1B2C3D4
            or the hexadecimal number 0xA1B23C4D.  If the value is
            0xA1B2C3D4, time stamps in Packet Records (see <xref
            target="packet_record"/>) are in seconds and microseconds; if
            it is 0xA1B23C4D, time stamps in Packet Records are in
            seconds and nanoseconds.  These numbers can be used to
            distinguish sections that have been saved on little-endian
            machines from the ones saved on big-endian machines, and to
            heuristically identify pcap files.</t>

            <t>Major Version (16 bits): an unsigned value, giving the
            number of the current major version of the format. The
            value for the current version of the format is 2. This
            value should change if the format changes in such a way that
            code that reads the new format could not read the old format
            (i.e., code to read both formats would have to check the
            version number and use different code paths for the two
            formats) and code that reads the old format could not read
            the new format.</t>

            <t>Minor Version (16 bits): an unsigned value, giving the
            number of the current minor version of the format. The
            value is for the current version of the format is 4. This
            value should change if the format changes in such a way that
            code that reads the new format could read the old format
            without checking the version number but code that reads the
            old format could not read all files in the new format.</t>

            <t>Reserved1 (32 bits): not used - SHOULD be filled with 0 by
            pcap file writers, and MUST be ignored by pcap file
            readers. This value was documented by some older implementations
            as "gmt to local correction". Some older pcap file writers
            stored non-zero values in this field.</t>

            <t>Reserved2 (32 bits): not used - SHOULD be filled with 0 by
            pcap file writers, and MUST be ignored by pcap file
            readers. This value was documented by some older implementations
            as "accuracy of timestamps". Some older pcap file writers
            stored non-zero values in this field.</t>

            <t>SnapLen (32 bits): an unsigned value indicating the
            maximum number of octets captured from each packet.  The
            portion of each packet that exceeds this value will not be
            stored in the file.  This value MUST NOT be zero; if no
            limit was specified, the value should be a number greater
            than or equal to the largest packet length in the file.</t>

            <t>LinkType (32 bits): an unsigned value that defines, in
            the lower 16 bits, the link layer type of packets in the
            file, and optionally indicates the length of the Frame Check
            Sequence (FCS) of packets in the upper 16 bits.  The list of
            Standardized Link Layer Type codes is available in <xref
            target="LINKTYPES"/>.  If bit
            5 is set, bits 0 through 3 contain the length of the FCS
            field at the end of all packets; if bit 5 is not set, the
            length of the FCS field at the end of all packets is
            unknown.  Bit 4, and bits 6 through 15, SHOULD be filled
            with 0 by pcap file writers, and MUST be ignored by pcap
            file readers.</t>

          </list>
        </t>

    </section>

    <section title="Packet Record">

        <t>A Packet Record is the standard container for storing the
        packets coming from the network.</t>

        <figure anchor="packet_record" title="Packet Record">
          <artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
                       1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                      Timestamp (Seconds)                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |            Timestamp (Microseconds or nanoseconds)            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                    Captured Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                    Original Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 /                                                               /
   /                          Packet Data                          /
   /                        variable length                        /
   /                                                               /
   +---------------------------------------------------------------+
</artwork>
        </figure>

        <t>The Packet Header length is 16 octets.</t>

        <t>The meaning of the fields in the Packet Record is:
          <list style="symbols">

            <t>Timestamp (Seconds) and Timestamp (Microseconds or
            nanoseconds): seconds and fraction of a seconds values of a
            timestamp. The seconds value is a 32-bit unsigned integer
            that represents the number of seconds that have elapsed
            since 1970-01-01 00:00:00 UTC, and the microseconds or
            nanoseconds value represents the number of microseconds or
            nanoseconds that have elapsed since that seconds. Whether
            the value represents microseconds or nanoseconds is
            specified by the magic number in the File Header.</t>

            <t>Captured Packet Length (32 bits): an unsigned value that
            indicates the number of octets captured from the packet
            (i.e. the length of the Packet Data field). It will be the
            minimum value among the Original Packet Length and the
            snapshot length for the interface (SnapLen, defined in <xref
            target="file_header"/>).</t>

            <t>Original Packet Length (32 bits): an unsigned value that
            indicates the actual length of the packet when it was
            transmitted on the network.  It can be different from
            the Captured Packet Length if the packet has been truncated
            by the capture process.</t>

            <t>Packet Data: the data coming from the network, including
            link-layer headers. The actual length of this field is
            Captured Packet Length.  The format of the link-layer
            headers depends on the LinkType field specified in the file
            header (see <xref target="file_header"/>) and it is
            specified in the entry for that format in <xref
            target="LINKTYPES"/>.</t>

          </list>
        </t>

      </section>

    <section title="Recommended File Name Extension: .pcap">

      <t>The recommended file name extension for the "PCAP Capture File
      Format" specified in this document is ".pcap".</t>

      <t>On Windows and macOS, files are distinguished by an extension to their
      filename. Such an extension is technically not actually required, as
      applications should be able to automatically detect the pcap file
      format through the "magic bytes" at the beginning of the file, as some
      other UN*X desktop environments do. However, using name extensions makes
      it easier to work with files (e.g. visually distinguish file formats) so
      it is recommended - though not required - to use .pcap as the name
      extension for files following this specification.</t>

      <t>Please note: To avoid confusion (such as the current usage of
      .cap for a plethora of different capture file formats) file
      name extensions other than .pcap should be avoided.</t>

    </section>

    <section title="Security Considerations">

      <t>TBD.</t>

    </section>

    <section title="IANA Considerations">
      <t>TBD.</t>

      <t>[Open issue: decide whether the LinkType values should be IANA
      registries.  And if so, what the IANA policy for each should be
      (see RFC 5226)]</t>

    </section>

    <section title='Contributors'>

      <t>[Insert pcap developers etc. here].</t>

    </section>

    <section title="Acknowledgments">

      <t>The authors wish to thank [insert list here]
      and many others for their invaluable comments.</t>

    </section>

  </middle>

<!--===========================================================================

    Back End - still within the <rfc> tag

============================================================================-->

  <back>
    <references title='Normative References'>
      <?rfc include='reference.RFC.2119'?>
    </references>

    <references title='Informational References'>
      <reference anchor="LINKTYPES" target="http://www.tcpdump.org/linktypes.html">
        <front>
          <title>the tcpdump.org link-layer header types registry</title>
          <author initials="" surname="" fullname="">
            <organization>The Tcpdump Group</organization>
          </author>
          <date/>
        </front>
      </reference>
    </references>

  </back>
</rfc>