Wireshark · Wireshark-dev: Re: [Wireshark-dev] Adding IEEE 802.15.4 DLT for meta data?

[James Ko <jim.list@xxxxxxxxxxx>]

In order to go down the path of adding DLT_PPI fields for IEEE 802.15.4, I tried sent an email off to winpcap-users@xxxxxxxxxxx but I found that the list is no longer.  It appears to me that much of that list is also part of this list but I could not find the responsible party for allocating and managing PPI link-type fields since CACE was acquired by Riverbed.  The PPI document

I've drafted up a document with the proposed format of the additional PPI fields and attached it.

How can I formally go about putting this through review?

James

---

From: Wireshark-dev <wireshark-dev-bounces@xxxxxxxxxxxxx> on behalf of James Ko <jim.list@xxxxxxxxxxx>
Sent: Thursday, January 10, 2019 11:10
To: Guy Harris; Developer support list for Wireshark
Subject: Re: [Wireshark-dev] Adding IEEE 802.15.4 DLT for meta data?

 

Thanks Guy,

I submitted my request for a link-type assignment but I see that the DLT_PPI is generic enough to extend support for IEEE 802.15.4 packets as well with new field types.  The approach there is is similar to what I am proposing but the field types defined in the PPI are aggregate blocks of a not small number of parameters/values instead of a single or few related values per type.  Perhaps that is just a factor of the IEEE802.11 specification that the values are tightly coupled.

James

---

From: Wireshark-dev <wireshark-dev-bounces@xxxxxxxxxxxxx> on behalf of Guy Harris <guy@xxxxxxxxxxxx>
Sent: Monday, January 7, 2019 13:50
To: Developer support list for Wireshark
Subject: Re: [Wireshark-dev] Adding IEEE 802.15.4 DLT for meta data?

 

On Jan 7, 2019, at 1:18 PM, James Ko <jim.list@xxxxxxxxxxx> wrote:

> There are ongoing proposal in pcapng format for adding generic wireless meta data options to the enhanced packet block (EPB) and invariant (or seldom changing) capture interface meta data to a new capture interface block (CIB).
> https://github.com/pcapng/pcapng/pull/51 and  https://github.com/pcapng/pcapng/pull/56
>
> I see  that 802.11 has several DLT types for including metadata.  (DLT_PRISM_HEADER, DLT_IEEE802_11_RADIO, & DLT_IEEE802_11_RADIO_AVS)

Yes.  Personally, I think that's two too many - three, actually, with DLT_PPI - but there are historical reasons for them.  I'd like to see radiotap pick up all of the 802.11-specific things PPI does, at which point PPI's remaining capabilities should probably be picked up either by other link-layer header types or by pcapng options.

> I would like to propose one or more DLT types for including 802.15.4 meta-data.

I'd prefer "one" to "or more".

> Defining a new DLT type instead of relying on PCAPNG out of band data enables adding the additional information to pcap sources as well.

Yes.  My inclination, by default, is to put the metadata in the link-layer header, with a new link-layer header type assigned, rather than use pcapng for this.

> Preference of course is to have only one DLT type with type/length/value (TLV) for each meta data object just as pcapng deals with options.  However creating different DLT types may make more sense for the various MACs defined in IEEE802.15.4 (i.e. TSCH-MAC specific).  The new DLT would encapsulate the existing packet-ieee802154.c dissector as the last option.

If the metadata is mostly MAC-specific, that'd probably mean either

        1) the MAC type as the first item in the metadata, followed by MAC-specific metadata

or

        2) multiple link-layer header types.

Presumably a single interface will always have the same MAC type, so that, in the multiple link-layer header types case, the interface can be given a specific link-layer header type.

> Any advice/comments on how to proceed or not proceed?  Shall I go just ahead and create the dissector with a new DLT type and submit it for code-review to solicit feedback?

The procedure for assigning a link-layer header type is outlined at the beginning of

        https://www.tcpdump.org/linktypes.html

Note that the first thing you start with is *not* code to parse the header, it's a specification of the header, independent of code.  All the specs on the tcpdump.org site, or linked to from the tcpdump.org site, should be sufficient for somebody to write code to parse the header without ever looking at tcpdump or Wireshark code.
___________________________________________________________________________
Sent via:    Wireshark-dev mailing list <wireshark-dev@xxxxxxxxxxxxx>
Archives:    https://www.wireshark.org/lists/wireshark-dev
Unsubscribe: https://www.wireshark.org/mailman/options/wireshark-dev
             mailto:wireshark-dev-request@xxxxxxxxxxxxx?subject=unsubscribe

