b827dc40b1
Take VEIL from the synthetic Rust reference model toward real WiFi silicon
across multiple hardware providers, around one shared, host-validated core.
Answers the questions "can OpenWRT / open WiFi software implement this?" and
"can ESP32 help scramble signals?" with an honest per-platform feasibility map.
Portable C shield core (firmware/privshield/core/) — VALIDATED (host test):
- veil_shield.{h,c}: keyed Givens-rotation obfuscation of the identity-bearing
"fine" subspace, C99, no malloc / no libc I/O, only <math.h>. SplitMix64 key
schedule byte-identical to the Rust crate, so on-air behavior is consistent
everywhere and every adapter links the same math.
- make test passes: energy conservation (orthogonal => "not jamming"),
reversibility (recover inverts apply), wrong-key-fails, and PRNG stream parity
with the Rust crate. This is build/host evidence, NOT silicon.
Per-provider adapters (all SYNTHETIC / L0, build-only, TODO(hw) markers):
- openwifi/ grade B (ceiling A, effort D): only open PHY/MAC (FPGA) that can
host the full keyed rotation + inverse; needs new HDL + 2nd TX chain. Carries
the P5 measurement protocol (MEASUREMENT.md) for the first MEASURED result.
- openwrt/ grade C: per-packet keyed unitary is blob-blocked on commodity APs;
coarse compliant knobs (TX antenna map, sounding-cadence jitter) reachable
from userspace/hostapd; ath9k is the one credible driver-patch route.
- nexmon/ grade C: reading the compressed-BF angles is solved (nexmon_csi /
Wi-BFI); shaping the transmitted report is research-grade (D11 ucode-adjacent).
- esp32/ grade F (self) / B (supporting): cannot shape its own BF feedback
(closed esp-phy-lib blob); legitimate as a sensing detector and external-RIS
controller — the honest way ESP32 "helps scramble", via an external surface.
Docs:
- firmware/privshield/README.md: architecture, layout, and the feasibility matrix.
- ADR-290: the E2E hardware program, PROOF discipline, and per-provider decision;
added to docs/adr/README.md index.
Compliant waveform controls only, never jamming. No adapter has run on silicon;
no MEASURED claim is made (that is roadmap P5, gated on a captured log).
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01WEXNqzs7UsfNFBcP5yW21p
VEIL protector — Nexmon (Broadcom/Cypress) path
C-firmware-patch adapter that would call the portable VEIL core
(../core/veil_shield.{h,c}) on the compressed-beamforming-feedback angles
before transmission, using the 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 noMEASUREDclaims and no hardware logs. The patch is an honest skeleton withTODO(hw)andTODO(reverse-engineer)markers, not working firmware. Per CLAUDE.md, no defense claim becomesMEASUREDwithout 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 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 TODOs.
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.
- 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_*/ awlc_send*mgmt/action path), a branch hook there could locate the report's fine-angle block and callveil_shield_applyin place. Cheapest if it exists on this chip. - ARM → D11 TX descriptor / template handoff. Hook where the driver stages
a frame into the D11 TX FIFO / template RAM (
wlc_d11hdrs/wlc_txfiforegion) and rewrite the angle bytes there. Requires knowing the exact template-RAM offset of the report body. - 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 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.