A Handshake Capture Appliance
- Why a dedicated box
- The one idea worth taking away
- The hardware, and a question you should ask first
- The files
- Worked example: capturing a handshake
- Why M1 + M2 is already enough
- PMKID: the active option
- What it will not do
- Reading the screen
- References
Why a dedicated box
Watching the 2.4 GHz Band captures handshakes the conventional
way: a laptop, a USB adapter in monitor mode, airodump-ng. That works, and
you should be able to do it. It also has two problems that only show up when
you try to do it in front of people.
The first is the adapter lottery. “Monitor mode” is not one capability. An
adapter can enter monitor mode, report no errors, show dropped 0, and still
hand you nothing but beacons, because its firmware’s sniffer mode never
delivers the data frames that carry EAPOL. The monitor card also has to speak
the same PHY as the client you are watching — an 802.11n-only card watching an
802.11ac client sees the management frames and misses the handshake.
The second is that 5 GHz is where the interesting traffic went, and plenty of cheap adapters are 2.4 GHz only.
So this page is about a different instrument: a purpose-built board that does
one job, shows you it is doing it, and cannot be misconfigured into looking
like it works. It is a demonstration device, not a replacement for knowing how
to do this with airodump-ng.
The one idea worth taking away
Channel hopping and handshake capture are mutually exclusive.
A survey sweep covers 28 channels. Dwelling 120 ms on each, a full sweep takes about 3.4 seconds, so the radio is on any one channel roughly 3.5% of the time. A four-way handshake completes in a few milliseconds. Multiply those together and you get the probability of catching a handshake while sweeping, which is approximately the probability of being struck by a good idea during a committee meeting.
Sweeping is how you find the target. Parking is how you capture it. A sniffer that is still hopping when the handshake happens was never going to see it, and nothing about the output tells you that — the capture is simply empty, which looks exactly like a quiet network.
hop 28 channels
120 ms each"] survey --> q{"target
identified?"} q -- "no" --> survey q -- "yes" --> park["PARK
stop on its channel
radio does not move"] park --> rec["record
mgmt + EAPOL to SD"] rec --> wait{"EAPOL
seen?"} wait -- "no" --> rec wait -- "M1+M2 or M2+M3" --> done([handshake is crackable]) style survey fill:#1f3a2a,stroke:#3fd97f,color:#e8e8e8 style park fill:#3a2a14,stroke:#f5a623,color:#e8e8e8 style done fill:#1a3a4a,stroke:#3fa9f5,color:#e8e8e8
The hardware, and a question you should ask first
The board is a Waveshare ESP32-C5-LCD-1.47: a dual-band Wi-Fi 6 part with a 1.47-inch screen and a microSD slot, for about fifteen dollars.
The question you should ask is why write firmware at all — ESP32 Marauder already exists, is maintained, and supports the ESP32-C5 as a first-class target across eleven boards. That is the right instinct, and for most purposes the answer is to use Marauder.
It will not run on this particular board, for two independent reasons:
- Every Marauder ESP32-C5 target requires the 8 MB
default_8MBflash layout. This board carries an ESP32-C5HF4 — 4 MB of flash, inside the package, not expandable.esptool flash_idreports it in one line. - The 1.47-inch board is not a listed target. The Waveshare board Marauder supports is the larger ESP32-C5-Touch-LCD-3.5, which is a different device. The project’s own documentation is blunt about this: “Never substitute a binary merely because two devices use the same ESP32 family.”
If you want Marauder, buy a C5-DevKitC-1 or a Seeed XIAO ESP32-C5. Both are listed targets with 8 MB and need no work at all. This firmware exists because the board with the screen is the one that makes a good demonstration, and because a tool you wrote is a tool whose failure modes you know.
The files
The firmware and the host tool:
wificap/README.md— the operator manualwificap/main/— the firmware (capture.cholds the EAPOL parsing,pcap.cthe radiotap writer,pmkid.cthe one path that transmits)wificap/host/wificap.py— the host-side driver
$ curl -LO https://web.cecs.pdx.edu/~dmcgrath/courses/F26/iotsec/wificap/host/wificap.py
$ chmod +x wificap.py
Building the firmware needs ESP-IDF v5.5 or newer — the ESP32-C5 is a preview target before that, and dual-band promiscuous receive is not something to run on preview support.
$ idf.py set-target esp32c5
$ idf.py build
$ idf.py -p /dev/ttyACM0 flash
Worked example: capturing a handshake
Everything here is passive. The board never transmits in this workflow.
Survey. Let it sweep long enough to cover the plan several times.
$ ./wificap.py survey --seconds 20
BSSID CH RSSI BCN SSID
94:83:c4:d1:e3:b3 1 -25 17 O-Net
48:8b:0a:b8:00:60 11 -72 13 PSU-IoT
48:8b:0a:b6:51:0f 36 -73 13 PSU-IoT
1e:f2:90:04:bb:14 161 -11 31 D-Net Mobile
48 access point(s).
Note the channel column is the channel where each AP was heard loudest, not where it was heard last. That distinction is not pedantry: 2.4 GHz channels overlap, so a close AP on channel 1 decodes perfectly while the radio is tuned to channel 6. Recording the most recent sighting sends you to the wrong channel, and an empty capture is the only symptom you get.
Park and record. This stops the sweep and starts writing.
$ ./wificap.py watch --target 94:83:c4:d1:e3:b3 --record hs
OK target set, parked ch=1
OK rec hs file=/sdcard/wcap000.pcap
watching; Ctrl-C to stop
ch f/s frames eapol pairs written bytes state
1 112 1800 0 0 220 59501 park
1 152 3404 2 1 1795 503695 park
1 118 4621 4 1 2402 680110 CRACKABLE
rec hs writes management frames and EAPOL only. That is why the SD
bandwidth question never arises: a handshake plus the beacons that name the
network is a few kilobytes, while recording every data frame on a busy channel
is megabytes a minute through a card that shares its SPI bus with the display.
Beacons are always kept, because the SSID is an input to the PMK and a capture
with a handshake but no beacon has no SSID in it.
Watch drop. It counts frames lost because the writer fell behind. A
capture that silently drops frames looks exactly like a quiet channel, which
is why the number is on the screen rather than buried in a log.
Pull the capture over the same USB cable, without ejecting anything:
$ ./wificap.py pull -o ./captures
pulling wcap000.pcap ...
853442 bytes -> ./captures/wcap000.pcap (crc32 da430282 ok)
The CRC is checked against one computed on the board. A serial transfer that silently drops a chunk produces a pcap that opens cleanly and is subtly wrong, which is worse than one that fails loudly.
Confirm it is a real capture, rather than trusting the device that made it:
$ capinfos captures/wcap000.pcap
File type: Wireshark/tcpdump/... - pcap
File encapsulation: IEEE 802.11 plus radiotap radio header
Number of packets: 2,959
Strict time order: True
$ tshark -r captures/wcap000.pcap -Y eapol
Why M1 + M2 is already enough
The firmware flags a station pair as crackable on M1+M2 or M2+M3, not on seeing all four messages, and that is deliberate.
An offline dictionary attack needs the two nonces and one MIC computed over a known EAPOL body. M1 carries the ANonce. M2 carries the SNonce and a MIC. That is the whole input. M3 and M4 are confirmation, and M4 in particular is frequently lost to a retransmission.
Waiting for all four is a mistake people make because the handshake has four
messages. aircrack-ng will work from two.
Telling M2 from M4 is the only genuinely fiddly part of the parsing: both come
from the supplicant with a MIC and no ACK. M2 carries the RSN IE in its key
data and is not yet Secure; M4 is Secure with empty key data. Checking only
one of those two conditions misclassifies some implementations, so the
firmware checks both — and ships a selftest command that runs synthetic
M1–M4 frames through the same classifier so the logic is verifiable without
waiting for a real handshake.
PMKID: the active option
Everything above only receives. This does not.
As Steube showed in 2018, the PMKID is derived from the PMK, the two MAC addresses and a fixed string — so it is a function of the passphrase and nothing else. An access point that supports PMK caching volunteers it in message 1, the AP’s own first message, sent on association, before the supplicant has proved anything.
The consequences are worth stating plainly:
- You do not need a client to be present.
- You do not need to wait for anyone to reconnect.
- You do not need the rest of the handshake.
- One frame from the AP is enough.
The catch is “on association”. Asking means transmitting — an authentication
request and an association request from your radio to that AP. That is a
different legal position from passive capture, and the firmware treats it that
way: a separate source file, a separate command, a red ACTIVE —
TRANSMITTING banner on the screen while it runs, receive-only restored on
every error path, and an explicit --yes on the host side.
$ ./wificap.py pmkid --target 94:83:c4:d1:e3:b3 --yes -o found.22000
OK transmitting: associating to O-Net on ch 1 for up to 8s
WPA*01*<pmkid>*<ap mac>*<sta mac>*<essid hex>***
crack with: hashcat -m 22000 found.22000 wordlist
The output is hashcat’s 22000 format, so the result of the demonstration is a line you can paste into a cracking run rather than something needing conversion first.
Point it at an access point you administer. The firmware’s refusal to deauthenticate limits what it can do; it does not decide what you point it at.
When it does not work
A probe that returns no PMKID is usually a fact about the target rather than a failure of the tool, and the distinction matters:
- The AP does not do PMK caching, so there is no PMKID in M1 to take. Many modern access points simply do not offer one.
- The network is WPA3-SAE, which does not use a PMKID this way at all.
- The AP never answered.
The firmware reports the key-data length of the M1 it saw, so “this AP offers no PMKID” can be distinguished from “it sent key data the parser did not recognise”. The first is a result. The second would be a bug.
What it will not do
There is no deauthentication command, and that is a design decision, not an oversight. Deauthenticating a network to force a handshake is the fastest way to get one, and in a classroom it means touching networks belonging to everyone in the building. A demonstration that requires that is a demonstration you cannot run.
The honest cost: you capture a handshake when a device happens to join, not when you want one. For a scheduled demonstration, bring your own access point and toggle Wi-Fi on a phone.
Reading the screen
The screen exists so the board can be believed without a host attached.
| what | means |
|---|---|
| the large number | the channel the radio is on right now |
f/s bar |
how busy this channel is |
| heat strip | one cell per planned channel; white is current, dark red is a channel the radio refused |
eapol |
EAPOL frames seen — it moves before a handshake completes |
drop |
frames lost because the writer fell behind |
| bottom line | the handshake line, which latches |
A refused channel and a quiet channel are indistinguishable in a capture, which is why they are different colours here. A frozen screen showing a plausible channel is this board’s worst failure mode, so the UI task logs loudly if it cannot repaint.
References
- ESP32 Marauder: supported hardware and releases — the ESP32-C5 target list and the 8 MB flash-layout requirement
- Espressif, Wi-Fi sniffer mode — promiscuous receive, the filter masks, and what the callback is handed
esp_wifi_set_promiscuous_rx_cbAPI reference- radiotap — the capture metadata header, and the FLAGS field whose “frame includes FCS” bit decides whether your capture parses at all
- Steube, “New attack on WPA/WPA2 using PMKID” — the original disclosure
- hashcat mode 22000 / WPA-PBKDF2-PMKID+EAPOL
— the hash format the
pmkidcommand emits - Aircrack-ng: airodump-ng — the conventional way to do the same capture
- IEEE 802.11-2020, clause 12.7 — the four-way handshake and the EAPOL-Key frame layout
- Wireshark: How to Decrypt 802.11 — what a capture must contain before a key is any use
Related course pages: Watching the 2.4 GHz Band · Wi-Fi Security