mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
Claude
1c2b383075
Adopt "WiFi Veil" as the product name across all user-facing surfaces, keeping VEIL (Verifiable Emission-shaping for Identity-Leakage prevention) as the technical codename it's built on. Only prose, titles, descriptions, and the console UI change — no code identifiers, file names, crate/npm `name` fields, or the deterministic proof witness are touched, so `cargo test` and the C-core host test are unaffected. - Crate & research READMEs: title + defining line now "WiFi Veil (codename VEIL — …)". - Cargo.toml / package.json / plugin.json descriptions: "WiFi Veil …". - Console UI (veil-console.html): title, brand, and copy say "WiFi Veil". - Firmware tree (README, per-provider READMEs, BUILD/INTEGRATION/MEASUREMENT): "WiFi Veil protector/core/shield". - Harness manifest: recomputed SHA-256 digests for the four changed packaged files (README, package.json, CLAUDE.md, plugin.json) — all verified consistent. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01WEXNqzs7UsfNFBcP5yW21p
125 lines
7.1 KiB
Markdown
125 lines
7.1 KiB
Markdown
# 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 — <https://github.com/seemoo-lab/nexmon>
|
|
- `nexmon_csi` (chips: bcm4339, bcm43455c0, bcm4358, bcm4366c0) —
|
|
<https://github.com/seemoo-lab/nexmon_csi>
|
|
- Wi-BFI (reads BFAs/BFI from captured compressed-beamforming action frames) —
|
|
<https://github.com/kfoysalhaque/Wi-BFI>, paper arXiv:2309.04408
|
|
<https://arxiv.org/abs/2309.04408>
|
|
- BCM43455c0 patches / D11 headers (`d11.h`) —
|
|
<https://github.com/seemoo-lab/nexmon/tree/master/patches/bcm43455c0>
|
|
- D11 real-time core / ucode reverse engineering (SEEMOO, Quarkslab) —
|
|
<https://www.seemoo.tu-darmstadt.de/> ,
|
|
<https://blog.quarkslab.com/reverse-engineering-broadcom-wireless-chipsets.html>
|
|
- 802.11ac VHT NDP sounding & compressed beamforming report structure (context) —
|
|
<https://community.cisco.com/t5/wireless-mobility-knowledge-base/802-11ac-transmit-beamforming-and-vht-ndp-sounding-procedure/ta-p/3155879>
|
|
|
|
> 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.
|