add -a (assoc only) command line option
[rofl0r-wpakey.git] / README.md
blob0f5fa059f99ef528d636885cda46efc80ef0d708
1 # wpakey (1H)                 WIFI hacker's manual                  wpakey (1H)
3 ## NAME
5 wpakey - monitor mode WPA1/WPA2 online password bruteforcer
7 ## SYNOPSIS
9     cat password.lst | wpakey -i wlan0 -b bssid -t timeout -a -f
11 ## DESCRIPTION
13 reads password candidates from stdin and tries to connect to the specified AP.
14 the wifi apapter needs to be in **monitor mode** and on the right channel
15 already.
17 password candidates with length > 64 and < 8 will be ignored.
19 note that some access points (most notably *hostapd*) insist on getting ACK
20 responses on every single unicast packet. due to tight timeout constraints,
21 it is not possible to generate this ACK in due time in software, so the AP will
22 not send EAPOL packet M1 after the association response, or if it sends it, will
23 not accept our M2 packet without an ACK for M1, which makes it impossible to
24 distinguish whether the password is correct, or the router bitchy.
26 the only fix for this issue is the so-called "active monitor" mode.
27 currently, this feature can only be activated on *ath9k* and *mt7601u* drivers
28 using `iw dev wlan1 set monitor active`. `iw list` or `iw phyX show` can
29 tell you whether the feature is implemented, it will print
30 `Device supports active monitor (which will ACK incoming frames)` if supported.
31 note that even though this feature cannot be actively activated on *ath9k_htc*
32 devices, some or all of them have this behaviour turned on by default, so
33 it may well be that other devices behave the same.
35 therefore, it is highly recommend to use an adapter with one of the mentioned
36 chipsets for a reliable result.
38 on the bright side, if we can get the targetted AP to send M1 (regardless of
39 whether the password we send during M2 is correct), we can retrieve
40 its PMKID (if it sends one) and crack it with john the ripper instead.
42 ## RETURN VALUE
44 if the correct password is found, it will be displayed on stdin and the
45 program will exit with status 0.
46 if the correct password is not found, exits with status 1.
48 ## ERRORS
50 No errors are defined.
51 The following sections are informative.
53 ## RATIONALE
55 it is possible to test password candidates online using a patched version
56 of wpa_supplicant (see KEEP/wpa_supplicant-cracker.patch and
57 KEEP/wpacracker in sabotage-linux repo), however it is very slow, and it
58 is annoying to switch from monitor mode to managed mode during pentesting.
60 ## FUTURE DIRECTIONS
62 currently only WPA1/2 in AES CCMP mode is supported. support for TKIP,
63 WEP and other ciphers may be added in the future.
65 ## COPYRIGHT
66 (C) 2018 rofl0r
68 the crypto code in `crypto/`, `wsupp_crypto.c` and the function `pmk_to_ptk()`
69 were taken from https://github.com/arsv/wsupp-libc which is licensed under the
70 GPLv3.
72 due to the viral nature of the GPL, this project is currently licensed under
73 the GPLv3.
75 ## THANKS
76 thanks to arsv for well commented, concise code.
77 thanks to dragorn, Mister_X, Zero_Chaos for giving valuable tips.