fragattacks

1. Introduction

This repository contains the FragAttacks tool. It can test Wi-Fi clients and access points for fragmentation and aggregation attacks. These vulnerabilities affect all protected Wi-Fi networks. For more information about these vulnerabilities see fragattacks.com.

The following additional resources are available:

• The USENIX Security presentation gives a summary of the discovered vulnerabilities.
• An overview of all assigned CVEs is available.
• Slides that summarize the root cause and impact of each vulnerability.
• A 2-page summary of resulting attacks and preconditions.
• Handouts that give extra background and explain the vulnerabilities in more detail.
• A demonstration of three example attacks.
• The research paper published at USENIX Security.
• Example network captures illustrating some of the vulnerabilities.
• A live USB image with this tool and modified drivers pre-installed.
• A list of known advisories from companies

See the change log for a detailed overview of updates to the tool made since 11 August 2020. This change log also contains information on which version of hostap the FragAttacks tool is based on.

Note that the attacks are identical against WPA2 and WPA3 because their CCMP and GCMP encryption ciphers are identical. Older WPA networks by default use TKIP for encryption, and the applicability of the attacks against TKIP are discussed in the paper and on the website. To illustrate that Wi-Fi has been vulnerable since its creation, the paper and website also briefly discusses the applicability of the attacks against WEP.

2. Supported Network Cards

