esp-idf-injection-ng

Инъекция необработанных кадров 802.11 на ESP-IDF v5.x / v6.x. Патч в одну команду, обратимый, который повторно включает полный набор типов кадров 802.11 (Authentication, Deauth, Assoc, Reassoc, Disassoc, RTS/CTS/ACK, …) для передачи через esp_wifi_80211_tx(), который поставляемый Espressif libnet80211.a ограничивает коротким белым списком (Beacon, Probe Req/Resp, Action, non-QoS Data).

Включает:

• Сам патч (patch/patch_libnet80211.sh) — objcopy --weaken-symbol для одного символа, с резервной копией и --revert.
• Минимальную демонстрационную прошивку (example/), которая инжектирует пять вариантов кадров и сообщает результаты через последовательный порт.
• Доказательства в виде Pcap, лога Hostapd и лога последовательного порта, что патч включает инъекцию SAE Commit (Authentication subtype 11) на ESP32 — мотивирующий сценарий использования для этой работы.
• Полное инженерное описание в виде исследовательской статьи (docs/esp32_raw_tx_report.pdf).

Зачем это существует?

Более ранние проекты сообщества (wsl_bypasser, esp32-wifi-penetration-tool, Atomic-SAQuery, …) полагались на переопределение strong-C-символа функции блоба ieee80211_raw_frame_sanity_check. Эта техника молча перестала работать примерно на ESP-IDF v5: привязка символа блоба изменилась с WEAK на STRONG, поэтому переопределение теперь завершается ошибкой на этапе компоновки с ошибкой множественного определения.

Очевидный запасной вариант (-Wl,--wrap=ieee80211_raw_frame_sanity_check) также молча не работает: GNU ld --wrap переписывает только неопределённые, межобъектные ссылки, но вызов, который имеет значение — esp_wifi_80211_tx → sanity_check — является внутриобъектным внутри ieee80211_output.o, невидимым для --wrap.

Этот репозиторий документирует ломающее изменение и поставляет работающую альтернативу: переключить символ блоба обратно на WEAK с помощью objcopy --weaken-symbol, затем предоставить переопределение в коде приложения. Глобальное разрешение strong-beats-weak перепривязывает каждую ссылку, включая внутриобъектную.

См. docs/esp32_raw_tx_report.pdf для полной инженерной трассировки, включая дизассемблирование белого списка типов кадров, три неудачные попытки и сквозные доказательства проверки.

Быстрый старт

1. Пропатчить архив 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

Патч идемпотентен; повторный запуск ничего не меняет. Чтобы откатить:

bash patch/patch_libnet80211.sh --revert

Резервная копия исходного архива сохраняется как libnet80211.a.bak при первом запуске.

2. Сборка и прошивка демо-версии

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

Вывод последовательного порта должен циклически переключаться между пятью вариантами каждые 4 с, каждый из которых сообщает 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

Если вместо этого вы видите E (xxxxx) wifi:unsupport frame type: 0b0 на каждом цикле, патч не применился; повторно запустите patch_libnet80211.sh и idf.py fullclean build flash.

3. (Необязательно) Захват по эфиру

Направьте другой Wi-Fi адаптер в режиме монитора на тот же канал и запустите tcpdump / Wireshark. Пример захвата см. в evidence/.

Что включено

Таблица из исследовательской работы (Таблица 1):

Тип кадра	Подтипы, разрешённые в стоке	Подтипы, отклоняемые в стоке, включаемые этим патчем
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)	(нет)	все (RTS, CTS, ACK, BlockAck, …)
DATA (2)	0–7 (не-QoS)	8–15 (QoS-варианты)

Ограничения

• Ограничения нижележащих уровней по-прежнему действуют. Патч лишь снимает проверку sanity_check. Аппаратное обеспечение MAC, конечный автомат MLME и планировщик TX по-прежнему применяют свои собственные ограничения. На практике это означает, что кадры управления (mgmt) инжектируются надёжно; кадры контроля (RTS/CTS/ACK) отправляются, но могут оказаться слишком запоздалыми для пользовательского пространства, чтобы соблюсти надлежащую синхронизацию IEEE 802.11 (дедлайн SIFS). Для фаззинга содержимого синхронизация не важна; для взаимодействий, соответствующих протоколу, — важна.
• Это глобально изменяет установку ESP-IDF. Каждый проект, который вы собираете с этим IDF, будет компоноваться с пропатченным архивом. patch_libnet80211.sh --revert восстанавливает исходный файл из резервной копии.
• Обход только для TX. Это ничего не делает для RX — неразборчивый захват в режиме монитора работает из коробки в ESP-IDF.
• Протестировано на ESP-IDF v6.1-dev для ESP32 (классический). Должно работать на v5.x и других целях (ESP32-S2/S3/C-серия), если привязка символа — T — сначала проверьте с помощью nm, см. шаг «Проверка» выше.

Этичное использование

Описанные здесь методы обеспечивают передачу необработанных кадров 802.11, что имеет как исследовательское/защитное применение (фаззинг, тестирование PMF, измерение побочных каналов — мотивирующий сценарий использования), так и враждебное применение (штормы деаутентификации против сетей, которыми вы не владеете). Работайте только с Wi-Fi сетями и устройствами, которыми вы владеете или на тестирование которых у вас есть явное письменное разрешение. Несанкционированное воздействие на стороннюю инфраструктуру незаконно в большинстве юрисдикций.

Автор использует этот патч в изолированной лабораторной среде в NHSM, Алжир, для магистерской диссертации по анализу побочных каналов WPA3-SAE.

Структура репозитория

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

Связанные работы

• risinek/wsl_bypasser — оригинальный подход с переопределением одноимённого поля. Работает на IDF ≤ v4.x; молча ломается на v5+, как описано здесь.
• risinek/esp32-wifi-penetration-tool — зависит от wsl_bypasser; то же ограничение.
• Matheus-Garbelini/esp32_esp8266_attacks — академические PoC для CVE, ограничены инъекцией только beacon-кадров.
• Vanhoef & Ronen, Dragonblood: Analyzing the Dragonfly Handshake of WPA3 and EAP-pwd, IEEE S&P 2020 — побочный канал SAE PWE, который мотивирует этот проект.

Цитирование

Если вы используете этот патч или описание в академической работе, пожалуйста, цитируйте: