SyriusM/ar9271-sovereign-build
GitHub: SyriusM/ar9271-sovereign-build
一套为 AR9271 USB WiFi 适配器构建自定义固件的可复现方案，解决了现代 GCC 15+ 工具链下构建失败的问题，并提供签名注入和安全实机测试能力。
Stars: 1 | Forks: 0
# ar9271-sovereign-build
为高通 Atheros AR9271 USB WiFi 适配器（TP-Link TL-WN722Nv1、Alfa AWUS036NHA、ASUS USB-N13 v1 等）构建**经过签名的自定义固件**的可复现方案，已在**实体芯片**上通过自动回滚机制进行了验证。
本项目**并不是**固件本身的分支——它是一套方案与工具链，封装了 [qca/open-ath9k-htc-firmware](https://github.com/qca/open-ath9k-htc-firmware) 并解决了现代工具链的引导问题。
## 为什么会有这个项目
在 2026 年的 Linux 系统上构建 open-ath9k-htc-firmware 会立即失败：
```
configure: error: could not find a working compiler
make: *** [Makefile:147: .../gmp-6.2.0/.built] Błąd 1
```
GMP 6.2.0（该仓库引导的 GCC 10.2 交叉编译器的一个构建依赖）使用了 K&R 风格的函数声明：
```
void g(){}
/* ... */
g(i, d[i].src, d[i].n, got, d[i].want, 9); /* 6 args to a 0-arg function */
```
现代 GCC（15.x, 16.x）将其视为**错误**，而不是警告。工具链构建在生成任何一个 `xtensa-elf-gcc` 之前就会终止。
本仓库提供了：
1. 一个使用 `debian:11` 的 **Docker 方案**（其 GCC 10.2.1 版本与上游仓库最初设计所依赖的版本一致），从而让补丁能顺利应用，且无需修改即可成功执行 `make toolchain`。
2. 一个最小化的**签名补丁**，演示了如何以及在哪里向固件二进制文件 (blob) 中注入自定义数据，并通过 `strings` 进行验证。
3. 一个**安全的实机测试脚本**，通过内核的 `use_dev_fw=1` 机制加载自定义固件，而不会影响生产环境的 `htc_9271-1.4.0.fw`，并在超时或按下 `Ctrl+C` 时自动回滚。
## 你将获得什么
- 可复现的交叉编译器：针对 AR9271 特定 Xtensa 核心（`XCHAL_HAVE_DIV32=0`、`MUL32_HIGH=1`、`ABSOLUTE_LITERALS=1`）的 **xtensa-elf-gcc 10.2.0**
- 一个已签名的 `htc_9271.fw` 二进制文件（51008 字节——与原厂固件插槽大小一致）
- 通过 `dmesg` 确认芯片已使用你的固件成功枚举的实机测试结果
- 一个干净的回滚路径，确保生产环境的 WiFi 不会受到任何风险影响
## 这不是什么
- **不是 TX 功率解锁。** AR9271 的 TX 功率表存储在 EEPROM 中，而不是固件里。修改固件不会改变 TX dBm。若要进行 TX/合规性更改，你需要重新刷写外部 EEPROM（这是一项独立的硬件工程，请参阅下文的“后续计划”）。
- **不是 LED/重试机制修改。** 这些策略位于内核驱动程序（`ath9k_htc`）中，而不是固件里。该固件只是一个薄层：USB 协议 + 底层 MAC + WMI 服务。
- **不是安全工具。** 这是一个具有作品集质量的可复现性实践项目，而不是一个漏洞利用框架。
## 构建
```
# 1. Clone upstream 固件 repo (独立目录):
git clone https://github.com/qca/open-ath9k-htc-firmware.git ~/src/ath9k-htc-firmware
cd ~/src/ath9k-htc-firmware
# 2. 应用此 repo 的 signature patch:
git apply /path/to/ar9271-sovereign-build/patches/0001-sovereign-build-signature.patch
# 3. 在 Debian 11 container 内 Bootstrap toolchain (GCC 10 匹配 repo deps):
docker run --rm -v "$PWD":/work -w /work debian:11 bash -c "
apt-get update -qq &&
apt-get install -y -qq build-essential cmake wget gperf bison flex \
texinfo libtool gawk patch m4 file &&
make toolchain
"
# 4. Build 固件本身 (相同 container, toolchain 在 path 上):
docker run --rm -v "$PWD":/work -w /work debian:11 bash -c "
apt-get update -qq &&
apt-get install -y -qq build-essential cmake perl &&
export PATH=/work/toolchain/inst/bin:\$PATH &&
make -C target_firmware
"
# 5. 验证嵌入的 signature:
strings target_firmware/htc_9271.fw | grep -i sovereign
# → SOVEREIGN-BUILD:...
```
输出结果：`target_firmware/htc_9271.fw`——大小为 51008 字节，并已嵌入了你的签名。
## 实机测试
```
sudo scripts/test-sovereign-fw.sh
```
此操作将会：
1. 停止任何正在使用 AR9271 的 AP（默认为 `hostapd-balkon`——如果你使用的是其他设备，请进行修改）。
2. 将你的自定义构建安装为 `/lib/firmware/ath9k_htc/htc_9271-1.dev.0.fw`（独立路径——内核仅在设置了 `use_dev_fw=1` 时才会加载此文件）。
3. 执行 `rmmod ath9k_htc && modprobe ath9k_htc use_dev_fw=1`。
4. 打印 `dmesg` 输出，显示已加载的固件路径、传输大小、HTC 初始信用点、芯片版本以及接口状态。
5. 30 秒后（或按下 `Ctrl+C` 时），自动执行以下操作：
- 重新加载生产环境的固件（不带参数的 `rmmod` + `modprobe`）。
- 从 `/lib/firmware/` 中移除开发版固件文件。
- 重启 `hostapd-balkon`。
成功进行实机加载的验证证据：
```
[15767.941398] usb 1-7: ath9k_htc: Firmware ath9k_htc/htc_9271-1.dev.0.fw requested
[15769.028664] usb 1-7: ath9k_htc: Transferred FW: ath9k_htc/htc_9271-1.dev.0.fw, size: 51008
[15769.275417] ath9k_htc 1-7:1.0: ath9k_htc: HTC initialized with 33 credits
[15769.501790] ath9k_htc 1-7:1.0: ath9k_htc: FW Version: 1.4
[15769.505162] ieee80211 phy17: Atheros AR9271 Rev:1
[15769.510881] ath9k_htc 1-7:1.0 wlan_ap: renamed from wlan0
```
完整的溯源信息请参见 [BUILD-CERTIFICATE.txt](BUILD-CERTIFICATE.txt)。
## 补丁说明
[`patches/0001-sovereign-build-signature.patch`](patches/0001-sovereign-build-signature.patch) 向 `wlan/if_ath.c` 中注入了一个 `__attribute__((used))` 字符串，以便链接器将其保留在最终生成的二进制文件中。构建完成后，执行 `strings htc_9271.fw | grep -i sovereign` 即可返回你的签名。
为什么要这么做？因为它证明了该二进制文件来自于你的构建。每次构建的 SHA256 哈希也是唯一的，但签名具备人类可读性，并且只要源代码保持不变，即便经过重新编译也能留存下来。这是具备作品集价值的最小化修改。
## 后续计划（独立的硬件方向）
若要对 AR9271 进行实际的功能更改：
- **TX 功率 / 合规性解锁** → 物理上拆开适配器外壳，找到 SOIC-8 封装的 25 系列 SPI flash 和/或 24 系列 I2C EEPROM，使用 `flashrom -p ch341a_spi`（SPI）或 `ch341prog`（I2C）进行读取转储，修改后重新刷写。适配器数据手册（LPCC-68，第 14 页）确认这两种外设通常是外部挂载的。
- **LED / 重试调优** → 需要在 `drivers/net/wireless/ath/ath9k/` 中修改内核驱动，而不是固件。
- **帧注入改进** → 这部分实际上属于固件范畴，具体模式请参见 [PR #163](https://github.com/qca/open-ath9k-htc-firmware/pull/163)。
## 免责声明
本方案旨在用于**安全研究、教育以及在您自己拥有的硬件上进行可复现的固件构建实践**。
- **不提供任何形式的保证**，无论是明示还是默示的——请参阅 GPL-2.0 许可证第 11-12 节。
- 用户需对遵守**当地法规**（电信法、射频辐射、监管域、EIRP 限制）自行负责。
- 本方案明确**不会解锁 TX 功率、区域锁定或其他监管控制**（这些数据存储在 EEPROM 中，而不是固件里——请参阅上文的“这不是什么”）。
- 请勿对您不拥有或未获得明确授权进行测试的硬件使用本方案。
- 作者对因使用本材料而导致的误用、硬件损坏、违规操作或数据丢失不承担任何责任。
合法的主要应用场景包括：了解 AR9271 固件的结构，解决现代工具链引导问题（GCC 15+），演示带有自动回滚的安全实机测试方法，以及促进对 Atheros 硬件的开源理解。随附的 `test-sovereign-fw.sh` 脚本特意使用了内核的 `use_dev_fw=1` 机制，从而确保生产环境的固件永远不会被修改。
## 许可证
本仓库中的签名补丁和工具均采用 **GPL-2.0** 许可证，以与上游固件仓库中被修改文件的许可证保持一致（根据上游的 `NOTICES.TXT`，`wlan/if_ath.c` 遵循 ECOS GPLv2 的相关条款）。出于一致性考虑，本仓库下的其他构建脚本同样采用了 GPL-2.0 许可证。
上游固件本身受高通 Atheros 持有的 ClearBSD 许可证保护；请参见 [qca/open-ath9k-htc-firmware/LICENCE.TXT](https://github.com/qca/open-ath9k-htc-firmware/blob/master/LICENCE.TXT)。本仓库不分发任何上游代码——仅提供补丁和工具链。
## 相关工作
- [SyriusM/rtl8188eus-efuse-tool](https://github.com/SyriusM/rtl8188eus-efuse-tool) — 用于 Realtek RTL8188EUS USB WiFi 适配器上的 OTP EFuse 内存的用户空间 CLI 工具（通过 libusb 绕过内核驱动）。
标签：AR9271, Cutter, Debian, Docker, GCC, Linux内核, TP-Link, USB网卡, WiFi安全, Xtensa, 云资产清单, 交叉编译, 可复现构建, 固件修改, 固件开发, 固件签名, 安全测试, 安全防御评估, 嵌入式开发, 工具链, 开源固件, 攻击性安全, 无线网络, 物联网安全, 硬件安全, 签名注入, 网络安全, 自定义固件, 请求拦截, 路由器安全, 逆向工程, 隐私保护, 高通Atheros