Per-Packet Information Specification

for IEEE 802.15.4

Version 1



January 16, 2019

Contents


1  Introduction                                                                   2

2  Overview                                                                       2

    2.1  PCAPNG Block Types  . . . . . . . . . . . . . . . . . . . . . . . . . .  3

        2.1.1 PCAPNG IDB     . . . . . . . . . . . . . . . . . . . . . . . . . .  3

        2.1.2 PCAPNG EPB     . . . . . . . . . . . . . . . . . . . . . . . . . .  3

    2.2  PPI Packet  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

        2.2.1 PPI Packet Header  . . . . . . . . . . . . . . . . . . . . . . . .  4

        2.2.2 PPI Field Header   . . . . . . . . . . . . . . . . . . . . . . . .  4

3  New PPI Fields                                                                 4

    3.1  End of Frame Timestamp  . . . . . . . . . . . . . . . . . . . . . . . .  4

    3.2  FCS Length  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

    3.3  IEEE 802.15.4 PHY Encoding  . . . . . . . . . . . . . . . . . . . . . .  5

    3.4  IEEE 802.15.4 PHY Receiver Information . . .. . . . . . . . . . . . . .  5

    3.5  IEEE 802.15.4 TSCH-MAC  . . . . . . . . . . . . . . . . . . . . . . . .  5

4  Glossary                                                                       7

1    Introduction

IEEE 802.15.4 is a wireless standard for Low-Rate Wireless Personal Area
Networks (LR-WPANs) defining a number of physical layers (PHYs) covering a wide
variety of freqency bands and a number of Media Access Control (MAC) sub-layers
for managing data and management services including beacon management, channel
access, frame delivery and validation, and security mechanisms.  Developing and
maintaining technologies using IEEE 802.15.4 generally require capturing
packets with a sniffer. Sniffers output captured packets using a specified data
link-type (DLT). [1]

Three existing link-types for IEEE 802.15.4 are defined

   o DLT_IEEE_802_15_4_WITHFCS (195),

   o DLT_IEEE802_15_4_NONASK_PHY (215), and

   o DLT_IEEE_802154_NOFCS (230).

None of these link-types provide a means to include out-of-band meta-data such
as received signal strength and channel number which are useful for diagnostics
in any wireless transmission system.

CACE Technologies introduced the Per-Packet Information (PPI) DLT (192), to
allow arbitrary data to be included with each packet using a Type-Length-Value
(TLV) format, and every packet to encapsulate a different link-type. The
original specification defined field types for IEEE 802.11 Wi-Fi but also
explictly allows for other capture information to be defined using
General-purpose or Vendor-specific field types.  Harris Corporation for example
has defined vendor-specific fields for Geolocation infomation. [2]

Additional TLV Field Types for the PPI link-type are proposed to support IEEE
802.15.4 meta-data from sniffers.

2    Overview

The PPI link-type is specified in the pcap header or pcapng interface
description block (IDB) before the the first packet. Each PPI packet includes a
DLT identifier for the encapsulated capture data, zero or more TLV fields, and
the captured data. A DLT_PPI formatted packet is encapsulated in the packet
data following a pcap record header or in the packet data of a pcapng Enhanced
Packet Block (EPB).

2.1    PCAPNG Block Types


2.1.1     PCAPNG IDB

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                Block Type = 0x00000001                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                   Block Total Length                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  LinkType = DLT_PPI (192)     |        reserved               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          SnapLen                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Options (variable)                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                   Block Total Length                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

2.1.2     PCAPNG EPB

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                   Block Type = 0x00000006                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Interface_ID                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Timestamp (High)                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       Timestamp (Low)                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Captured Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Original Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          PPI  Packet                          |
   |                variable length, padded to 32 bits             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       Options (variable)                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


2.2   PPI Packet

The PPI Packet consists of a PPI Packet Header, zero or more PPI Field Headers, and the original
capture data.

2.2.1      PPI Packet Header
    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  pph_version  |   pph_flags   |            pph_len            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |            pph_dlt = DLT_IEEE_802_15_4_WITHFCS                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

pph_len - length of of entire message including this header and optional TLV payload.

