esp-idf-injection-ng

ESP-IDF v5.x / v6.x 上での生の 802.11 フレームインジェクション。 1 コマンドで実行でき、元に戻せるパッチです。esp_wifi_80211_tx() を介した送信のために、802.11 フレームタイプの完全なセット（Authentication、Deauth、Assoc、Reassoc、Disassoc、RTS/CTS/ACK など）を再び有効にします。Espressif が提供する libnet80211.a は、これを短いホワイトリスト（Beacon、Probe Req/Resp、Action、非 QoS Data）に制限しています。

含まれるもの:

• パッチ本体（patch/patch_libnet80211.sh）— 1 つのシンボルに対する objcopy --weaken-symbol。バックアップと --revert 付き。
• 5 つのフレームバリアントをインジェクトし、結果をシリアル経由で報告する最小デモファームウェア（example/）。
• このパッチが ESP32 上で SAE Commit（Authentication サブタイプ 11）のインジェクションを可能にすることを示す、Pcap、Hostapd ログ、シリアルログの証拠 — これが本研究の動機となったユースケースです。
• 完全なエンジニアリング解説を研究論文として収録（docs/esp32_raw_tx_report.pdf）。

なぜこれが存在するのか？

以前のコミュニティプロジェクト（wsl_bypasser、esp32-wifi-penetration-tool、Atomic-SAQuery など）は、ブロブ関数 ieee80211_raw_frame_sanity_check に対する強力な C シンボルによるオーバーライドに依存していました。この手法は 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 からは見えません。

このリポジトリはその破壊的変更を文書化し、動作する代替手段を提供します: objcopy --weaken-symbol でブロブシンボルを WEAK に戻し、アプリコードでオーバーライドを提供します。グローバルな strong-beats-weak 解決により、オブジェクト内の参照を含むすべての参照が再バインドされます。

フレームタイプホワイトリストの逆アセンブリ、3 回の失敗した試み、エンドツーエンドの検証証拠を含む完全なエンジニアリングトレースについては 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秒ごとに5つのバリアントを巡回し、それぞれが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/ を参照してください。

有効になるもの

研究論文の表 (Table 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 (クラシック) に対してテスト済み。シンボル バインディングが T であれば、v5.x や他のターゲット (ESP32-S2/S3/Cシリーズ) でも動作するはずです — まず nm で確認してください。上記の「Verify」ステップを参照してください。

倫理的な使用

ここで紹介する技術は生の 802.11 フレーム送信を可能にし、これには 研究/防御目的の用途 (ファジング、PMF テスト、サイドチャネル 測定 — これが動機となったユースケース) と、攻撃的な用途 (所有していないネットワークに対する deauth ストーム) の両方があります。所有している、またはテストするための明示的な書面による許可を得ている Wi-Fi ネットワークおよびデバイスに対してのみ操作してください。 第三者のインフラに対する無許可の操作は、 ほとんどの法域で違法です。

著者はこのパッチを、WPA3-SAE サイドチャネル 分析に関する修士論文のために、アルジェの NHSM にある隔離された実験環境内で使用しています。

リポジトリ構成

.
├── 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 であり、 beacon のみのインジェクションに限定されている。
• 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 を参照してください。