wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant (PSK 4-way, EAP-TLS, PEAP/MSCHAPv2, SAE with H2E)

[dgarske]

wolfSupplicant: clean-room WPA2 / WPA2-Enterprise / WPA3 supplicant

Adds an in-tree Wi-Fi supplicant (src/supplicant/) built directly on wolfSSL/wolfCrypt: WPA2-Personal (PSK), WPA2-Enterprise (EAP-TLS, optional PEAP/MSCHAPv2), and WPA3-Personal (SAE). Transport-agnostic, caller-allocated context, no dynamic allocation on the bare-metal path. Each method is selectable at build time.

Rebased on the latest upstream master and organized as four logical commits.

Commits

1. wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant + interop harness - the state machine, 4-way handshake, SAE dragonfly (sae_crypto.c, incl. constant-time hunt-and-peck and RFC 9380 H2E), EAP-TLS engine (wolfSSL native + custom IO), optional PEAPv0/MSCHAPv2, AES-CMAC / AES-Key-Wrap, RSN IE handling, PMKSA caching, and the host unit + crypto-vector test suite. Incorporates the peer-review hardening (reflection-attack reject, P-521 hunt-and-peck parity, Dragon Blood / CVE-2019-9494 constant-time PWE, M1-retransmit DoS guard, EAP-TLS reassembly fix, PEAP RNG check, RFC 9190 TLS-1.3 exporter MSK, key-unwrap bound) and an internal clarity refactor (supplicant.c decomposed into per-mode init, per-type rx, and PEAP Phase-2 helpers) - all behavior-preserving.
2. SoftMAC nl80211 STA glue + wolfsta + hwsim/real-card interop - tools/hostapd/nl80211_sta.c drives a Linux mac80211 station (AUTHENTICATE+SAE_DATA / ASSOCIATE / NEW_KEY / control-port) and wires it to the supplicant ops; tools/wolfsta/ is a wolfIP+supplicant host app (join -> DHCP -> ping/UDP echo); the hwsim and run_realcard_* test runners and the testing docs.
3. STM32H563 wired 802.1X EAP-TLS demo - the supplicant authenticating on real hardware.
4. Raspberry Pi Pico 2 W (RP2350 + CYW43439) port - bare-metal scaffolding for the FullMAC PSK/SAE path.

What's validated

Against real hostapd over mac80211_hwsim (SoftMAC; the same code path a TP-Link USB card uses), all reaching AUTHENTICATED:

Path	Status
WPA3-SAE P-256/P-384/P-521, Hunt-and-Peck + H2E (all 6)	green
WPA2-Enterprise EAP-TLS over the radio	green
WPA3-SAE PMKSA fast reconnect (no dragonfly on rejoin)	green
WPA3-SAE wrong-password rejected (negative)	green
wolfsta join + DHCP + ping + UDP echo (SAE and PSK)	green

On real Wi-Fi hardware (TP-Link TL-WN722N v1 / Atheros AR9271 / ath9k_htc, against a Raspberry Pi 5 hostapd WPA3-SAE AP), the same binaries, unchanged: WPA3-SAE Commit/Confirm -> 4-way -> key install -> AUTHENTICATED, then a wolfIP DHCP lease + UDP echo + ICMP reply over the air. This required carrying EAPOL over the nl80211 control port (CONTROL_PORT_OVER_NL80211 / NL80211_CMD_CONTROL_PORT_FRAME) - real SoftMAC drivers drop EAPOL on the data path while the controlled port is unauthorized (hwsim is lenient). The recipe (generic AP setup + card identification) and the convenience runners are in tools/hostapd/README.md.

Plus: STM32H563 authenticates over wired 802.1X EAP-TLS on hardware; host unit tests cover the 4-way, SAE crypto (incl. RFC 9380 J.1.1 P-256 KAT), EAP-TLS, and MSCHAPv2 vectors.

Notable correctness work

