LINKTYPE_PKTAP

Packet structure

PKTAP version 1:

+---------------------------+
|   Length of PKTAP header  |
|         (4 Octets)        |
+---------------------------+
|        Record type        |
|         (4 Octets)        |
+---------------------------+
| DLT_ value for this packet|
|         (4 Octets)        |
+---------------------------+
|    ASCII interface name   |
|        (24 Octets)        |
+---------------------------+
|        Packet flags       |
|         (4 Octets)        |
+---------------------------+
|       Protocol family     |
|         (4 Octets)        |
+---------------------------+
|  Link-layer header length |
|         (4 Octets)        |
+---------------------------+
| Link-layer trailer length |
|         (4 Octets)        |
+---------------------------+
|         Process ID        |
|         (4 Octets)        |
+---------------------------+
|       Command name        |
|        (20 Octets)        |
+---------------------------+
|       Service class       |
|         (4 Octets)        |
+---------------------------+
|      Interface type       |
|         (2 Octets)        |
+---------------------------+
|  Unit number of interface |
|         (2 Octets)        |
+---------------------------+
|    Effective process ID   |
|         (4 Octets)        |
+---------------------------+
|   Effective command name  |
|        (20 Octets)        |
+---------------------------+
|           Flow ID         |
|         (4 Octets)        |
+---------------------------+
|        IP protocol        |
|         (4 Octets)        |
+---------------------------+
|    Time stamp, seconds    |
|         (4 Octets)        |
+---------------------------+
|  Time stamp, microseconds |
|         (4 Octets)        |
+---------------------------+
|            UUID           |
|        (16 Octets)        |
+---------------------------+
|      Effective UUID       |
|        (16 Octets)        |
+---------------------------+
|           Payload         |
.                           .
.                           .
.                           .

PKTAP version 2:

+----------------------------------------+
|         Length of PKTAP header         |
|                (1 Octet)               |
+----------------------------------------+
|             Offset of UUID             |
|                (1 Octet)               |
-----------------------------------------+
|         Offset of effective UUID       |
|                (1 Octet)               |
+----------------------------------------+
|         Offset of interface name       |
|                (1 Octet)               |
+----------------------------------------+
|          Offset of command name        |
|                (1 Octet)               |
+----------------------------------------+
|      Offset of effective command name  |
|                (1 Octet)               |
+----------------------------------------+
|       DLT_ value for this packet       |
|               (2 Octets)               |
+----------------------------------------+
|        Link-layer header length        |
|               (2 Octets)               |
+----------------------------------------+
|        Link-layer trailer length       |
|               (2 Octets)               |
+----------------------------------------+
|             Interface type             |
|               (2 Octets)               |
+----------------------------------------+
|              IP protocol               |
|               (2 Octets)               |
+----------------------------------------+
|            Protocol family             |
|               (4 Octets)               |
+----------------------------------------+
|              Service class             |
|               (4 Octets)               |
+----------------------------------------+
|                 Flow ID                |
|               (4 Octets)               |
+----------------------------------------+
|               Process ID               |
|               (4 Octets)               |
+----------------------------------------+
|          Effective process ID          |
|               (4 Octets)               |
+----------------------------------------+
|              Packet flags              |
|               (4 Octets)               |
+----------------------------------------+
|                  UUID                  |
|             (0-16 Octets)              |
+----------------------------------------+
|            Effective UUID              |
|             (0-16 Octets)              |
+----------------------------------------+
|          ASCII interface name          |
|             (0-24 Octets)              |
+----------------------------------------+
|              Command name              |
|             (0-17 Octets)              |
+----------------------------------------+
|         Effective command name         |
|             (0-17 Octets)              |
+----------------------------------------+
|                Payload                 |
.                                        .
.                                        .
.                                        .

Description

All multi-byte fields currently appear to be little-endian, but Apple haven't indicated whether this is by design or merely a consequence of all Apple machines that write this format being little-endian.

In the PKTAP version 1 header:

The length field indicates how long the PKTAP header is; this value includes the length of the length field itself. It should be at least 108; if it's larger, there is additional data in the header following the effective command name.

The record type field contains a value that is one of:

  • 0, if nothing follows the PKTAP header;
  • 1, if a packet follows the PKTAP header.

The DLT_ value field contains a macOS DLT_ value for the packet, such as DLT_EN10MB for an Ethernet packet.

The interface name contains a null-padded ASCII string giving the name of the interface on which the packet arrived. Do not assume that there is a NUL character at the end of the name.

The flags field contains a set of flags for the packet:

  • 0x00000001 - packet is an incoming packet
  • 0x00000002 - packet is an outgoing packet
  • 0x00000004 - process is delegated
  • 0x00000008 - interface is delegated
  • 0x00002000 - header has a time stamp
  • 0x00004000 - packet is from a new flow
  • 0x00008000 - packet is a retransmission
  • 0x00010000 - packet is a keep-alive packet
  • 0x00020000 - packet is on a socket
  • 0x00040000 - packet is on a nexus channel
  • 0x00080000 - this packet has a version 2 PKTAP header

The flags field is at the same offset in the version 1 and version 2 headers; it should be checked for the "version 2 PKTAP header" flag before any other fields, including the length, are interpreted.

The protocol family field contains a value indicating the address family of the packet. It may be 0 for "unknown", 2 for IPv4, or 30 for IPv6. It may also be another macOS AF_ value; note that those values do not necessarily correspond to the AF_ value of the operating system on the host reading a capture.

