aliarifsoydas/rt5392-driver

# rt5392-driver — macOS (Apple Silicon) 的用户态 Wi-Fi 驱动 一个从零开始编写的、用于 ASUS USB-N14 / **Ralink-MediaTek RT5392** 的**用户态 802.11 驱动** (USB `0b05:17e8`)，通过 `libusb` 完全运行在 **Apple Silicon macOS** 的用户空间中。 无需内核扩展，无需 DriverKit，无需更改 SIP，也无需额外硬件。 它可以扫描并连接到**开放网络和 WPA2-PSK 网络**——完全通过软件实现了 **4 次握手 和 AES-CCMP**——通过 DHCP 获取 IP，并通过 `utun` 接口将流量桥接到 macOS。 **你可以让一张 macOS 没有驱动的网卡获得真正的互联网连接。** ``` $ ./wifi connect aa:bb:cc:dd:ee:ff 11 MyHomeWiFi AP RSN grup=TKIP pairwise-CCMP=var ASSOC ok (grup cipher=TKIP, pairwise=CCMP) WPA2 4-way handshake basliyor... 4-way TAMAM -> pairwise TK saklandi, YAZILIMSAL CCMP aktif DHCP ok ip=192.168.1.123 -> ARP gw -> utun bridge BAGLANDI (IP + internet) $ ./wifi ping 8.8.8.8 # ICMP straight off the card ``` ## 可用功能 - **原生扫描** — 支持所有 2.4 GHz 频段，beacon/IE 解析（安全性、Wi-Fi 世代、 WPS、信道宽度、国家代码、QBSS 负载、供应商 IE、multi-BSSID），以及隐藏 SSID 去遮蔽。 - **连接** — 支持 OPEN 和 **WPA2-PSK**： - auth → 关联，带有**自动匹配 AP 真实组加密算法**的 RSN IE （可处理 CCMP+TKIP 混合网络）， - 从零实现的 **EAPOL 4 次握手**（PMK = PBKDF2-SHA1，PTK = PRF，MIC = HMAC-SHA1， GTK 解包 = AES key-unwrap — 通过 CommonCrypto 实现）， - 用于数据平面的**软件 AES-CCMP** 加密/解密（基于 AES-ECB 构建的 CCM）—— 芯片的硬件加密被完全绕过， - DHCP（单播）、ARP，以及带有作用域路由的 **`utun` 桥接**，从而确保只有该网卡 的流量会通过它发送（你的默认路由不受影响）。 - 每次连接的 **MAC 随机化**。 - **L2 侦察工具包**（仅限用于你自己/获得授权的网络 — 见下文）：airodump 风格的 监控器、深入的单 AP 分析、批量分析器、被动设备发现、ARP 扫描、 ARP 欺骗监控器、子网查找器，以及用于 Wireshark 的**原始 `.pcap` 抓包**。 ## ⚠️ 仅限授权使用 侦察工具（`monitor`、`pcap`、`recon`、`arp`、`arpwatch`、……）仅供你**拥有或获得明确授权进行测试**的网络使用，也可用于学习 802.11 的工作原理。它们是被动/标准的分析功能（即 Wireshark 和 `tcpdump` 提供的那种功能）。请勿将其指向你不控制的网络。出于设计考量，本项目中不包含任何攻击性/DoS 工具。 ## 快速开始 ``` brew install libusb # + Xcode command-line tools ./scripts/fetch-firmware.sh # downloads firmware/rt2870.bin (not redistributed here) make # builds wifid + the bring-up tools sudo bash wifid-up.sh -v # start the daemon (owns the card; -v = live log) ./wifi scan # list networks ./wifi connect # WPA2 ./wifi status ./wifi ping 8.8.8.8 ``` `wifid` 必须以 root 身份运行（用于原始 USB 操作 + 创建 `utun` 接口）。它是网卡的 唯一所有者；其他所有操作均通过 `wifi` CLI 与 `/tmp/wifid/` 中的文件进行通信。 ## `wifi` CLI | 命令 | 功能 | |---|---| | `scan` | 列出附近的 2.4 GHz 网络 | | `connect [ssid] [psk]` | 加入 OPEN 或 WPA2-PSK；即使 DHCP 失败也会保持在 L2 | | `disconnect` / `status` / `log` | 断开连接 / 状态 / 实时守护进程日志 | | `ping ` | 直接通过网卡进行 ICMP 测试（无需 utun） | | `staticip / [gw]` | 在没有 DHCP 时手动设置 IP | | `info [ch]` | 深入分析单个 AP 配置（完整 IE 解码） | | `infoall` | 对**每个**发现的 AP 进行一次性分析 | | `monitor [ch]` / `stations` | airodump 风格的 AP+客户端发现 | | `netinfo` / `findnet` / `arp [subnet]` | 在没有 IP 的情况下了解网络 / 查找子网 / ARP 扫描 | | `recon` / `sniff` / `arpwatch` | 被动设备发现 / 实时嗅探 / ARP 欺骗监控 | | `pcap [ch] [secs]` | 原始 802.11 → 带时间戳的 `.pcap` 文件供 Wireshark 使用 + 主动探测 | | `web [path]` | 通过网卡 curl 设备的 Web UI | ## 工作原理 ``` RT5392 (USB) ──libusb──► wifid (root daemon, single owner of the card) ├─ register/BBP/RFCSR I/O (usb_io.h) ├─ rt2800 MAC/PHY init (regs.h, LINUX_MAC_INIT[]) ├─ scan / beacon+IE parse ├─ WPA2: 4-way handshake (wpa.h, CommonCrypto) ├─ AES-CCMP encrypt/decrypt (ccmp.h, software CCM) └─ utun bridge (scoped route) ◄── IP traffic ──► macOS file IPC in /tmp/wifid/ ◄──► wifi (CLI) ``` - **寄存器访问**通过供应商控制传输实现（`bRequest` MULTI_READ 7 / MULTI_WRITE 6， 4 字节小端序）。接收使用批量端点 `0x81`；发送使用 `0x01–0x04`。 - **为什么使用软件 CCMP？** 实践证明，从用户空间使用 RT5392 的硬件加密卸载并不稳定（发送帧未被加密；接收时 IV 头仍被保留）。使用握手派生密钥在软件中执行 CCM 是完全确定性且可移植的。目前已实现单播 CCMP；DHCP 通过单播请求，因此不需要组/广播（通常是旧版 TKIP）密钥。 ## 开发历程（真实版） 在很长一段时间里，这个驱动“无法接收数据”，多智能体调查得出的结论是网卡的 **RF 模块已损坏**——属于硬件故障。**那是错的。** 通过 QEMU USB 透传在同一张网卡上运行 Linux 的 `rt2800usb` 证明射频硬件完好无损。真正的 bug 是：`mac_init()` 只写入了约 12 个寄存器；而真正的 `rt2800_init_registers` 写入了约 50 个。缺失的写入导致 RX PHY 变成了聋子。通过 `usbmon` 捕获 Linux 的初始化过程，并逐字重放那 48 个核心 MAC 写入（`LINUX_MAC_INIT[]`）后，它终于唤醒了。教训是：网卡本身一直都是好的。 随后，WPA2 经历了六次真正的 bug 修复：修复了混合模式网络下的 RSN 组加密算法不匹配问题（状态 41），基于准确的 EAPOL 长度（非填充）计算 M3 的 MIC，确保在解析 GTK KDE 之前，没有在 RSN IE 处停止 M3 密钥数据解析，最后通过软件 AES-CCMP 绕过了不稳定的硬件加密。这段侦探工作中产生的 `linux-vm-test/` 追踪记录已被保留。 ## 代码布局 | 文件 | 作用 | |---|---| | `wifid.c` | 守护进程：扫描、连接、侦察、utun 桥接、文件 IPC | | `wpa.h` | WPA2 4 次握手 + 密钥派生 (CommonCrypto) | | `ccmp.h` | 软件 AES-CCMP (基于 AES-ECB 的 CCM) | | `usb_io.h`, `regs.h`, `rt2800.h` | USB 寄存器 I/O + rt2800 寄存器映射/初始化 | | `wifi` | CLI 客户端 | | `wifid-up.sh`, `com.wifid.plist` | 监管脚本 / 可选的 LaunchDaemon | | `wifi-*.py` | 用于美化守护进程输出的 JSON 的打印器 | | `scan.c`, `faz0_probe.c`, `load_fw.c`, … | 开发历程中使用的独立启动/诊断工具 | | `linux-vm-test/` | 发现初始化 bug 的 usbmon 追踪记录 | ## 硬件（基于设备实测确认，非参考规格书） - USB `0b05:17e8` (ASUS)；真实芯片为 **RT5392** 版本 `0x0223` (`MAC_CSR0`@`0x1000` = `0x53920223`) — USB-ID 数据库错误地将其列为 RT5372。 - 单频段 **2.4 GHz**，2T2R 802.11n。不支持 5 GHz（硬件限制）。 - 主机：Apple M4 Max，macOS，arm64。 ## 许可证 **GPLv2。** 寄存器常量和初始化序列是从 Linux 的 **rt2x00 / rt2800** 驱动 (GPLv2) 移植过来的，因此本项目也采用 GPLv2。参见 `LICENSE`。固件（`rt2870.bin`）来自 `linux-firmware`，**未**在此处重新分发——请使用 `scripts/fetch-firmware.sh` 获取。 *逐步构建，每一步均在真实硬件上经过验证。与 ASUS、 MediaTek 或 Ralink 无任何关联。*

标签：AES-CCMP, Cutter, libusb, Wi-Fi, 客户端加密, 无线网络, 用户态, 网络驱动, 逆向工具