esp-idf-injection-ng

Iniezione di frame 802.11 grezzi su ESP-IDF v5.x / v6.x. Una patch reversibile, applicabile con un solo comando, che riabilita l'intero insieme di tipi di frame 802.11 (Authentication, Deauth, Assoc, Reassoc, Disassoc, RTS/CTS/ACK, …) per la trasmissione tramite esp_wifi_80211_tx(), che la libnet80211.a distribuita da Espressif limita a una breve whitelist (Beacon, Probe Req/Resp, Action, Data non-QoS).

Include:

• La patch stessa (patch/patch_libnet80211.sh) — objcopy --weaken-symbol su un singolo simbolo, con backup e --revert.
• Un firmware demo minimale (example/) che inietta cinque varianti di frame e riporta i risultati via seriale.
• Evidenze Pcap, log Hostapd e log seriale che dimostrano che la patch abilita l'iniezione di SAE Commit (sottotipo Authentication 11) su ESP32 — il caso d'uso che ha motivato questo lavoro.
• La documentazione tecnica completa sotto forma di research paper (docs/esp32_raw_tx_report.pdf).

Perché esiste?

Progetti precedenti della community (wsl_bypasser, esp32-wifi-penetration-tool, Atomic-SAQuery, …) si basavano su un override di un simbolo C strong della funzione del blob ieee80211_raw_frame_sanity_check. Tale tecnica ha smesso silenziosamente di funzionare intorno a ESP-IDF v5: il binding del simbolo del blob è cambiato da WEAK a STRONG, quindi l'override ora fallisce in fase di link con un errore di definizione multipla.

Anche il ripiego ovvio (-Wl,--wrap=ieee80211_raw_frame_sanity_check) fallisce silenziosamente: ld --wrap di GNU riscrive solo i riferimenti non definiti tra oggetti, ma la chiamata che conta — esp_wifi_80211_tx → sanity_check — è interna all'oggetto ieee80211_output.o, invisibile a --wrap.

Questo repository documenta il cambiamento incompatibile e fornisce un'alternativa funzionante: riportare il simbolo del blob a WEAK con objcopy --weaken-symbol, quindi fornire l'override nel codice dell'applicazione. La risoluzione globale strong-beats-weak riassocia ogni riferimento, incluso quello interno all'oggetto.

Vedi docs/esp32_raw_tx_report.pdf per la traccia tecnica completa, inclusi il disassemblaggio della whitelist dei tipi di frame, tre tentativi falliti e le evidenze di verifica end-to-end.

Avvio rapido

1. Applicare la patch all'archivio IDF

# 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

La patch è idempotente; eseguirla di nuovo non produce effetti. Per ripristinare:

bash patch/patch_libnet80211.sh --revert

Un backup dell'archivio originale viene salvato come libnet80211.a.bak alla prima esecuzione.

2. Compilare e flashare la demo

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

L'output seriale dovrebbe alternare cinque varianti ogni 4 s, ciascuna che riporta esp_wifi_80211_tx() -> ESP_OK:

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

Se invece si vede E (xxxxx) wifi:unsupport frame type: 0b0 a ogni ciclo, la patch non è stata applicata; rieseguire patch_libnet80211.sh e idf.py fullclean build flash.

3. (Opzionale) Cattura over the air

Puntare un altro adattatore Wi-Fi in modalità monitor sullo stesso canale ed eseguire tcpdump / Wireshark. Vedere evidence/ per un esempio di cattura.

Cosa è abilitato

Tabella dal paper di ricerca (Tabella 1):

Tipo di frame	Sottotipi Permessi stock	Sottotipi Rifiutati stock, Abilitati da questa 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)	(nessuno)	tutti (RTS, CTS, ACK, BlockAck, …)
DATA (2)	0–7 (non-QoS)	8–15 (varianti QoS)

Avvertenze

• I vincoli a valle si applicano comunque. La patch rimuove solo il gate sanity_check. L'hardware MAC, la macchina a stati MLME e lo scheduler TX applicano comunque le proprie restrizioni. In pratica ciò significa che i frame mgmt vengono iniettati in modo affidabile; i frame di controllo (RTS/CTS/ACK) vengono inviati ma potrebbero essere troppo in ritardo per lo user space per rispettare i tempi IEEE 802.11 corretti (scadenza SIFS). Per il fuzzing dei contenuti, i tempi non contano; per interazioni conformi al protocollo, sì.
• Questo modifica globalmente l'installazione di ESP-IDF. Ogni progetto compilato con quell'IDF verrà collegato all'archivio modificato. patch_libnet80211.sh --revert ripristina il file originale dal backup.
• Solo bypass TX. Questo non fa nulla per l'RX — la cattura promiscua in modalità monitor funziona già di base in ESP-IDF.
• Testato su ESP-IDF v6.1-dev su ESP32 (classic). Dovrebbe funzionare su v5.x e altri target (ESP32-S2/S3/serie C) se il binding del simbolo è T — verificare prima con nm, vedere il passo "Verify" sopra.

Uso etico

Le tecniche qui descritte abilitano la trasmissione di frame 802.11 grezzi, che ha sia usi di ricerca/difensivi (fuzzing, test PMF, misurazione di canali laterali — il caso d'uso motivante) sia usi ostili (tempeste di deauth contro reti che non possiedi). Operare solo contro reti Wi-Fi e dispositivi di cui si è proprietari o per cui si ha esplicita autorizzazione scritta a testare. L'operazione non autorizzata contro infrastrutture di terzi è illegale nella maggior parte delle giurisdizioni.

L'autore utilizza questa patch all'interno di un ambiente di laboratorio isolato presso NHSM, Algeri, per una tesi di Master sull'analisi di canali laterali di WPA3-SAE.

Struttura del repository

.
├── 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

Lavori correlati

• risinek/wsl_bypasser — l'approccio originale basato sull'override dello stesso nome. Funziona su IDF ≤ v4.x; si rompe silenziosamente su v5+ come documentato qui.
• risinek/esp32-wifi-penetration-tool — dipende da wsl_bypasser; stessa limitazione.
• Matheus-Garbelini/esp32_esp8266_attacks — PoC accademici di CVE, limitati all'iniezione di soli beacon.
• Vanhoef & Ronen, Dragonblood: Analyzing the Dragonfly Handshake of WPA3 and EAP-pwd, IEEE S&P 2020 — il side-channel SAE PWE che motiva questo progetto.

Citazione

Se utilizzi questa patch o il writeup in lavori accademici, cita: