esp-idf-injection-ng

在 ESP-IDF v5.x / v6.x 上实现原始 802.11 帧注入。 一条命令即可完成的可逆补丁，重新启用完整的 802.11 帧类型集合（Authentication、Deauth、Assoc、Reassoc、Disassoc、RTS/CTS/ACK 等），使其可通过 esp_wifi_80211_tx() 发送；而乐鑫随附的 libnet80211.a 原本仅允许一个很短的帧类型白名单（Beacon、Probe Req/Resp、Action、非 QoS Data）。

包含内容：

• 补丁本身（patch/patch_libnet80211.sh）——对单个符号执行 objcopy --weaken-symbol，并支持备份与 --revert。
• 一个最小演示固件（example/），注入五种帧变体并通过串口报告结果。
• Pcap、Hostapd 日志和串口日志证据，证明该补丁可在 ESP32 上启用 SAE Commit（Authentication 子类型 11）注入——这是本工作的核心动机用例。
• 完整工程说明以研究论文形式提供（docs/esp32_raw_tx_report.pdf）。

为什么需要它？

早期的社区项目（wsl_bypasser、esp32-wifi-penetration-tool、Atomic-SAQuery 等）依赖对 blob 函数 ieee80211_raw_frame_sanity_check 进行强 C 符号覆盖。该技术在 ESP-IDF v5 前后悄然失效：blob 符号的绑定从 WEAK 变为 STRONG，因此该覆盖现在会在链接阶段因多重定义错误而失败。

显而易见的替代方案（-Wl,--wrap=ieee80211_raw_frame_sanity_check）同样会悄然失效：GNU ld --wrap 只重写未定义的对象间引用，但真正关键的调用——esp_wifi_80211_tx → sanity_check——是 ieee80211_output.o 内部的对象内调用，对 --wrap 不可见。

本仓库记录了这一破坏性变更，并提供了一个可用的替代方案：用 objcopy --weaken-symbol 将 blob 符号重新翻转为 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 调度器仍会施加各自的限制。实际效果是：管理帧可以可靠注入；控制帧（RTS/CTS/ACK）能够发出，但可能因用户态延迟过大而无法满足 IEEE 802.11 的时序要求（SIFS 截止时间）。对于内容模糊测试，时序无关紧要；对于符合协议规范的交互，则至关重要。
• 这会全局修改 ESP-IDF 安装。 你基于该 IDF 构建的每个项目都会链接到打过补丁的归档文件。patch_libnet80211.sh --revert 可从备份恢复原厂文件。
• 仅绕过 TX。 这对 RX 没有任何影响——监听模式下的混杂抓包在 ESP-IDF 中开箱即用。
• 已在 ESP-IDF v6.1-dev 上针对 ESP32（经典款）测试。 如果符号绑定为 T，应可在 v5.x 及其他目标（ESP32-S2/S3/C 系列）上工作——请先用 nm 检查，参见上文“验证”步骤。

合规使用

本文所述技术可实现原始 802.11 帧发送，既有研究/防御用途（模糊测试、PMF 测试、侧信道测量——即本项目的动机用例），也有对抗性用途（针对非自有网络的 deauth 风暴）。仅可对你拥有或已获得明确书面授权测试的 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 — 学术性 CVE PoC， 仅限于仅信标注入。
• Vanhoef & Ronen，Dragonblood: Analyzing the Dragonfly Handshake of WPA3 and EAP-pwd，IEEE S&P 2020 — 激发本项目研究的 SAE PWE 侧信道。

引用

如果您在学术工作中使用此补丁或本文，请引用：

Mehdi Mansour. "Enabling Raw 802.11 Management Frame Injection on
ESP-IDF v6: A Linker-Level Analysis of ieee80211_raw_frame_sanity_check
and a Reproducible Bypass." Technical report, École Nationale
Supérieure de Mathématiques (NHSM), Algiers, October 2026.

作者

Mehdi Mansour — 阿尔及尔 NHSM 密码学、编码与安全系。 联系方式：[email protected] · LinkedIn

许可证

MIT。参见 LICENSE。