• SAE 4-way uses Key Descriptor Version 0 (AES-128-CMAC) and the SHA-256 IEEE KDF for the PTK (vs Version 2 / HMAC-SHA1 for WPA2-PSK); RSN IE advertises AKM=SAE. AES-128-CMAC is implemented in-tree (RFC 4493 over AES-CBC), so no --enable-cmac dependency.
• P-521 hunt-and-peck: the IEEE 802.11 KDF emits its 521 valid bits left-aligned, so the pwd-value is right-shifted by 8 - 521%8 = 7 bits before the < p test (matching hostapd's buf_shift_right) - the prior high-byte mask agreed with an in-process peer but not hostapd.
• Constant-time hunt-and-peck PWE (Dragon Blood / CVE-2019-9494): blinded quadratic-residue test, fixed iteration count, constant-time select - no timing/cache oracle on the password.
• PMKSA fast reconnect on a SoftMAC userspace-SME radio uses open AUTHENTICATE + ASSOCIATE with the PMKID inline in the RSN IE (not the FullMAC SET_PMKSA path); hostapd matches the cached PMKSA and runs the 4-way directly.
• EAPOL over the nl80211 control port (CONTROL_PORT_OVER_NL80211): the glue carries the 4-way via NL80211_CMD_CONTROL_PORT_FRAME on a dedicated owner socket. Required on real SoftMAC hardware; transparent on hwsim.
• RFC 9190 TLS-1.3 exporter for the EAP-TLS MSK (vs the RFC 5216 PRF for TLS <= 1.2), selected by negotiated TLS version.

Memory footprint

The supplicant context is caller-allocated, and the build flags gate out the heavy crypto state - sizeof(struct wolfip_supplicant):

Build	Size
All features (EAP-TLS + SAE H&P + H2E)	18992 B
SAE only (no EAP-TLS)	14720 B
EAP-TLS only (no SAE)	5208 B
WPA2-PSK only	936 B

The SAE dragonfly context (ecc_point / mp_int bignums, ~13.8 KB) and the EAP-TLS engine (~4.3 KB) dominate; compile in only the methods a target ships and the footprint drops accordingly (down to ~0.9 KB for PSK-only).

Build flags

WOLFIP_ENABLE_EAP_TLS (1), WOLFIP_ENABLE_SAE (1, needs WOLFSSL_PUBLIC_MP), WOLFIP_ENABLE_SAE_H2E (1), WOLFIP_ENABLE_SAE_HNP (1), WOLFIP_ENABLE_PEAP_MSCHAPV2 (0, pulls in MD4/DES). Compile in only what you ship.

Testing

make supplicant-tests                              # host unit + crypto vectors
sudo make supplicant-hwsim-sae-softmac-test        # WPA3-SAE over a virtual radio
sudo make supplicant-hwsim-pmksa-test              # PMKSA fast reconnect
sudo make supplicant-hwsim-eap-softmac-test        # WPA2-Enterprise EAP-TLS

For a real SoftMAC USB card against any WPA3-SAE AP, the runners auto-detect the netdev and scan for the AP's BSSID/channel (only the SSID/passphrase is required):

sudo tools/hostapd/run_realcard_sae_test.sh                       # SAE association
sudo tools/hostapd/run_realcard_wolfsta_test.sh                   # join -> DHCP -> UDP echo
sudo SSID=my-ap PSK='my-pass' tools/hostapd/run_realcard_sae_test.sh

hwsim targets need root, mac80211_hwsim, hostapd, iw, and libnl-genl-3. tools/hostapd/README.md has the full matrix, a generic Pi-5/router AP setup, TP-Link card identification, and the wolfSSL build flags.

[Copilot]

Pull request overview

Adds a clean-room WPA/WPA2/WPA3 supplicant (“wolfSupplicant”) to wolfIP and introduces Linux hostapd-based interop harnesses (wired + mac80211_hwsim) to validate EAP-TLS/PEAP, WPA2-PSK 4-way, and WPA3-SAE flows against a real authenticator.

Changes:

• Introduces an optional Wi‑Fi control vtable (wolfIP_wifi_ops) and an EAPOL (0x888E) RX demux hook for supplicant integration.
• Adds the supplicant implementation (src/supplicant/*) including EAP-TLS, PEAP/MSCHAPv2, RSN parsing, WPA(2) 4-way, and SAE (incl. H2E) plus test binaries.
• Adds hostapd/mac80211_hwsim scripts + templates and an nl80211_connect helper, and wires new build/test targets into the Makefile.

Reviewed changes

Copilot reviewed 50 out of 50 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
wolfip.h	Adds Wi‑Fi ops vtable + public EAPOL handler registration API.
src/wolfip.c	Implements EAPOL handler registration and EAPOL ethertype demux in RX path.
src/test/unit/unit_tests_dns_dhcp.c	Adds unit coverage for EAPOL handler register/unregister behavior.
src/test/unit/unit.c	Registers the new unit test in the suite.
Makefile	Adds supplicant build outputs and hostapd/hwsim interop targets (+ nl80211 helper build).
src/supplicant/supplicant.c	Core supplicant state machine (PSK/EAP/SAE integration).
src/supplicant/supplicant.h	Supplicant public interface/types.
src/supplicant/eapol.c	802.1X/EAPOL framing helpers.
src/supplicant/eapol.h	EAPOL constants and APIs.
src/supplicant/eap.c	EAP packet parsing/building.
src/supplicant/eap.h	EAP structs/APIs and documentation for EAP parsing/building.
src/supplicant/eap_tls.c	EAP-TLS outer method implementation.
src/supplicant/eap_tls.h	EAP-TLS API/types.
src/supplicant/eap_tls_engine.c	TLS engine glue (wolfSSL IO/exporter integration) for EAP-TLS/PEAP.
src/supplicant/eap_tls_engine.h	TLS engine API/types.
src/supplicant/eap_peap.c	PEAP outer method implementation (when enabled).
src/supplicant/eap_peap.h	PEAP API/types.
src/supplicant/mschapv2.c	MSCHAPv2 inner method implementation (when enabled).
src/supplicant/mschapv2.h	MSCHAPv2 API/types.
src/supplicant/rsn_ie.c	RSN IE parse/build utilities (AKM/ciphers).
src/supplicant/rsn_ie.h	RSN IE API/types.
src/supplicant/wpa_crypto.c	WPA(2) key derivation/PRFs and related crypto helpers.
src/supplicant/wpa_crypto.h	WPA crypto API/types.
src/supplicant/sae_crypto.c	SAE (dragonfly) + H2E crypto/state helpers.
src/supplicant/sae_crypto.h	SAE crypto API/types.
src/supplicant/test_eap_certs.h	Test certificate material helpers for EAP-TLS/PEAP tests.
src/supplicant/test_eap_framing.c	Unit tests for EAP framing/parsing.
src/supplicant/test_eap_tls_engine.c	Unit tests for EAP-TLS engine behavior.
src/supplicant/test_mschapv2.c	Unit tests for MSCHAPv2 vectors.
src/supplicant/test_wpa_crypto.c	Unit tests for WPA crypto routines.
src/supplicant/test_supplicant_4way.c	In-process tests for 4-way handshake state machine.
src/supplicant/test_supplicant_eap_tls.c	In-process tests for EAP-TLS supplicant flow.
src/supplicant/test_sae_crypto.c	Unit tests/vectors for SAE crypto (incl. H2E).
src/supplicant/test_supplicant_sae.c	In-process tests for SAE handshake state machine.
src/supplicant/test_supplicant_hostapd.c	Wired hostapd interop test binary for EAP-TLS.
src/supplicant/test_supplicant_hostapd_psk.c	hostapd interop test binary for WPA2-PSK path.
src/supplicant/test_supplicant_hostapd_peap.c	hostapd interop test binary for PEAP/MSCHAPv2 path.
src/supplicant/test_supplicant_hostapd_sae.c	nl80211 external-auth hostapd interop test binary for SAE.
tools/hostapd/README.md	Documents hostapd-based interop harness setup/targets/flags.
tools/hostapd/run_hostapd_test.sh	Runner for wired hostapd interop (veth pair).
tools/hostapd/run_hwsim_psk_test.sh	Runner for mac80211_hwsim WPA2-PSK interop (nl80211 + hostapd).
tools/hostapd/run_hwsim_sae_test.sh	Runner for mac80211_hwsim SAE interop attempt (documents SoftMAC limitation).
tools/hostapd/hostapd.conf.template	hostapd wired-mode EAP server template for interop harness.
tools/hostapd/hostapd_psk.conf.template	hostapd PSK template for wired path (documented limitation).
tools/hostapd/hostapd_psk_hwsim.conf.template	hostapd nl80211 WPA2-PSK AP template for hwsim path.
tools/hostapd/hostapd_sae_hwsim.conf.template	hostapd nl80211 WPA3-SAE AP template for hwsim path.
tools/hostapd/eap_users	EAP users file for EAP-TLS interop.
tools/hostapd/eap_users_peap	EAP users file for PEAP/MSCHAPv2 interop.
tools/hostapd/nl80211_connect.c	Minimal libnl nl80211 client to associate STA with CONTROL_PORT for external EAPOL handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 90 out of 90 changed files in this pull request and generated 5 comments.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.