The link-layer header length field appears to contain the length of the packet's link-layer header. It may be 0.

The link-layer trailer length field is assumed to contain the length of the packet's link-layer trailer. It may be 0.

The process ID field contains the process ID of the process that sent the packet; it may be 0 if the process ID is unknown.

The command name contains a null-padded ASCII string giving the last component of the path name of the executable image running in the process that sent the packet, truncated to 20 characters. It may be a null string if the executable image name is unknown. Do not assume that there is a NUL character at the end of the name.

The service class field contains one of the following values:

  • 0, for "best effort",
  • 100, for "background system-initiated";
  • 200, for "background user-initiated";
  • 300, for "responsive data";
  • 400, for "operations, administration, and management";
  • 500, for "multimedia audio/video streaming";
  • 600, for "responsive multimedia audio/video";
  • 700, for "interactive video";
  • 800, for "interactive voice";
  • 900, for "network control".

Note that these are priorities for which there is a total order; they have different delay tolerance, loss tolerance, etc. characteristics.

The interface type field contains an SNMP ifType value for the interface.

The "unit number of interface" field is assumed to contain the unit number of the interface.

The effective process ID field is assumed to contain a process ID of some sort; it may be 0 if the process ID is unknown.

The effective command name contains a null-padded ASCII string giving the last component of the path name of the executable image running in some process, truncated to 20 characters. It may be a null string if the executable image name is unknown. Do not assume that there is a NUL character at the end of the name.

The flow ID field contains a hash value computed for the flow to which the packet belongs; it is 0 if there is no flow ID.

The IP protocol field contains a macOS IPPROTO_ value for the packet; it may be IPPROTO_RAW if the packet was written to a raw socket.

All fields following the effective command name field are optional; the length field indicates how many fields are present.

In the PKTAP version 2 header:

The length field indicates how long the PKTAP header is; this value includes the length of the length field itself. It should be at least 108; if it's larger, there is additional data in the header following the effective command name.

The "offset of UUID" field is 0 if the UUID field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the UUID field.

The "offset of effective UUID" field is 0 if the effective UUID field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the effective UUID field.

The "offset of interface name" field is 0 if the interface name field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the interface name field.

The "offset of interface name" field is 0 if the interface name field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the interface name field.

The "offset of effective interface name" field is 0 if the effective interface name field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the effective interface name field.

The "offset of command name" field is 0 if the command name field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the command name field.

The "offset of effective command name" field is 0 if the effective command name field is not present; otherwise, it's the offset from the beginning of the PKTAP header of the effective command name field.

The DLT_ value field contains a macOS DLT_ value for the packet, such as DLT_EN10MB for an Ethernet packet.

The link-layer header length field appears to contain the length of the packet's link-layer header. It may be 0.

The link-layer trailer length field is assumed to contain the length of the packet's link-layer trailer. It may be 0.

The interface type field contains an SNMP ifType value for the interface.

The IP protocol field contains a macOS IPPROTO_ value for the packet; it may be IPPROTO_RAW if the packet was written to a raw socket.

The protocol family field contains a value indicating the address family of the packet. It may be 0 for "unknown", 2 for IPv4, or 30 for IPv6. It may also be another macOS AF_ value; note that those values do not necessarily correspond to the AF_ value of the operating system on the host reading a capture.

The service class field contains one of the following values:

  • 0, for "best effort",
  • 100, for "background system-initiated";
  • 200, for "background user-initiated";
  • 300, for "responsive data";
  • 400, for "operations, administration, and management";
  • 500, for "multimedia audio/video streaming";
  • 600, for "responsive multimedia audio/video";
  • 700, for "interactive video";
  • 800, for "interactive voice";
  • 900, for "network control".

Note that these are priorities for which there is a total order; they have different delay tolerance, loss tolerance, etc. characteristics.

The flow ID field contains a hash value computed for the flow to which the packet belongs; it is 0 if there is no flow ID.

The process ID field contains the process ID of the process that sent the packet; it may be 0 if the process ID is unknown.

The effective process ID field is assumed to contain a process ID of some sort; it may be 0 if the process ID is unknown.

The flags field contains a set of flags for the packet:

  • 0x00000001 - packet is an incoming packet
  • 0x00000002 - packet is an outgoing packet
  • 0x00000004 - process is delegated
  • 0x00000008 - interface is delegated
  • 0x00002000 - header has a time stamp
  • 0x00004000 - packet is from a new flow
  • 0x00008000 - packet is a retransmission
  • 0x00010000 - packet is a keep-alive packet
  • 0x00020000 - packet is on a socket
  • 0x00040000 - packet is on a nexus channel
  • 0x00080000 - this packet has a version 2 PKTAP header

The flags field is at the same offset in the version 1 and version 2 headers; it should be checked for the "version 2 PKTAP header" flag before any other fields, including the length, are interpreted.

The interface name contains a null-terminated ASCII string giving the name of the interface on which the packet arrived.

The command name contains a null-terminated ASCII string giving the last component of the path name of the executable image running in the process that sent the packet, truncated to 20 characters. It may be a null string if the executable image name is unknown.

The effective command name contains a null-terminated ASCII string giving the last component of the path name of the executable image running in some process, truncated to 20 characters. It may be a null string if the executable image name is unknown.