ieee80211 package
Information on this package is covered here.
|
Package
|
Description
|
License
|
|
ieee80211
|
Devicescape 802.11 stack for DataPath driver.
|
|
(For information on modifying/extending this package, see the "DataPath Driver" topic in the Developer Guide.)
Summary
The Devicescape DataPath driver is the software that controls the radio hardware on the target device on which the runtime system is deployed. The DataPath driver provides a well-defined interface between the higher-level Access Point or wireless client functions and the low-level radio drivers.
Usage
Start/Stop Options
Use the following commmands to control the DataPath driver (ieee80211) on the target device.
|
Action
|
Command
|
|
Start
|
/etc/init.d/ieee80211 start
|
|
Stop
|
/etc/init.d/ieee80211 stop
|
|
Restart
|
/etc/init.d/ieee80211 restart
|
There are no parameters defined for this script.
Runtime Configuration
Access Point Configuration
The Devicescape 802.11o module uses hostapd for Access Point configuration. (See hostapd package).
Client Configuration
If you are configuring a client device (wpa_supplicant), you will set most options in wpa_supplicant.conf (see Runtime Configuration (wpa_supplicant.conf) of wpa_supplicant package documentation). However, the following driver-specific options must be configured in the driver. For the 802.11o driver, use ieee-tools to configure these options.
(The following options and examples are shown here for convenience. For complete information on these configuration options, see ieee80211-tools package.)
Wi-Fi Multimedia Extensions
To configure Wi-Fi Multimedia (WMM) extensions, use the iwpriv command.
|
Notes
|
- The interface must be down (
iconfig eth1 down) when changing the Wi-Fi Multimedia (WMM) configuration. - WMM extensions are disabled by default.
|
To enable WMM extensions:
iwpriv sta0 param 1038 0
To disable WMM extensions:
iwpriv sta0 param 1038 1
Country/Regulatory Domain
The regulatory domain is set when loading the kernel module (80211.o):
Currently, only FCC and MKK/TELEC are supported.
To set the regulatory domain to FCC/U.S. (which is the default):
insmod 80211.o ieee80211_regdom=32
To set the regulatory domain to MKK/TELEC/Japan
insmod 80211.o ieee80211_regdom=64
Wireless Monitor Mode (Sniffer)
See Wireless Sniffer in the Wireless Testing Tools section.
External APIs
Thie Devicescape DataPath driver 80211.o module provides as an external interface for user programs. Examples of programs that use the external API of the 80211.o module are:
Debugging (80211.o module procfs tree)
The 80211.o module provides a procfs tree for easy access to configuration and statistics information of data collected within kernel module.
The root of 80211.o procfs tree is /proc/net/ieee80211. Each radio interface has its own subtree in this directory. The name of the subtree root directory is the same as the main netdevice of that interface (wlan#); for example, /proc/net/ieee80211/wlan0.
For example, the following files show radio specific information for the wlan0 interface for an Access Point in /proc/net/ieee80211/wlan0:
configcountersdebugifacemulticastratessta
|
Note
|
- This procfs interface is designed primarily for debugging use and, therefore, does not include information that is collected in user space hostapd process. In future releases, some functionality may be moved from 80211.o into hostapd and the related information will at that point be removed from the
procfs tree.
- In the following sections, the various data values are shown the way they will appear in the file, with example values (for example, "
channel=11").
|
Radio Interface Specific Files (/proc/net/ieee80211/wlan#/*)
config
channel=11
freq=2462
mode=IEEE 802.11g
wep_iv=0xe128ff
antenna_sel=0
calib_int=60
tx_power_reduction=0.0 dBm
bridge_packets=1
key_tx_rx_threshold=0
rts_threshold=2347
fragmentation_threshold=2346
short_retry_limit=7
long_retry_limit=4
total_ps_buffered=0
counters
TransmittedFragmentCount=2000
MulticastTransmittedFrameCount=303
FailedCount=46
ReceivedFragmentCount=1298
MulticastReceivedFrameCount=1227
TransmittedFrameCount=888
WEPUndecryptableCount=0
ACKFailureCount=8029
RTSFailureCount=0
FCSErrorCount=5468
RTSSuccessCount=0
Virtual Interface Specific Files (/proc/net/ieee80211/wlan#/iface/*)
Each virtual interface; for example, wlan# for the default data interface and each virtual interface configured in multi_ssid blocks of hostapd.conf, has its own file that contain generic information about the interface. This includes interface type (norm/wds/vlan) and default (broadcast) encryption algorithm and keys (if in use).
Following are some typical entries in an example file:
type=norm
channel_use=0
drop_unencrypted=0
<Optional_Encryption_Key_Entries>
Here are the details on most options and values in the above example file:
|
Example
|
Description
|
|
channel_use=0
|
Estimated channel (air time) use of this interface in 1/1000. (For example, 10 = 1 percent.)
|
|
drop_unencrypted=0
|
Drop all unencrypted TX and RX frames from this interface.
|
|
key[<idx]>[*] len=<len> sw_encrypt=<val> idx=<val>
hwidx =<val> tx_rx_count=<val> alg=<str> ... [alg specific data]
|
Optional encryption key entries (default/broadcast keys)
|
Station Information (/proc/net/ieee80211/wlan#/sta/*)
Each associated station has its own file (with the hardware/MAC address as the file name) that includes state information and statistics. Stations that are not associated are not in the 80211.o station table and, consequently, they do not have procfs entry. These stations may have an entry in the hostapd tables and, if so, that information is available through the hostapd interface. (See hostapd package.)
xx:xx:xx:xx:xx:xx (for example, FE:DC:BA:09:87:65)
Following is the contents of an example STA file (named <SomeMACAddress>) in /proc/net/ieee80211/wlan#/sta/. Parameters and values found in this file are described below.
users=1
aid=1
flags=0xa3 [AUTH][ASSOC][AUTHORIZED][SHORT PREAMBLE]
key_idx_compression=-1
dev=wlan0
rx_packets=3
tx_packets=3
rx_bytes=439
tx_bytes=459
rx_duplicates=1
rx_fragments=3
rx_dropped=1
tx_fragments=3
tx_filtered=0
key[0]* len=32 sw_encrypt=0 idx=0 hwidx=1 tx_rx_count=2 alg=TKIP
iv(tx)=00000000 0001 iv(rx 0)=00000000 0001
key=d60eff2f44369a8147e90ce9d8dda0a6fd4a8c6fe16fa2394c9fe4363db37970
tx_avg_rate_avg=37
txrate=55
last_txrate=10
num_ps_buf_frames=0
tx_retry_failed=0
tx_retry_count=1
last_rssi=51
last_ack_rssi=40 35 35
last_ack_ms=6590
inactive_msec=6560
channel_use=0
wep_weak_iv_count=0
wme_rx_queue=4 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
wme_tx_queue=0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
last_seq_ctrl=680 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
last_rate_ctrl_rssi=0
rate: num_tx / rssi_thresh / MPDU not ACKed (%)
10: 3 / 0 / 3
20: 0 / 1 / 0
55: 0 / 2 / 0
60: 0 / 2 / 0
90: 0 / 3 / 0
110: 0 / 3 / 0
120: 0 / 4 / 0
180: 0 / 6 / 0
240: 0 / 10 / 0
360: 0 / 14 / 0
480: 0 / 19 / 0
540*: 0 / 23 / 0
Here are the details on most options and values in the above example file:
|
Example
|
Description
|
|
flags=0x3 [AUTH][ASSOC][AUTHORIZED]
[SHORT PREAMBLE]
|
Station flags:
- AUTH=authenticated
- ASSOC=associated
- AUTHORIZED=IEEE 802.1X authorized
- PS=in power saving mode
- TIM=buffered frame pending for STA in PS mode
|
|
dev=wlan0
|
Data device to which this station is bound
|
|
rx_packets=3
|
Number of received packets (MSDU)
|
|
tx_packets=3
|
Number of transmitted packets (MSDU)
|
|
rx_bytes=439
|
Number of received bytes
|
|
tx_bytes=459
|
Number of transmitted packets
|
|
rx_duplicates=1
|
Number of received MPDUs that were dropped because they were duplicates.
|
|
rx_fragments=3
|
Number of received fragments (MPDU
|
|
rx_dropped=1
|
Number of received MPDUs that were dropped for any reason (for example,duplicates and failed decryption).
|
|
tx_fragments=3
|
Number of transmitted fragments (MPDU)
|
|
txrate=55
|
Current transmission rate (for AP-to-STA transmissions) in 100 kbps. For example, 55 = 5.5 Mbps.
|
|
tx_avg_rate_avg=37
|
Transmission rate average value
|
|
num_ps_buf_frames=0
|
Number of buffered frames for this station (power saving mode)
|
|
tx_retry_failed=0
|
Number of times transmission failed due to excessive retries
|
|
tx_retry_count=1
|
Total number of retries used for TX packets
|
|
last_rssi=51
|
Received Signal Strength Indication ( RSSI) of the last received frame
|
|
last_ack_rssi=40 35 35
|
RSSI of the last received frame
|
|
last_ack_rssi=61
|
RSSI of the acknowledgement ACK to the last sent Unicast frame
|
|
inactive_msec=6560
|
Number of milliseconds from the last received frame
|
|
channel_use=0
|
Estimated channel (air time) use of this STA in 1/1000. (For example, 10 = 1 percent.)
|
Wireless Testing Tools
The 80211.o module (ieee80211 package) can be configured to run as a wireless sniffer, virtual client simulator, WPA testing tool, and frame generator. You can configure the driver for these modes to test the runtime software deployed on your target wireless devices. Therefore, we refer to these modes as "wireless testing tools" in the following sections.
The platform wireless testing tools incorporate the use of iwconfig and iwpriv commands from the open source Linux wireless-tools package (see wireless-tools package).
The Devicescape tools require an up-to-date version of these Linux wireless-tools (version 25 or newer). We recommend that you use the wireless-tools package included with the platform to ensure proper functionality of the testing tools.
Wireless Sniffer
The 80211.o module (available as part of the ieee80211 package) is normally used in access point mode with user space daemon (hostapd). However, the 80211.o module can also be used as wireless sniffer when used with Atheros ar521x low-level driver (oahu.o). This mode can be used to debug network issues and it does not use hostapd.
The following sections describe how to set up, configure, and deploy the Devicescape wireless sniffer:
Prerequisites and Troubleshooting Sniffer Setup
Setting the driver in monitor mode requires some manual configuration (that hostapd takes care of when in AP mode). After the driver is configured properly, any Linux IEEE 802.11 sniffer that supports special sniffer header (dev->type == ARPHRD_IEEE80211_PRISM) can be used to record full IEEE 802.11 frames including some meta data like used transmit rate and signal strength.
Currently, the only tested and recommended sniffer setup is Ethereal with libpcap. Please note that you will need to get the latest or at least one of the most recent versions of libpcap and Ethereal to actually support the sniffer header in the frames.
- A recent version of libpcap is provided in the platform Linux distribution.
- Get Linux wireless-tools from the wireless-tools package that comes with the platform.
First, compile libpcap and install it (unless you already have a recent version of libpcap; version 0.6.x is not new enough).
Then, compile Ethereal using this libpcap version (use --with-pcap=DIR option to specify where the new libpcap version is installed).
Please note that IEEE 802.11 frame control checksum (FCS) is included in the frames, so Ethereal needs to be configured to assume this (Edit | Preferences... | Protocols | IEEE 802.11 | Assume packets have FCS).
If Authentication, Association Request, and Associate Response packets have [Malformed Packet] in their Info field, it means this has not been done successfully. Select "Save" (rather than "OK") to make this change persistent.
The WEP bit is set correctly, so "Ignore the WEP bit" should not be set on the same preference page.
You will also need to have both the generic Instant802 IEEE 802.11 module (80211.o) and Atheros low-level driver (oahu.o) for host that is going to be used as the sniffer.
Configuring the DataPath Driver for Monitor Mode
Following steps can be used to configure driver for monitor mode:
- Load the modules:
- insmod 80211.o
- insmod oahu.o
- Unmask all channels so that they can be used without hostapd:
iwpriv wlan0 param 1007 1
- Enable the radio:
iwpriv wlan0 param 1010 1
- Change the driver to monitor mode:
iwconfig wlan0 mode monitor
- Set the IEEE 802.11 interface and the "management interface" up (these do not need IP address):
ifconfig wlan0.11 up
ifconfig wlan0ap up
- Select frequency (for example, IEEE 802.11g channel 1):
iwconfig wlan0 freq 2412M
- Start ethereal (use wlan0ap interface for receiving IEEE 802.11 frames):
ethereal -ni wlan0ap
Changing Channels
The used channel can be selected with iwconfig's 'freq' command. In addition, iwconfig's 'channel' command can be used, but it may require additional mode configuration with iwpriv because not all channel numbers are equal (e.g., channel 8 is used both with IEEE 802.11g 2.447 GHz and IEEE 802.11a 5.040 GHz).
- Select hardware mode for next channel selection (IEEE 802.11a)
iwpriv wlan0 param 1008 0
- Select channel 8 (5.040 GHz)
iwconfig wlan0 channel 8
- Select hw mode for next channel selection (IEEE 802.11g)
iwpriv wlan0 param 1008 3
- Select channel 8 (2.447 GHz)
iwconfig wlan0 channel 8
|
Note
|
The following hardware modes are currently supported:
0 = IEEE 802.11a
1 = IEEE 802.11b only
2 = Atheros Turbo (5 GHz)
3 = IEEE 802.11g
|
Filtering Packets
Ethereal supports two kinds of filters: capture filters and display filters. Capture filters are executed in the kernel, so they are much more efficient at filtering out large amounts of traffic. They are provided by libpcap, and use the same syntax for filters as tcpdump. Display filters are provided by Ethereal, so they are less efficient. But their filter syntax understands more protocols and fields, including those in IEEE 802.11, and can be constructed using Ethereal's graphical user interface.
Here are some capture filters that may be useful:
|
No beacons
|
link[64] != 0x80
|
|
No probe request
|
link[64] != 0x50
|
|
No probe responses
|
link[64] != 0x40
|
|
No CTSs
|
link[64] != 0xc4
|
|
No ACKs
|
link[64] != 0xd4
|
|
No spanning tre
|
link[68:4] != 0x0180c200
|
|
No spanning tree (WDS)
|
link[80:4] != 0x0180c200
|
Virtual Client Station Simulator
The ieee80211 package includes a 80211.o module which supports client modes (BSS/infrastructure mode and IBSS/ad-hoc mode). This can be used to implement normal client functionality or a test mode in which one radio can be used to simulate multiple virtual stations, e.g., for AP testing.
The following sections describe how to set up, configure, and use the virtual client simulator:
Configuring the DataPath Driver for Client Mode
To configure radio driver for client mode, do the following:
- Load these modules on the target system:
- insmod 80211.o
- insmod oahu.o
- Change MAC address, if needed. This is mainly used for the virtual station mode in which the least significant bits (i.e., the last hex digits of the address) need to be zeroes.
ifconfig wlan0 hw ether 02:01:02:03:00:00
- Set IEEE 802.11 interface up (this interface does not need an IP address)
ifconfig wlan0.11 up
- Configure the driver for client/Managed mode:
iwconfig wlan0 mode managed
- For virtual station mode (not used in normal client mode), set the mask for own MAC address to allow 2048 virtual stations:
ds_iftool wlan0 bss ff:ff:ff:ff:f8:00 2048
|
Note
|
Note that (own_mac_addr & ~mask) have to 00:00:00:00:00:00, i.e., the least significant bits of the own address have to be zeroes.
|
- Add a client interface
ds_iftool wlan0 sta add sta0
|
Notes
|
- The
wpa_supplicant is normally used to control the client functionality in normal client mode (both BSS/infrastructure and IBSS/ad-hoc). See wpa_supplicant package for more information. - Please note that
wpa_supplicant will need to be configured to use the interface name created here with ds_iftool (that is, "-ista0" on command line in this example) and i802 driver interface (-Di802).
|
Configuring Wireless Parameters on Virutal Stations
The open source wireless tools iwconfig and iwpriv can be used to configure various parameters relating to IEEE 802.11 and wireless operations. (See wireless-tools package.) The options listed here are available for both wpa_supplicant and manual association modes.e.
|
Parameter
|
Syntax Example and Details
|
|
Fragmentation Threshold
|
iwconfig sta0 frag <FragmentationThreshold>
|
|
RTS Threshold
|
iwconfig sta0 rts <RTSThreshold>
|
|
Short Retry Limit
|
iwconfig sta0 retry min <ShortRetryLimit>
|
|
Long Retry Limit
|
iwconfig sta0 retry max <LongRetryLimit>
|
|
WMM (Wi-Fi Multimedia extensions):
|
iwpriv sta0 param 1038 <0_or_1>
- 0 = disabled (default)
- 1 = enabled
|
|
New IBSS (for ad-hoc mode):
|
iwpriv sta0 param 1037 <0 or 1>
- 0 = disabled; that is, only join an existing network
- 1 = enabled; that is, create a new IBSS if no existing network is found
|
|
Allowed radio hardware modes
(IEEE 802.11a, IEEE 802.11b, etc.):
|
iwpriv sta0 param 1036 <BitfieldOfEnabled_hw_mode>
- bit0 = IEEE 802.11a
- bit1 = IEEE 802.11b
- bit2 = Atheros Turbo (5 GHz)
- bit3 = IEEE 802.11g
- bit4 = Atheros TurboG (2.4 GHz)
For example, 1 = IEEE 802.11a only, 10 = IEEE 802.11b and IEEE 802.11g
|
|
Forced TX (transmit) rate for unicast packets
|
iwpriv sta0 param 1018 <RateIn100kbps>
(10 = 1 Mbps, 55 = 5.5 Mbps, 540 = 54 Mbps, and so on)
|
Manual Association
When plaintext mode is used, Linux wireless tools (iwconfig and iwpriv) can be used to configure association parameters manually. (See wireless-tools package.)
This type of manual associatoin is normally used only for testing with the virtual station setup. When using wpa_supplicant, this configuration is not needed.
To create an association using iwconfig and iwpriv commands:
- Set the channel.
iwconfg sta0 channel 11
- Set the SSID.
iwconfig sta0 essid "test network"
- Set the BSSID
iwconfig sta0 ap 02:11:22:33:44:55
Changing Channels
The currently channel can be selected with the Linux iwconfig "freq" command. In addition, the iwconfig "channel" command can be used, but it may require additional mode configuration with iwpriv because not all channel numbers are equal. (Fo example, channel 8 is used both with IEEE 802.11g 2.447 GHz and IEEE 802.11a 5.040 GHz).
These options are only used in manual association mode; wpa_supplicant takes care of channel configuration internally.
To change channels using iwpriv and iwconfig commands:
- Select hardware mode for the next channel selection (IEEE 802.11a):
iwpriv wlan0 param 1008 0
- Select channel 8 (5.040 GHz):
iwconfig wlan0 channel 8
- Select the hardware mode for next channel selection (IEEE 802.11g):
iwpriv wlan0 param 1008 3
- Select channel 8 (2.447 GHz)
iwconfig wlan0 channel 8
|
Note
|
The following hardware modes are currently supported:
0 = IEEE 802.11a
1 = IEEE 802.11b only
2 = Atheros Turbo (5 GHz)
3 = IEEE 802.11g
4 = Atheros TurboG (2.4 GHz)
|
Client Interface
The 80211.o module supports virtual data interfaces. More than one virtual interface can be used at the same time to operate as multiple "virtual" stations. Each station must have its own MAC address. This is very similar to multi-BSSID support in the Access Point code.
A separate tool, ds_iftool, is needed for adding new virtual interfaces. This tool is also used to set MAC address mask for multiple virtual station functionality.
The MAC address of the radio interface much be set in the same way as in multi-BSSID case; that is, the least significant bits must be zeroes. This can be changed with the following command:
ifconfig wlan0 hw ether <new MAC address>
|
Note
|
Please note that the MAC address of the radio interface must not be changed after virtual client interfaces are created.
Make sure that the used MAC address and all addresses covered by the address mask are unique and do not collide with any other device.
|
Example Scripts
Starting Virtual Wireless Clients (start.STA)
#!/bin/sh
insmod 80211.o
insmod oahu.o
ifconfig wlan0 hw ether 02:01:02:03:00:00
ifconfig wlan0.11 up
iwconfig wlan0 mode managed
iwconfig wlan0 channel 40
ds_iftool wlan0 bss ff:ff:ff:ff:f8:00 2048
Adding Client Stations (add.STAs)
- #!/bin/sh
- for i in `seq 0 $1`; do
- ds_iftool wlan0 sta add sta$i
- ifconfig sta$i up 10.0.$i.2 netmask 255.255.255.0 broadcast 10.0.$i.255
- iwconfig sta$i essid test-ssid
- iwconfig sta$i ap 00:01:02:03:04:05
- done
|
Notes
|
- For line 4 in the "add.STAs" example script, modify IP addresses based on the test setup.
- For lines 5 and 6 in the "add.STAs" example script, wpa_supplicant can be used as an alternative to iwconfig if the network requires WPA
|
Deleting Client Stations (del.STAs)
#!/bin/sh
for i in `seq 0 $1`; do
ifconfig sta$i down
ds_iftool wlan0 sta del sta$i
done
Stopping Client Stations (stop.STA)
#!/bin/sh
ifconfig wlan0.11 down
rmmod oahu
rmmod 80211
WPA Testing Tool
WPA TKIP uses a compromise in the strength of the encryption algorithm and capabilities of existing devices. Consequently, the authentication part of the protocol, Michael MIC, can be breaking with brute force attacks. As a way to make this kind of attack more difficult, WPA TKIP implements countermeasures that limit the maximum frequency at which an attacker can send modified packets to about once per minute.
TKIP countermeasures needs support from both the Access Point and Client sides and consequently, it is part of interoperability testing for WPA. The 80211.o module includes testing functionality that can be used to simulate Michael MIC failures both for outgoing and incoming TKIP packets. This can be used to test TKIP countermeasures testing which is part of the Wi-Fi Aliiance certification tests for WPA.
Disabling Testing Code in the 80211.o Module
The default build of the 80211.o module includes this testing code since it does not have a large overhead for normal operations. This functionality can be disabled by removing CONFIG_HOSTAPD_WPA_TESTING define from the Makefile. A small amount of memory (4 bytes per association station) and a couple of branches on TX/RX fast path can be saved by removing this test code.
wpa_test_trigger
In addition to test code in 80211.o module, a user space tool is needed to control WPA testing. This tool, wpa_test_trigger, can be built with 'make tools' and it is included in the ieee80211-tools package.
When run without any parameters, wpa_test_trigger prints out brief description of the command line arguments:
wpa_test_trigger Syntax and Options
wpa_test_trigger <device> <STA addr> <flags>
|
Option
|
Description
|
|
<device>
|
The radio interface for the device in the form wlan<Number>.
For example: wlan0
|
|
<StationAddress>
|
The MAC address (hardware address) of the client station.
|
|
<flags>
|
WPA trigger flags:
- bit0 (1) = corrupt next TX Michael MIC
- bit1 (2) = corrupt next TX TKIP ICV
- bit2 (4) = corrupt next RX Michael MIC
- bit3 (8) = corrupt next RX TKIP ICV
- bit4 (16) = do not increment replay counter on next TX (TKIP/CCMP)
- bit5 (32) = do not increment replay counter on next TX of a fragment (TKIP/CCMP)
- bit6 (64) = skip TX sequence number on next TX (CCMP fragm)
|
This tool can be used to configure test flags for the next TKIP packet. The flags can be set for each station by using the MAC address of the station as the selected. In addition, testing can be done with multicast frames, in which case the address is set to all-ones broadcast address (ff:ff:ff:ff:ff:ff).
The 80211.o module will use the testing flag for the next packet and the flag will be cleared automatically after this. If more than one test packet is needed, the wpa_supplicant_trigger will need to be run multiple times.
The test code supports corrupting both TKIP ICV (WEP checksum) and Michael MIC (data authenticity hash). However, in most cases, only Michael MIC failures are used since they are used as a trigger to TKIP countermeasures. The command line argument <flags> is thus set to 1 (bit0) or 4 (bit2) to trigger corruption of the next TX or RX packets, respectively. The Wi-Fi Alliance test plans for WPA use a an "attacker" tool which is either an Access Point or a client sending packets with an invalid Michael MIC. For these cases, only the flags value 1 is used. Corruption of received packets (flags value 4) can be used to test the other direction without having to use another attacker tool.
Example Test Procedure
Setup an access point (AP) in a normal way with 80211.o and hostapd. Configure it to use WPA with TKIP as the encryption algorithm. Associate one or more stations with it. Pick one of the associated stations as the target for the test; that is, it would be the STAUT in Wi-Fi test plan. Verify that you can ping STAUT from the AP.
In the example commands, the MAC address of this STAUT is assumed to be 02:01:02:03:04:05 and IP address 192.168.1.2.
Run the following commands on the AP to send the next frame with an invalid Michael MIC:
wpa_test_trigger wlan0 02:01:02:03:04:05 1
ping -c 1 192.168.1.2
As a result, the client is supposed to notice the failure and report it to the AP. This will trigger a rekeying (new 4-Way Handshake). If this is repeated twice within 60 seconds, TKIP countermeasures are initialized. As a results, the data connection will stop for 60 seconds. This can be verified, for example, by running the ping command continuously instead of using the "-c 1" argument to send only one packet. STAUT is expected to re-associate after the countermeasures and data connection should be restored within about 70 seconds after the second packet with invalid Michael MIC is sent.
For testing the AP, this test can be repeated by using the wpa_test_trigger command on the client that is using 80211.o module and wpa_supplicant. Alternatively, when testing the AP that is using 80211.o, the option to corrupt received frames (flags 4) can be used to test the key management part (4-Way Handshake) without having to set up a special client as the attacker. However, this does not test the capability of the AP to detect invalid Michael MIC, so the recommended procedure for the full test is to use an attacker tool in the client.
Replay Testing
The wpa_test_trigger can also be used to test whether a TKIP/CCMP implementation performs the required test on the packet number/sequence counter. The easiest setup for these tests is to set up a testbed device (either AP or STA) with 80211.o, associate the device under test (either STA or AP) with the testbed device, and start a continuous ping between these two devices. The following tests should be performed:
- TKIP/CCMP - normal replay detection:
wpa_test_trigger wlan0 <APUT/STAUT MAC Address> 16
APUT/STAUT is expected to drop one packet which should be visible in the ping output. The connection remains working even if this test is repeated number of times.
- TKIP/CCMP - replay of a fragmented frame:
Set testbed device with fragmentation threshold of 512 bytes. Set ping to use data size larger than 512.
wpa_test_trigger wlan0 <APUT/STAUT MAC Address> 32
APUT/STAUT is expected to drop one packet which should be visible in the ping output. The connection remains working even if this test is repeated number of times.
CCMP - PN not sequential for fragments:
Set testbed device with fragmentation threshold of 512 bytes. Set ping to use data size larger than 512.
wpa_test_trigger wlan0 <APUT/STAUT MAC Address> 64
APUT/STAUT is expected to drop one packet which should be visible in the ping output. The connection remains working even if this test is repeated number of times.
|
Note
|
This test does not apply for TKIP which does not have such a requirement.
|
Arbitrary Frame Generator
The send_frame tool (included in the ieee80211-tools package) can be used to send arbitrary IEEE 802.11 frames. For example, this can be used to send an invalid association request to te AP and a wireless sniffer can be used verify whether the AP replies with an expected error code.
send_frame can be used in any mode; that is, the device can be configured to AP mode with hostapd, client modes with wpa_supplicant, or wireless monitor mode (sniffer).
The wlan<Number>ap interface (for example, wlan0ap) is used to send the frame(s). The contents of the frames can be described as a text file. send_frame can also be instructed to start a continuous transmit mode in which the same packet is send multiple times until send_frame program is killed. This can be used to implement continuous transmit test modes with full IEEE 802.11 frames
|
Note
|
When sending broadcast packets in AP mode, 80211.o will drop these frames if there are no associated stations. This may not be approriate for test cases that are using broadcast packets for a continuous transmit mode to skip wait times for ACK packets (only unicast IEEE 802.11 packets are acknowledged). This multicast packet filtering can be disabled with following command:
iwpriv wlan0 param 1034 1
|
Example send_frame Commands
send_frame wlan0ap ps_poll.data
iwpriv wlan0 param 1034 1
send_frame wlan0ap broadcast.data cont
send_frame Control File Format
The send_frame data files describe the contents of the packets. The data file includes full packet payload as hex numbers. Lines beginning with # are ignored and can thus be used to comment the contents of the file. Similarly, empty lines ignored. Data octets can be be separated with colons or spaces, but they can also be used without separation. In other words "00:01:02:03:04:05", "00 01 02 03 04 05" and "000102030405" will produce identical end result.
Example Data Files
# PS-Poll frame
# Frame Control (ctrl::PS-Poll type=1 Subtype=10)
a4 00
# AID (aid=10; 2 MSBs set to 1) (note: little endian byte order)
0a c0
# BSSID (AP addr)
00:10:20:30:40:50
# TA (STA addr)
00:11:22:33:44:55
# Broadcast management frame (e.g., for continuous TX mode testing)
# Frame control (mgmt, subtype=15 = reserved)
f0 00
# duration
00 00
# DA
ff:ff:ff:ff:ff:ff
# BSSID
ff:ff:ff:ff:ff:ff
# SA
00:00:00:00:00:00
# seq
00 00
# data payload
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
# add more lines for a longer packet,
Other Test Modes
The 80211.o module (ieee80211 package) provides a private ioctl that can be used to initialize special test modes in the wireless LAN hardware. This is a generic interface and it requires support from the low-level drivers to be useful.
The Linux wireless-tools package iwpriv program can be used to control test modes. "Sub-ioctl" 'param 1007' is reserved for this.
|
Note
|
Test mode must be disabled and enabled before modified parameters take effect.
Test mode needs to configuration that is different from normal operational mode. The low-level driver does not fully support moving from test mode back to normal mode. Before using the driver in normal operational mode, reboot the device or at least load and reload the low-level driver
Since generic driver code is used instead of a special test driver, some error messages may be printed when using tests modes (for example, "Assertation failed!" messages for TX queue releasing, which can be ignored).
|
Test Parameters for iwpriv Command
The following commands are currently defined.
|
Command
|
Description
|
|
iwpriv wlan0 param 1007 0
|
Disable test modes.
|
|
iwpriv wlan0 param 1007 1
|
Unmask all channels so that they can be used even without hostapd, first unmasking them based on regulatory domain configuration.
|
|
iwpriv wlan0 param 1007 2
|
Enable continuous transmit test mode.
|
|
iwpriv wlan0 param 1010 1
|
Enable radio (it is disabled if hostapd is not started)
|
Test parameters can be set with another iwpriv command 'test_param'. The following parameters are currently defined.
|
Command
|
Description
|
|
iwpriv wlan0 test_param 0 <Value>
|
Transmit (TX) power (in raw hardware model specific units; that is, this value will be used directly without any conversion)
|
|
iwpriv wlan0 test_param 1 <Value>
|
Transmit (TX) rate (in raw hardware model specific units; that is, this value will be used directly without any conversion)
|
|
iwpriv wlan0 test_param 2 <Value>
|
Transmit (TX) pattern (pattern of data used in continuous TX test mode; 32 bits)
|
|
iwpriv wlan0 test_param 3 <Value>
|
Transmit (TX) power (in 0.1 dBm; that is, 100 = 10 dBm)
Caution: This test configuration does not limit the power based on calibrated hardware limits. Use care when selecting which levels are used to avoid damage to test results and equipment. The signal quality will degrade when using too high power levels, especially on higher rates (48 Mbps / 54 Mbps).
|
|
iwpriv wlan0 test_param 4 <Value>
|
Transmit (TX) rate (in 100 kbps; that is., 540 = 54 Mbps)
|
|
iwpriv wlan0 test_param 5 <Value>
|
Antenna select:
- 0 = use default antenna
- 1 = use antenna 1
- 2 = use antenna 2
|
Example Commands for Testing
# load modules
insmod 80211.o
insmod oahu.o
# enable interface
ifconfig wlan0 up
# enable radio
iwpriv wlan0 param 1010 1
# unmask all channels
iwpriv wlan0 param 1007 1
# setup continuous TX mode on IEEE 802.11b/g channel 6 (2.437 GHz)
iwconfig wlan0 freq 2437M
# TX power: 15 dBm
iwpriv wlan0 test_param 3 150
# TX rate: 6 Mbps
iwpriv wlan0 test_param 4 60
# Enable continuous TX
iwpriv wlan0 param 1007 2
# change rate to 54 Mbps, and TX power to 5 dBm
iwpriv wlan0 param 1007 0
iwpriv wlan0 test_param 4 540
iwpriv wlan0 test_param 3 50
iwpriv wlan0 param 1007 2
Commands to Disable Testing
iwpriv wlan0 param 1007 0
# disable card and remove modules
ifconfig wlan0 down
rmmod oahu
rmmod 80211
Building the Package
Follow standard instructions for building kernel modules in the Devicescape Developer Guide topic on "Building the Packages", see subtopic: "Building a Kernel Module from a Source RPM".
This package requires building a userspace and kernel module from one source RPM, so it must have .tshint file also, like all kernel modules.
Licensing
Devicescape Software, Inc.
Related Packages
Suggested
hostapd package
wpa_supplicant package
ieee80211-tools package
Required
None
