User manual CACE TECHNOLOGIES PPI HEADER SPECIFICATION V1.0.7

[. . . ] It is not intended to add arbitrary data to packets, such as annotations. That task is better suited to NTAR. 1. 2 Scope This document defines the general format of the PPI header, along with the formats of several fields. Definitions, Acronyms and Abbreviations ASCII A-MPDU A-MSDU CCK CRC CR-LF DLT EVM FCS FHSS GFSK GID HT MAC MPDU OFDM PHY PPI RF American Standard Code for Information Interchange aggregate MAC protocol data unit aggregate MAC service data unit complementary code keying cyclic redundancy check carriage return-line feed data link type error vector magnitude frame check sequence frequency-hopping spread spectrum gaussian frequency shift key or keying group identifier high throughput medium access control MAC protocol data unit orthogonal frequency division multiplexing physical layer per-packet information radio frequency 1. 3 © CACE Technologies, 2007 - 2008 Page 4 PPI Header Specification Version: 1. 0. 7 Date: 9/11/2008 receive signal strength indicator receive or receiver short guard interval timing synchronization function timing synchronization function timer unique identifier Unicode transformation format RSSI RX SGI TSF TSFT UID UTF 1. 4 Notational Conventions 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 RFC 2119. References Radiotap manual page: http://netbsd. gw. com/cgi-bin/man-cgi?ieee80211_radiotap+9+NetBSD-current NTAR documentation: http://www. winpcap. org/ntar/ RFC 2119: http://www. ietf. org/rfc/rfc2119. txt 1. 5 1. 6 Overview Section 2 provides a description of the PPI header, along with an explanation of its necessity. [. . . ] The following values are defined: Bits (Bit 0 = LSB) 0 Values Alignment. 32-bit aligned = 1, non-aligned = 0 Explained further in section 3. 3 1-7 Reserved. MUST be 0. 3. 1. 3 pph_len The length of the entire PPI header, including the packet header and fields. pph_dlt This MUST contain a valid data link type as defined in pcap-bpf. h from the libpcap distribution. If an official DLT registry is ever created by the libpcap development team, then it will supersede this list. A capture facility can implement per-packet DLTs by setting pph_version to 0, pph_flags to 0, pph_len to 8, and pph_dlt to the DLT of the encapsulated packet. 3. 1. 4 3. 2 PPI Field Structure Each PPI field includes a type and length: typedef struct ppi_fieldheader { u_int16_t pfh_type; /* Type */ u_int16_t pfh_datalen; /* Length of data */ } ppi_fieldheader_t; 3. 2. 1 pfh_type The type of data following the field header MUST be a valid type value as defined below: Range 0-29, 999 30, 000-65, 535 Possible Values General-purpose field. Defined in section 5. If an unknown field value is encountered, it MUST be skipped according to the length rule in section 3. 3. © CACE Technologies, 2007 - 2008 Page 6 PPI Header Specification Version: 1. 0. 7 Date: 9/11/2008 3. 2. 2 pfh_datalen The length of the data, in bytes, that follows MUST be between 0 and 65, 520 inclusive. Field Processing The first field header immediately follows the packet header (that is, if the packet header starts at byte 0, the first field header starts at byte 8). The starting point of each subsequent field header is defined by the "alignment" bit in pph_flags: · If the "alignment" bit in pph_flags is set to 1 AND pfh_datalen in field n is not a multiple of 4, then field n+1 will start at the next multiple of 4. For example, if pph_datalen in field 3 is 9, then the next three bytes MUST be considered padding, and field 4 will begin at byte 12. If the "alignment" bit in pph_flags is 0, then field n+1 will start at the next byte offset following the data in field n. 3. 3 · The "alignment" bit in pph_flags also applies to field data. That is, if the "alignment" bit is set and the field type is 7 bytes long, then there will be one byte of padding between the field header and field data. All padding bytes MUST be set to 0 in order to keep from exposing kernel memory to user space. 4. General-Purpose Field Types The following general-purpose fields are currently defined. Further general-purpose fields will be defined in later revisions of this document. Type 0-1 2 3 4 5 6 7 8 9 10 ­ 29, 999 20 12 48 22-65, 520 19-65, 520 ???RESERVED 4. 1 4. 1. 2 Field Descriptions 802. 11-Common Zero or one 802. 11-Common fields may be present in a single header. The 802. 11-Common field is loosely based on the existing Radiotap header format. Field Name Semantics Value Type Length © CACE Technologies, 2007 - 2008 Page 7 PPI Header Specification Version: 1. 0. 7 Date: 9/11/2008 7. 3. 1. 10 and 11. 1 of IEEE 802. 11-1999 Invalid value = 0 Unsigned integer 8 bytes TSF-Timer Flags Rate Packet flags LSB = bit 0. Bits: Bit 0 = If set, FCS present Bit 1 = If set to 1, the TSF-timer is in ms, if set to 0 the TSF-timer is in us Bit 2 = If set, the FCS is not valid Bit 3 = If set, there was a PHY error receiving the packet. 0 (zero) means that the information is not available Combined Received Signal Strength Indication (RSSI) value from all the active antennas and channels. Invalid value = 255 Unsigned integer Unsigned integer 1 byte 1 byte RSSIAnt0Ctl Received Signal Strength Indication (RSSI) value for the antenna 0, control channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt1Ctl Received Signal Strength Indication (RSSI) value for the antenna 1, control channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt2Ctl Received Signal Strength Indication (RSSI) value for the antenna 2, control channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt3Ctl Received Signal Strength Indication (RSSI) value for the antenna 3, control channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt0Ext Received Signal Strength Indication (RSSI) value for the antenna 0, extension channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt1Ext Received Signal Strength Indication (RSSI) value for the antenna 1, extension channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt2Ext Received Signal Strength Indication (RSSI) value for the antenna 2, extension channel Invalid value = 255 Unsigned integer 1 byte RSSIAnt3Ext Received Signal Strength Indication (RSSI) value for the antenna 3, extension channel Invalid value = 255 Unsigned integer 1 byte Extension Channel-Freq Radiotap-formatted extension channel frequency, in Channel Frequency in MHz Invalid value = 0x0000. [. . . ] A valid delimiter sequence consists of Idle start-of-frame(SOF) data, pad(optional) end-of-frame(EOF) fill(optional) idle Bit 2 = The frame has a symbol error. Value Type Unsigned integer Length 4 bytes Errors Unsigned integer 4 bytes 5. Vendor-Specific Field Types Type values 30, 000 to 65, 535 are reserved for vendor-specific applications. Vendor numbers are assigned by the WinPcap development team, and assignment may be handed over to a formal standards body in the future. To request a vendor number, send and mail to winpcap-users@winpcap. org. [. . . ]