# WiFi Veil protector — Nexmon (Broadcom/Cypress) path C-firmware-patch adapter that would call the portable WiFi Veil core (`../core/veil_shield.{h,c}`) on the compressed-beamforming-feedback **angles before transmission**, using the [Nexmon](https://github.com/seemoo-lab/nexmon) patching framework on a Broadcom/Cypress WiFi chip. > **Evidence discipline.** Everything here is **`SYNTHETIC` / L0 / build-only**. > Nothing in this directory has been built with the Nexmon toolchain, flashed to > a chip, or captured on air. There are **no** `MEASURED` claims and **no** > hardware logs. The patch is an honest **skeleton** with `TODO(hw)` and > `TODO(reverse-engineer)` markers, not working firmware. Per CLAUDE.md, no > defense claim becomes `MEASURED` without a captured runtime log from real > silicon (roadmap P5). > > **Compliant waveform only — never jamming.** The core applies an *orthogonal* > (energy-preserving) keyed rotation to the node's *own* standards-conformant > feedback report. It does not add power, transmit out of turn, or interfere > with any other station. ## Feasibility grade: **C** (research-grade, partial, unproven) | Sub-path | Grade | Why | |---|---|---| | **Read** the compressed BF feedback | **A** (proven by others) | `nexmon_csi` extracts CSI, and Wi-BFI parses the compressed-beamforming *angles* straight from captured action frames — no firmware change at all. The report content is observable today. | | **Write / shape** the transmitted report | **C / C-** | The report is generated by the proprietary **D11** real-time core, not the ARM firmware Nexmon comfortably patches. The hook point is deep, chip- and firmware-version-specific, and unverified here. Plausible, not demonstrated. | Grade **C** reflects *this* deliverable's goal — shaping the **TX** report. The read side is a solved problem and is graded only to contrast honestly. ### Why the write path is hard (the core honesty point) Broadcom/Cypress chips put all time-critical 802.11 MAC/PHY work on the **D11 core**, a proprietary microcontroller running a programmable state machine ("ucode"). Published reverse-engineering of these chips reports that the D11 generates the **VHT/HE compressed beamforming report ~10 µs after the NDP**, with its contents fetched from an **internal memory updated directly by the hardware** on NDP reception. In other words, the angles WiFi Veil wants to touch are staged and emitted inside the ucode/PHY path on a microsecond deadline — *below* the ARM "wl" driver firmware where Nexmon's C hooks (`__attribute__((at(addr, ...)))` flashpatches / branch hooks) live most reliably. Reaching them means either a D11-ucode patch (needs the D11 assembler and SHM/template-RAM layout) or catching the report while the ARM path still assembles the action-frame body — if it does so on this chip at all. Both are `TODO(reverse-engineer)`. ## Target chip(s) Primary: **BCM43455c0** (Raspberry Pi 3B+/4B; also RPi Zero 2 W), firmware **7_45_154** (Raspbian) or **7_45_189** (Cypress) — the best-documented, most-reproducible Nexmon target, and one of the four chips `nexmon_csi` already supports. Secondary candidates that `nexmon_csi` also supports: **BCM4339** (Nexus 5), **BCM4358** (Nexus 6P), **BCM4366c0** (Asus RT-AC86U). We scope the skeleton to BCM43455c0 / 7_45_189 and leave the others as build-matrix `TODO`s. Caveat: the RPi BCM43455c0 is an **802.11ac (VHT)** single-stream part; its own *transmit* beamforming/sounding activity as a beamformee is limited. The skeleton targets the **VHT compressed beamforming report** action-frame path; whether this chip emits enough to shape in practice is itself a `TODO(hw)` question. ## Hook-point candidates (all `TODO(reverse-engineer)`) Ordered most-tractable → deepest. Addresses are **placeholders** — real offsets come from disassembling the specific firmware blob and cross-checking the Nexmon symbol tables (`wl_ram.elf` / IDA); none are known-good here. 1. **ARM action-frame TX assembly (best first target).** If the "wl" driver assembles the VHT Compressed Beamforming Report action-frame *body* in ARM firmware before handing it to the D11 (function family around `wlc_txbf_*` / a `wlc_send*mgmt`/action path), a branch hook there could locate the report's fine-angle block and call `veil_shield_apply` in place. Cheapest if it exists on this chip. 2. **ARM → D11 TX descriptor / template handoff.** Hook where the driver stages a frame into the D11 TX FIFO / template RAM (`wlc_d11hdrs` / `wlc_txfifo` region) and rewrite the angle bytes there. Requires knowing the exact template-RAM offset of the report body. 3. **D11 ucode patch (deepest).** Patch the ucode routine that copies angles from the hardware-updated internal memory into the outgoing report, applying the rotation in D11 SHM. Needs the D11 assembler and PHY/SHM map; highest fidelity, highest effort, most fragile across firmware versions. The skeleton wires candidate **#1** and leaves #2/#3 documented but unimplemented. ## What is realistic - **Realistic now:** verify WiFi Veil's *effect* by reading — capture the shaped vs. unshaped report with `nexmon_csi`/Wi-BFI and confirm the fine subspace changed while energy (SNR/norm) is preserved. This validates the math, not the TX hook. - **Realistic with serious RE effort:** candidate #1, on one pinned firmware, as a demo — partial, brittle, chip-specific. - **Not realistic as a portable product:** a clean, firmware-version-stable TX report-shaping patch across Broadcom parts. Treat as research. ## Risk / honesty - Wrong flashpatch offsets can **brick the WiFi blob** (recoverable by reflashing stock firmware, but real). - Regulatory: the transform is energy-preserving and rides standards-marked spatial-mapping freedom, but any TX-path firmware patch on a certified radio is **outside the device's certification** — bench/anechoic use only. - Firmware blobs are proprietary; do **not** commit extracted firmware, symbols, or ROM dumps to this repo. ## Sources - Nexmon framework — - `nexmon_csi` (chips: bcm4339, bcm43455c0, bcm4358, bcm4366c0) — - Wi-BFI (reads BFAs/BFI from captured compressed-beamforming action frames) — , paper arXiv:2309.04408 - BCM43455c0 patches / D11 headers (`d11.h`) — - D11 real-time core / ucode reverse engineering (SEEMOO, Quarkslab) — , - 802.11ac VHT NDP sounding & compressed beamforming report structure (context) — > The "~10 µs / hardware-updated internal memory" characterization above is drawn > from published Broadcom D11 reverse-engineering (reported for BCM4365-class > parts) and is used here as design guidance; it is **not** independently > verified on BCM43455c0 in this repo. `TODO(reverse-engineer)`: confirm on the > target blob.