Libtrace Wireless Support

Libtrace3 contains functions that allow easy access to wireless metadata attached to frames in wireless traces. For example, a trace taken from a ​MadWiFi based monitor mode VAP can have Radiotap or Prism headers prepended to each IEEE802.11 frame. These headers include information such as bitrate, signal strength, etc, for each packet. Libtrace's wireless support allows access to this information in a consistent manner, no matter what frame encapsulation is used.

Note, as of libtrace 3.0, only Radiotap encapsulation is supported.

General API

The complete wireless API can be found ​here. We will give a brief overview and example of its usage below.

All wireless functions are named trace_get_wireless_*, where * is the wireless metadata that you are interested in. Each of the functions returns a bool which indicates whether the requested metadata could be found in the packet. Each function takes a void pointer to the start of the metadata header (usually obtained by trace_get_link(pkt)), a linktype to indicate the type of encapsulation (usually obtained by trace_get_link_type(pkt)), and an address to store the resulting metadata.

Trace Processing Example

For example, assume we want to retrieve the signal strength in dBm for each packet in our trace:

while (trace_read_packet(trace, pkt) > 0)
{
    int8_t signal;
    trace_get_wireless_signal_strength_dbm(trace_get_link(pkt), trace_get_link_type(pkt), &signal);
    printf("%i dBm\n", signal);
}

Note that in this code we have not specified what encapsulation is used. The trace_get_wireless_* methods will skip Linux SLL headers automatically and figure out how to obtain the metadata. Note that if the packet does not contain the requested metadata, the trace_get_wireless_* functions will return false, and the value in the output parameter is undefined.

Capturing Traces with Wireless Metadata

As an aside, we will explain how to capture traces that include useful metadata suitable for use in Libtrace. The example given below is based on ​MadWiFi version 0.9.3, however the same principles apply to other wireless drivers. The only pre-requisite is that a driver be capable of prepending a supported wireless metadata format to frames. Also note that as of Libtrace 3.0, the wireless support is limited to Radiotap encapsulation, though Prism AVS is planned (though it appears that Prism support is to be deprecated in upcoming Linux kernels in favour of the more extensible Radiotap).

Setting up MadWiFi for Radiotap

• Create a new Monitor mode VAP:

wlanconfig mon0 create wlandev wifi0 wlanmode mon

(where mon0 is the name of the monitor mode vap, and wifi0 is the name of the MadWiFi base device)

• Enable Radiotap encapsulation:

echo '803' > /proc/sys/net/mon0/dev_type

• Capture packets using either tcpdump -w or tracesplit, e.g.

tracesplit int:mon0 pcapfile:trace.pcap

You can then open the trace trace.pcap with your libtrace application and use the trace_get_wireless_* methods to extract per-packet metadata.

tracepktdump

The tracepktdump tool has been updated to decode both Radiotap and IEEE 802.11 frames. For example, run tracepktdump pcapfile:trace.pcap and you will get the following output:

Thu Mar  1 13:42:24 2007
 Radiotap: version: 0, length: 32, fields: 0x00586f
 Radiotap: TSFT = 160302265 microseconds
 Radiotap: Flags = 0x02
 Radiotap: Rate = 12000 kbps
 Radiotap: Freq = 2437 MHz, ChanFlags: 0x0480
 Radiotap: Signal = -79 dBm
 Radiotap: Noise = -96 dBm
 Radiotap: Antenna = 1
 Radiotap: Signal = 17 dB
 Radiotap: Frame Check Sequence = 0x59dc1264
 802.11MAC: proto = 0, type = 2, subtype = 8, flags = toDS retry
 802.11MAC: Data frame: QoS Data
 802.11MAC: duration = 52 us
 802.11MAC: fragment no. = 0, sequence no. = 3887
 802.11MAC: DA      = 00:0b:6b:34:87:da
 802.11MAC: SA      = 00:0b:6b:34:88:3d
 802.11MAC: BSSID   = 00:0b:6b:34:87:da
 802.11e: QoS = 0x0000
 802.11MAC: Payload ethertype = 0x0800
 IP: Header Len 20 Ver 4 DSCP 00 ECN 0 Total Length 1500
 IP: Id 25416 Fragoff 32
 IP: TTL 64 Proto 1 (icmp) Checksum 35178
 IP: Source 192.168.1.2 Destination 192.168.1.1
 ICMP: Type: 8 (ICMP Echo Request) Sequence: 1