esp-idf-injection-ng

Raw-802.11-Frame-Injection auf ESP-IDF v5.x / v6.x. Ein Ein-Befehl-Patch, reversibel, der den vollständigen Satz an 802.11-Frame-Typen (Authentication, Deauth, Assoc, Reassoc, Disassoc, RTS/CTS/ACK, …) für die Übertragung über esp_wifi_80211_tx() wieder aktiviert, den Espressifs mitgelieferte libnet80211.a auf eine kurze Whitelist (Beacon, Probe Req/Resp, Action, non-QoS Data) beschränkt.

Enthält:

Den Patch selbst (patch/patch_libnet80211.sh) — objcopy --weaken-symbol auf ein Symbol, mit Backup und --revert.
Eine minimale Demo-Firmware (example/), die fünf Frame- Varianten injiziert und die Ergebnisse über die serielle Schnittstelle meldet.
Pcap-, Hostapd-Log- und Serial-Log-Nachweise, dass der Patch die SAE-Commit-Injection (Authentication-Subtyp 11) auf dem ESP32 ermöglicht — der motivierende Anwendungsfall für diese Arbeit.
Die vollständige technische Ausarbeitung als Research Paper (docs/esp32_raw_tx_report.pdf).

Warum gibt es das?

Frühere Community-Projekte (wsl_bypasser, esp32-wifi-penetration-tool, Atomic-SAQuery, …) setzten auf ein Strong-C-Symbol-Override der Blob- Funktion ieee80211_raw_frame_sanity_check. Diese Technik funktionierte ab ESP-IDF v5 stillschweigend nicht mehr: Die Bindung des Blob-Symbols änderte sich von WEAK zu STRONG, sodass das Override nun zur Link-Zeit mit einem Multiple-Definition-Fehler fehlschlägt.

Der naheliegende Ausweichweg (-Wl,--wrap=ieee80211_raw_frame_sanity_check) schlägt ebenfalls stillschweigend fehl: GNU ld --wrap schreibt nur undefinierte, objektübergreifende Referenzen um, aber der entscheidende Aufruf — esp_wifi_80211_tx → sanity_check — ist objektintern innerhalb von ieee80211_output.o und für --wrap unsichtbar.

Dieses Repo dokumentiert die Breaking Change und liefert eine funktionierende Alternative: das Blob-Symbol mit objcopy --weaken-symbol wieder auf WEAK zurücksetzen und dann das Override im App-Code bereitstellen. Die globale Strong-beats-Weak- Auflösung bindet jede Referenz neu, einschließlich der objektinternen.

Siehe docs/esp32_raw_tx_report.pdf für die vollständige technische Nachverfolgung einschließlich Disassembly der Frame-Typ-Whitelist, drei fehlgeschlagener Versuche und End-to-End-Verifikationsnachweisen.

Schnellstart

1. Das IDF-Archiv patchen

# Assumes IDF is at $IDF_PATH. Override with LIBNET80211=... if needed.
bash patch/patch_libnet80211.sh

# Verify (should print "W" after; "T" means not patched)
xtensa-esp32-elf-nm $IDF_PATH/components/esp_wifi/lib/esp32/libnet80211.a \
    | grep ieee80211_raw_frame_sanity_check
#   0000005c W ieee80211_raw_frame_sanity_check    ← correct

Der Patch ist idempotent; ein erneutes Ausführen hat keine Wirkung. Zum Zurücksetzen:

bash patch/patch_libnet80211.sh --revert

Eine Sicherung des Originalarchivs wird beim ersten Lauf als libnet80211.a.bak gespeichert.

2. Demo bauen und flashen

cd example
idf.py set-target esp32
idf.py build flash monitor

Die serielle Ausgabe sollte alle 4 s durch fünf Varianten wechseln, wobei jede esp_wifi_80211_tx() -> ESP_OK meldet:

I (xxxxx) INJ-DEMO: >>> Sending V0 Deauth (control)            esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V1 Open-Auth (baseline)        esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V2 SAE-Commit bare             esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V3 SAE-Commit full (malformed) esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V4 SAE-Commit valid (scalar=2,E=G)
                                                               esp_wifi_80211_tx() -> ESP_OK

Wenn Sie stattdessen bei jedem Zyklus E (xxxxx) wifi:unsupport frame type: 0b0 sehen, wurde der Patch nicht angewendet; führen Sie patch_libnet80211.sh und idf.py fullclean build flash erneut aus.

3. (Optional) Über die Luft erfassen