2.2.2     PPI Field Header

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           pfh_type            |           pfh_datalen         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

pfh_datalen - length of data, in bytes, that follows.

3    New PPI Fields

All fields are in little-endian byte order.

3.1   End of Frame Timestamp

The end of frame timestamp as reported by the PHY. This value is important to
time-slotted MACs where a packet may overflow a time slot. The start of frame
timestamp is present in the pcap or pcapng header.

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      (TBD Assigned Type + 0)  |        datalen (8)            |}   PPI_Field Header
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           seconds                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        microseconds                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

3.2   FCS Length

The length of the FCS included at the end of the encapsulated DLT (if
supported) may be changed by this field.

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    (TBD_Assigned_Type_+_1)    |     datalen (4)               |}   PPI_Field Header
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   FCS length  |                  reserved                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The FCS length may be 0, 2, or 4.
   o  DLT_IEEE_802_15_4_WITHFCS - 2 or 4

   o  DLT_IEEE_802154_NOFCS - always 0

3.3   IEEE 802.15.4 PHY Encoding

An IEEE 802.15.4 PHY is configured to operate in a specified frequency band,
encoding type, and rate mode.

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   (TBD_Assigned_Type_+_2)     |         datalen (4)           |}   PPI_Field Header
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Band        |   Type        |     Mode      |   padding     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   o Band - IEEE 802.15.4 Table 7-19 Frequency band identifer values.

   o Type - IEEE 802.15.4 Table 7-20 Modulation scheme encoding values.

   o Mode - IEEE 802.15.4 Rate mode depends on the Band and Type.

3.4   IEEE 802.15.4 PHY Receiver Information

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    (TBD_Assigned_Type_+_3)    |           datalen (8)         |}   PPI_Field Header
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   RSS         |  Channel_page |      Channel_number           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Bit_rate                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   o RSS - Received Signal Strength (-128 to 127).

   o Channel page - Channel page for the channel number.
       See IEEE 802.15.4-2015 10.1.2 Channel assignments.

   o Channel number - channel number within the channel page.

   o Bit rate - in bits per seconds.

3.5   IEEE 802.15.4 TSCH-MAC

For a Time-slotted Channel Hopping MAC, the Absolute Slot Number (ASN) and
Start of slot timestamp are important for diagnostics and decryption. The ASN
forms part of the nonce for decryption. The start of slot timestamp which
preceeds the start of frame timestamp is essential for debugging and optimizing
TSCH configurations.

    0                   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   (TBD Assigned Type + 4)     |          datalen (24)         |}  PPI Field Header
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                            ASN (64-bits)                      |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                Start of slot timestamp seconds                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |              Start of slot timestamp microseconds             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

4    Glossary


         | Notation       |Description                                      |
         |                |                                                 |
         | DLT            |Data-Link Type                                   |
         |                |                                                 |
         | EPB            |Enhance Packet Block (pcapng)                    |
         |                |                                                 |
         | FCS            |Frame Check Sequence                             |
         |                |                                                 |
         | IDB            |Interface Description Block (pcapng)             |
         |                |                                                 |
         | IEEE           |Institute for Electrical and Electronic Engineers|
         |                |                                                 |
         | LR-WPAN        |Low-Rate Wireless Personal Area Network          |
         |                |                                                 |
         | MAC            |Medium Access Control                            |
         |                |                                                 |
         | pcap           |Packet Capture File Format [3]                   |
         |                |                                                 |
         | pcapng         |PCAP Next Generation Capture File Format [4]     |
         |                |                                                 |
         | PDU            |Protocol Data Unit                               |
         |                |                                                 |
         | PHY            |Physical Layer                                   |
         |                |                                                 |
         | PPI            |Per-Packet Information                           |
         |                |                                                 |
         | TLV            |Type-Length-Value                                |
         |                |                                                 |
         | TSCH           |Time-Slotted Channel Hopping                     |
         |                |                                                 |

References

1. https://www.tcpdump.org/linktypes.html - Data-Link Types
2. https://media.blackhat.com/bh-us-11/Cache/BH_US_11_Cache_PPI-Geolocation_WP.pdf - Geolocation PPI Specification
3. https://wiki.wireshark.org/Development/LibpcapFileFormat - Packet Capture File Format
4. https://pcapng.github.io/pcapng/ - PCAP Next Generation Capture File Format