courses

A Handshake Capture Appliance

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.

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:

  1. Every Marauder ESP32-C5 target requires the 8 MB default_8MB flash layout. This board carries an ESP32-C5HF4 — 4 MB of flash, inside the package, not expandable. esptool flash_id reports it in one line.
  2. 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:

$ 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:

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 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

Related course pages: Watching the 2.4 GHz Band · Wi-Fi Security