Move instructions from script to README.md

README.md

@@ -2,7 +2,6 @@ This project contains scripts to test if clients or access points (APs) are affe
 
 Remember that our scripts are not attack scripts! You require network credentials in order to test if an access point or client is affected by the attack.
 
-
 # Prerequisites
 
 Our scripts were tested on Kali Linux. To install the required dependencies on Kali, execute:
@@ -10,27 +9,81 @@ Our scripts were tested on Kali Linux. To install the required dependencies on K
 	apt-get update
 	apt-get install libnl-3-dev libnl-genl-3-dev pkg-config libssl-dev net-tools git sysfsutils python-scapy python-pycryptodome
 
-Then **disable hardware encryption** using the script `./krackattack/disable-hwcrypto.sh`. We tested our scripts on a Kali Linux distribution using a TP-Link WN722N v1.
+Then **disable hardware encryption** using the script `./krackattack/disable-hwcrypto.sh`. It's recommended to reboot after executing this script. After plugging in your Wi-Fi NIC, use `systool -vm ath9k_htc` or similar to confirm the nohwcript/.. param has been set. We tested our scripts with an Intel Dual Band Wireless-AC 7260 and a TP-Link TL-WN722N v1 on Kali Linux.
+
+Finally compile our modified hostapd instance:
 
-Remember to disable Wi-Fi in your network manager before using our scripts. After disabling Wi-Fi, execute `sudo rfkill unblock wifi` so our scripts can still use Wi-Fi.
+      cd ../hostapd
+      cp defconfig .config
+      make -j 2
 
+Remember to disable Wi-Fi in your network manager before using our scripts. After disabling Wi-Fi, execute `sudo rfkill unblock wifi` so our scripts can still use Wi-Fi though.
 
 # Testing Clients: detecting a vulnerable 4-way and group key handshake
 
-To simulate an attack against a client follow the detailed instructions in `krackattack/krack-test-client.py`:
+To test wheter a client is vulnerable to Key Reinstallation Attack against the 4-way handshake or group key handshake, take the following steps:
 
-	cd krackattack/
-	./krack-test-client.py --help
+1. Execute `krackattack/krack-test-client.py`. Accepted parameters are:
 
-**Now follow the detail instructions that the script outputs.**
-The script assumes the client will use DHCP to get an IP.
-Remember to also perform extra tests using the `--tptk` and `--tptk-rand` parameters, and using `--group` to test the group key handshake.
-So concretely, we recommend running the following tests:
-
-1. `./krack-test-client.py`
-2. `./krack-test-client.py --tptk`
-3. `./krack-test-client.py --tptk-rand`
-4. `./krack-test-client.py --group`
+		--group      Test the group key handshake instead of the 4-way handshake
+		--debug      Show more debug messages
+		--tptk       See step 3 (forge Msg1/4 with replayed ANonce before Msg3/4)
+		--tptk-rand  See step 3 (forge Msg1/4 with random ANonce before Msg3/4)
+
+	All other supplied arguments are passed on to hostapd. The main commands you will execute are:
+
+		krack-test-client.py
+		krack-test-client.py --tptk
+		krack-test-client.py --tptk-rand
+		krack-test-client.py --group
+		
+	These commands are further explained below. In all tests, once the script is running, the device being tested must connect to the **SSID testnetwork with password abcdefgh**. You can change settings of the AP by modifying `hostapd.conf`. In particular you will have to **edit the line `interface=` to specify the correct Wi-Fi interface to use for the AP**. The script assumes the client will use DHCP to get an IP after connecting to the Wi-Fi network.
+
+2. To test key reinstallations in the 4-way handshake, the script will keep sending encrypted message 3's to the client. To start the script execute:
+
+	      krack-test-client.py
+
+	Connect to the AP and the following tests will be performed automatically:
+
+	1. The script monitors traffic sent by the client to see if the pairwise key is being reinstalled. To assure the client is sending enough frames, you can optionally ping the AP: ping 192.168.100.254 . If the client is vulnerable, the script will show something like:
+
+			[19:02:37] 78:31:c1:c4:88:92: IV reuse detected (IV=1, seq=10). Client is vulnerable to pairwise key reinstallations in the 4-way handshake!
+
+		If the client is patched, the script will show (this can take a minute):
+	
+			[18:58:11] 90:18:7c:6e:6b:20: client DOESN'T seem vulnerable to pairwise key reinstallation in the 4-way handshake.
+
+	2. Once the client has requested an IP using DHCP, the script tests for reinstallations of the group key by sending broadcast ARP requests to the client using an already used (replayed) packet number (= IV). The client *must* request an IP using DHCP for this test to start. If the client is vulnerable, the script will show something like:
+
+			[19:03:08] 78:31:c1:c4:88:92: Received 5 unique replies to replayed broadcast ARP requests. Client is vulnerable to group
+			[19:03:08]                    key reinstallations in the 4-way handshake (or client accepts replayed broadcast frames)!
+
+		If the client is patched, the script will show (this can take a minute):
+	
+			[19:03:08] 78:31:c1:c4:88:92: client DOESN'T seem vulnerable to group key reinstallation in the 4-way handshake handshake.
+
+     Note that this scripts *indirectly* tests for reinstallations of the group key, by testing if replayed broadcast frames are accepted by the client. This may mean that the device will be reported as vulnerable if it accepts replayed broadcast frames, even though it's not reinstalling the group key
+
+3. Some supplicants (e.g. wpa_supplicant v2.6) are only vulnerable to pairwise key reinstallations in the 4-way handshake when a forged message 1 is injected before sending a retransmitted message 3. To test for this variant of the attack, you can execute:
+
+		krack-test-client.py --tptk         # Inject message 1 with a replayed ANonce
+		krack-test-client.py --tptk-rand    # Inject message 1 with a random ANonce
+
+	Now follow the same steps as in step 4 to see if a supplicant is vulnerable. Try both these attack variants after running the normal tests of step 4.
+
+4. To test key reinstallations in the group key handshake, the script will keep performing new group key handshakes using an identical (static) group key. The client *must* request an IP using DHCP for this test to start. To start the script execute:
+
+		krack-test-client.py --group
+
+	Connect the the AP and all tests will be performed automatically. The working and output of the script is now similar as in step 2b.
+
+5. Some final recommendations:
+
+	* Perform these tests in a room with little interference. A high amount of packet loss will make this script unreliable!
+	* Manually inspect network traffic to confirm the output of the script:
+		- Use an extra Wi-Fi NIC in monitor mode to check pairwise key reinstalls by monitoring the IVs of frames sent by the client.
+		- Capture traffic on the client to see if the replayed broadcast ARP requests are accepted or not.
+	* If the client being tested can use multiple Wi-Fi radios/NICs, test using a few different ones.
 
 ## Correspondence to Wi-Fi Alliance tests