Richten Sie einen weiteren Wi-Fi-Adapter im Monitor-Modus auf denselben Kanal und führen Sie tcpdump / Wireshark aus. Siehe evidence/ für ein Beispiel-Capture.

Was aktiviert ist

Tabelle aus dem Forschungspapier (Tabelle 1):

Frame-Typ	Subtypen erlaubt im Auslieferungszustand	Subtypen abgelehnt im Auslieferungszustand, aktiviert durch diesen Patch
MGMT (0)	4 (ProbeReq), 5 (ProbeResp), 6 (TimingAd), 7, 8 (Beacon), 13 (Action)	0 Assoc, 1 AssocResp, 2 Reassoc, 3 ReassocResp, 9 ATIM, 10 Disassoc, 11 Auth, 12 Deauth
CTRL (1)	(keine)	alle (RTS, CTS, ACK, BlockAck, …)
DATA (2)	0–7 (Nicht-QoS)	8–15 (QoS-Varianten)

Einschränkungen

Nachgelagerte Beschränkungen gelten weiterhin. Der Patch entfernt nur das sanity_check-Gate. Die MAC-Hardware, die MLME-Zustandsmaschine und der TX-Scheduler wenden weiterhin ihre eigenen Einschränkungen an. In der Praxis bedeutet dies, dass Mgmt-Frames zuverlässig injiziert werden; Control-Frames (RTS/CTS/ACK) werden gesendet, kommen aber möglicherweise zu spät aus dem User-Space für korrektes IEEE-802.11-Timing (SIFS-Deadline). Für Content-Fuzzing spielt das Timing keine Rolle; für protokollkonforme Interaktionen schon.
Dies verändert die ESP-IDF-Installation global. Jedes Projekt, das Sie gegen diese IDF bauen, wird gegen das gepatchte Archiv gelinkt. patch_libnet80211.sh --revert stellt die Originaldatei aus der Sicherung wieder her.
Nur TX-Bypass. Dies hat keine Auswirkung auf RX — Promiscuous-Capture im Monitor-Modus funktioniert in ESP-IDF von Haus aus.
Getestet mit ESP-IDF v6.1-dev auf ESP32 (classic). Sollte auf v5.x und anderen Targets (ESP32-S2/S3/C-Serie) funktionieren, wenn die Symbolbindung T ist — prüfen Sie dies zuerst mit nm, siehe den Schritt „Verify" oben.

Ethische Nutzung

Die hier beschriebenen Techniken ermöglichen die Übertragung von rohen 802.11-Frames, was sowohl Forschungs-/Verteidigungszwecke (Fuzzing, PMF-Tests, Side-Channel-Messung — der motivierende Anwendungsfall) als auch gegnerische Zwecke (Deauth-Stürme gegen Netzwerke, die Ihnen nicht gehören) ermöglicht. Arbeiten Sie nur gegen Wi-Fi-Netzwerke und -Geräte, die Ihnen gehören oder für die Sie eine ausdrückliche schriftliche Genehmigung zum Testen haben. Unautorisierte Eingriffe in Infrastruktur Dritter sind in den meisten Rechtsordnungen illegal.

Der Autor verwendet diesen Patch in einer isolierten Laborumgebung an der NHSM, Algier, für eine Masterarbeit zur Side-Channel-Analyse von WPA3-SAE.

Repository-Struktur

.
├── README.md                            — this file
├── LICENSE                              — MIT
├── patch/
│   └── patch_libnet80211.sh             — the patch script
├── example/                             — minimal demo IDF project
│   ├── CMakeLists.txt
│   └── main/
│       ├── CMakeLists.txt
│       └── main.c
├── docs/
│   └── esp32_raw_tx_report.pdf          — full engineering writeup
└── evidence/
    ├── README.md                        — what each file proves
    ├── sae_injection_first_capture.pcap — monitor-mode OTA capture
    ├── tshark_injected_frames.txt       — decoded frame list
    ├── hostapd_v4_roundtrip.log         — Hostapd parse + response
    └── serial_log_post_bypass.txt       — ESP32 serial, no reject log

Zitation

Wenn Sie diesen Patch oder die Ausarbeitung in akademischen Arbeiten verwenden, zitieren Sie bitte:

Beliebteste

esp-idf-injection-ng

esp-idf-injection-ng

Warum gibt es das?

Schnellstart

1. Das IDF-Archiv patchen

2. Demo bauen und flashen

3. (Optional) Über die Luft erfassen

Was aktiviert ist

Einschränkungen

Ethische Nutzung

Repository-Struktur

Verwandte Arbeiten

Zitation