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 — OpenWRT / Linux mac80211 adapter
STATUS:
SYNTHETIC / L0— BUILD-ONLY, UNTESTED ON HARDWARE. No radio was driven, no CSI captured, no log produced on silicon. Every claim below is a design/feasibility statement, not aMEASUREDresult. This adapter uses compliant waveform controls only — it never jams and emits no denial energy.
This directory is the OpenWRT/mac80211 platform adapter for the VEIL privacy
shield. It links the validated portable core
(../core/veil_shield.{h,c} — the keyed Givens rotation over the identity-bearing
"fine" subspace of 802.11 compressed beamforming feedback) and drives the subset
of controls that Linux userspace/mac80211 can actually reach on commodity APs.
Feasibility grade: C (partial — coarse compliant controls only)
Why C, not higher. VEIL's defining action is a per-packet keyed unitary on the compressed beamforming-feedback angles (equivalently, a keyed Q on the LTF spatial mapping / precoder). On every mainstream OpenWRT AP chipset (Qualcomm ath10k/ath11k/ath12k, MediaTek mt76 / mt7915), that report is generated and the precoder applied inside the WiFi MCU firmware blob — userspace and the open driver never touch the pre-transmit V matrix. So the full keyed-rotation path is blob-blocked from OpenWRT. What remains reachable is a set of coarse compliant knobs that perturb, but do not cryptographically obfuscate, the CSI a sensor observes. That is a real, honest defense-in-depth layer — hence C, not D — but it is not the full VEIL transform.
Why not D. Some controls genuinely work from userspace (TX antenna map; hostapd-mediated sounding/beamformer capability), and one chipset family (ath9k) is open enough at the register level that a driver patch could reach the static spatial-mapping matrix — a credible route to B on that specific, older hardware. openwifi (FPGA) and Nexmon (Broadcom) are the routes to the full A-grade keyed rotation, but those are separate adapters, not OpenWRT.
What is FEASIBLE vs. BLOB-BLOCKED from OpenWRT
| VEIL control | Reachable from OpenWRT? | Mechanism (real API / knob) | Notes |
|---|---|---|---|
| TX antenna-map perturbation | ✅ Feasible | NL80211_CMD_SET_WIPHY + NL80211_ATTR_WIPHY_ANTENNA_TX / _RX |
Coarse static spatial-mapping change. Many drivers require phy DOWN and symmetric masks. Compliant. |
| NDP sounding-cadence jitter | 🟡 Indirect | hostapd ctrl_iface (rewrite SOUNDING-DIMENSION, toggle [SU-BEAMFORMER], RECONFIGURE) |
No nl80211 "set sounding interval" exists; the per-NDP timer lives in driver/firmware. We can only jitter the offered capability. |
| Beamformer/beamformee capability toggle | ✅ Feasible | hostapd vht_capab / he_su_beamformer etc. |
Standards-compliant advertisement. Coarse on/off, not per-packet. |
| Spatial-stream → antenna mapping (static Q) | 🟡 Driver-patch (ath9k only) | ath9k PHY spatial-mapping registers (AR_PHY_*) |
Open enough to patch on ath9k; opaque/firmware on ath10k+/mt76. Not a stock userspace knob. |
| MU-MIMO group shuffling | ❌ Blob-blocked | would need NL80211_CMD_VENDOR subcmd that upstream mt76/ath do not expose |
Group formation + steering matrices computed in MCU firmware. |
| Per-packet keyed unitary on LTF / precoder | ❌ Blob-blocked | — | The core VEIL transform. Lives in firmware on all commodity AP parts. Requires firmware patch, or use openwifi / Nexmon adapters. |
| Compressed-BF-report angle edit (φ/ψ) | ❌ Blob-blocked | — | Report is generated in firmware/PHY; not exposed pre-TX on OpenWRT. |
| External sensing-solicitation detection (NDPA cadence) | 🟡 Partial | NL80211_CMD_FRAME + NL80211_CMD_REGISTER_FRAME, or monitor-mode capture |
Commodity drivers do not forward raw NDPA to userspace by default. |
Best candidate chipsets / drivers
- ath9k (Atheros 802.11n) — best open target for a driver-side patch. The most transparent open driver (no per-packet firmware for the datapath), with a long history of PHY register access and the Atheros CSI Tool ecosystem. A static spatial-mapping perturbation and CSI observation are realistic here; full HT beamforming-feedback editing still is not in open code. 802.11n-only.
- mt76 (MediaTek mt7915 / mt7622-mt7615) — best-maintained modern open driver and the most likely place upstream would eventually accept a vendor hook, but beamforming/sounding/MU grouping run in the MCU firmware today, so the keyed path needs a firmware patch (blob-blocked out of the box).
- ath10k / ath11k / ath12k (Qualcomm) — most capable radios but the most closed: regulatory + beamforming + sounding all firmware-side. ath11k/ath12k have no open firmware at all. Worst target for the keyed path.
- openwifi (FPGA SDR) / Nexmon (Broadcom) — the only routes to the full
A-grade keyed rotation; handled by the sibling
../openwifi/and../nexmon/adapters, not this OpenWRT one.
Recommendation: for OpenWRT specifically, target ath9k for a driver-patch proof-of-concept (spatial-mapping + CSI), and mt76/mt7915 as the strategic modern platform pending a firmware/vendor-subcmd hook.
Build (host, build-only)
make core # always works: compiles+links the portable core, no libnl needed
make daemon # builds veil_shieldd IF libnl-genl-3.0 dev headers are present
make clean
make daemon cleanly skips (does not fail) when libnl-genl-3.0 is absent,
printing the required dev packages. On an OpenWRT buildroot use openwrt.mk
(rename to Makefile under package/utils/veil-shieldd/), which builds against
libnl-tiny. See INTEGRATION.md for the per-control hook points and exactly
what a driver/firmware patch would need to touch.
Sources
- Linux
nl80211.h(in-tree, this host):NL80211_CMD_SET_WIPHY,NL80211_ATTR_WIPHY_ANTENNA_TX/_RX,NL80211_CMD_VENDOR,NL80211_CMD_FRAME/NL80211_CMD_REGISTER_FRAME. - ath10k configuration (beamforming only via hostapd
vht_capab, no debugfs sounding control): https://wireless.docs.kernel.org/en/latest/en/users/drivers/ath10k/configuration.html - hostapd beamforming/sounding knobs (
[SU-BEAMFORMER],[MU-BEAMFORMER],[SOUNDING-DIMENSION-4],he_su_beamformer): https://w1.fi/cgit/hostap/tree/hostapd/hostapd.conf and https://github.com/morrownr/USB-WiFi/blob/main/home/AP_Mode/hostapd-WiFi6.conf - mt76 beamforming lives in firmware (mt7622/mt7615 performance/beamforming discussion): https://github.com/openwrt/mt76/issues/863
- Qualcomm firmware closedness (ath11k/ath12k no open firmware; regulatory + features firmware-enforced): ath10k mailing-list thread https://ath10k.infradead.narkive.com/6bdEJZih/qca99xx-with-mu-mimo-and-beamforming and CodeLinaro ath firmware https://git.codelinaro.org/clo/ath-firmware/ath11k-firmware
- ath11k reports VHT beamformee spatial streams from firmware: https://lkml.iu.edu/2210.2/09619.html