Only specific wireless network cards are supported. This is because some network cards may overwrite the sequence or fragment number of injected frames, or may reorder frames of different priority, and this interferes with the test tool (i.e. the tool might say a device is secure although it's not). I have confirmed that the following network cards work properly:

The last two columns signify:

1. Mixed mode: whether the network card can be used in the recommended mixed mode.

2. Injection mode: whether the network card can be used as a second interface to inject frames in injection mode.

Yes indicates the card works out-of-the-box in the given mode. Patched driver/firmware means that the card is compatible when used with patched drivers and/or firmware. No means this mode is not supported by the network card. I recommend using the test tool in mixed mode.

Note that USB devices can be used inside a virtual machine, and the modified drivers and/or firmware can be installed in this virtual machine. However, I found that the usage of virtual machines can make network cards less reliable, and I instead recommend the usage of a live USB image if you cannot install the modified drivers/firmware natively.

My experience with the above network cards can be found here. Summarized:

• The AWUS036ACM in mixed mode appears reliable with our latest drivers and is the one I recommend. A cheaper but almost identical device is one with a MT7612U chipset. See more info here.

• I previously recommended the Technoethical N150 HGA in mixed mode. This dongle is identical to the TP-Link TL-WN722N v1.x and requires the usage of patched drivers and firmware. This is one of the most well-tested dongles, but it's hard to get. That's why I now recommend the AWUS036ACM instead.

• The Intel 3160 and 8265 are supported and extensively tested. Sometimes their firmware crashed but a reboot makes the network card usable again. The Intel AX200 is not compatible with the test tool.

• The WN111v2 seems to work well, although I did not test it extensively.

• The driver for the AWUS036ACH is not part of the Linux kernel and requires the installation of a separate driver. On Kali you can install this driver through the package manager. This card was not extensivly tested.

If you are unable to find one of the above network cards, you can search for alternative network cards that have a high chance of also working. When using a network card that is not explicitly supported I strongly recommend to first run the injection tests before using it, and using the tool against a known-vulnerable implementation to confirm the tool works properly.

3. Prerequisites

The test tool was tested on Ubuntu 20.04 using kernel 5.8. If you use another Linux distribution, please note that only kernel versions below or equal to 5.12 are supported.

Ubuntu 20.04 specific

When using Ubuntu 20.04 you will first have to install kernel 5.8 as follows. Note that your existing kernel will keep being installed and will also keep being used by default:

sudo apt install linux-image-5.8.0-63-generic linux-headers-5.8.0-63-generic linux-hwe-5.8-headers-5.8.0-63 \
	linux-modules-5.8.0-63-generic linux-modules-extra-5.8.0-63-generic

Now reboot Ubuntu, hold the shift key while booting, select "Advanced options for Ubuntu", and then start kernel 5.8 by picking "Ubuntu, with Linux 5.8.0-63-generic". You can edit your GRUB config so Ubuntu will use this kernel version by default. Continue the next instructions under this now-running kernel.

General Instructions

Install the required dependencies:

sudo apt-get update
sudo apt-get install libnl-3-dev libnl-genl-3-dev libnl-route-3-dev libssl-dev \
	libdbus-1-dev git pkg-config build-essential macchanger net-tools python3-venv \
	aircrack-ng rfkill firmware-ath9k-htc
# Note: on Kali linux use the package firmware-atheros instead of firmware-ath9k-htc

Now clone this repository, build the tools, and configure a virtual python3 environment:

git clone https://github.com/vanhoefm/fragattacks.git fragattacks
cd fragattacks/research
./build.sh
./pysetup.sh

The above instructions only have to be executed once. After pulling in new code using git you do have to execute ./build.sh and ./pysetup.sh again.

4. Patched Drivers

Install patched drivers using:

sudo apt-get install bison flex linux-headers-$(uname -r)
git clone https://github.com/vanhoefm/fragattacks-drivers58.git fragattacks-drivers58
cd fragattacks-drivers58
make defconfig-wifi
make -j 4
sudo make install

This compiles the drivers for most network cards supported by Linux. If you only want to compile the drivers for network cards I explicitly tested, use make defconfig-experiments instead. You may get the following warnings:

• When executing make defconfig-wifi you may get warnings related to -Wyacc and -Wformat-overflow. You can ignore these warnings as long as the drivers get successfully compiled.
• During the install command, you may also get the following warnings:
  • Several warnings containing .. needs unknown symbol ... You can ignore these warning as long they do not contain the directory /lib/modules/*/updates/ and the compiled drivers are working.
  • Repeated warnings containing SSL error and the sign-file command. This means that digitally signing the kernel modules has failed. You can usually ignore this.
• You can verify that the modified driver were located by executing cat /sys/module/mac80211/parameters/fragattack_version after a reboot. If this file exists, the modified drivers were successfully installed.

Now install patched ath9k_htc firmware:

cd research/ath9k-firmware/
./install.sh
# Now reboot

The ./install.sh script assumes the ath9k_htc firmware images are located in the directory /lib/firmware/ath9k_htc. If this is not the case on your system you have to manually copy htc_7010.fw and htc_9271.fw to the appropriate directory.

After installing the patched drivers and firmware you must unplug your Wi-Fi dongles and reboot your system. The above instructions have to be executed again if your Linux kernel gets updated or if the patched drivers get updated.

Note that even when your device works out of the box, I still recommend to install the modified drivers, as this assures there are no unexpected regressions in kernel and driver code.

In case you cannot install the modified drivers/firmware natively, you can download a live USB image that contains the modified drivers/firmware along with our test tool. Alternatively, you can use a virtual machine with USB network cards, although I found that using a virtual machine is less reliable in pratice.

5. Before every usage

Every time you want to use the test tool, you first have to load the virtual python environment as root. This can be done using:

cd research
sudo su
source venv/bin/activate

You should now disable Wi-Fi in your network manager so it will not interfere with the test tool. Also make sure no other network services are causing outgoing traffic. You can assure this by using iptables to block traffic by executing ./droptraffic.sh (you can revert this by rebooting). Optionally check using sudo airmon-ng check to see which other processes might be using the wireless network card and might interfere with our tool.

The test tool can test both clients and APs:

• Testing APs: configure the AP you want to test by editing research/client.conf. This is a standard wpa_supplicant configuration file, see the hostap documentation for an overview of all the options it supports.

• Testing clients: you must execute the test tool with the --ap parameter (see below). This instructs the tool into creating an AP with as name testnetwork and password abcdefgh. Connect to this network with the client you want to test. By default the client must request an IP using DHCP. To edit properties of the created AP, such as the channel it's created on, you can edit research/hostapd.conf.

6. Interface Modes

6.1. Mixed mode

This mode requires only one wireless network card, but generally requires a patched driver and/or firmware. See Patched Drivers on how to install patched drivers/firmware, and Supported Network Cards for compatible network cards. Execute the test tool i