smolkik_adm/RuView
1
0
Fork 0
mirror of https://github.com/ruvnet/RuView.git synced 2026-08-29 11:35:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(privshield): rebrand project to "WiFi Veil"

Browse Source 
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
This commit is contained in:
Claude
2026-08-09 16:52:40 +00:00
parent b827dc40b1
commit 1c2b383075
17 changed files with 90 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
firmware/privshield/README.md
View File

@@ -1,8 +1,8 @@
# VEIL privacy shield — end-to-end hardware implementation
# WiFi Veil privacy shield — end-to-end hardware implementation
This tree is the **hardware/firmware realization** of the VEIL compliant-waveform
This tree is the **hardware/firmware realization** of the WiFi Veil compliant-waveform
privacy shield (crate `wifi-densepose-privshield`, ADR-288; hardware program
ADR-290). It takes VEIL from a synthetic reference model toward real silicon
ADR-290). It takes WiFi Veil from a synthetic reference model toward real silicon
across multiple hardware providers.
> **Evidence discipline (read this first).** Everything here is **build-only /
@@ -64,19 +64,19 @@ across multiple hardware providers.
## Feasibility matrix
Grades reflect *capability to actually shape the beamforming-feedback surface*
(the waveform VEIL must touch), **not** effort. Each grade is taken from that
(the waveform WiFi Veil must touch), **not** effort. Each grade is taken from that
provider's own README, produced by a hardware research agent; the effort/blocker
reality is in the "Why" column. All rows are `SYNTHETIC / L0` — build-only, no
silicon, no captured log.
| Provider | Grade | Can it shape the BF-feedback surface? | Why |
|---|:---:|---|---|
| **openwifi** (Zynq + AD9361, open PHY/MAC) | **B** | **Yes — the only full path.** Capability ceiling **A**; graded B for effort **D**. | Only platform exposing the whole PHY/MAC on FPGA, so a keyed rotation *and its inverse* are physically reachable. But it ships SISO 802.11a/g/n with **no native explicit beamforming** (no NDP sounding, no SVD `V`, no compressed report), so VEIL is realized as the client-transparent per-packet keyed unitary on the TX spatial-mapping stage — which requires **new HDL + a 2nd TX chain + a Vivado rebuild**. Carries the P5 measurement protocol. |
| **openwifi** (Zynq + AD9361, open PHY/MAC) | **B** | **Yes — the only full path.** Capability ceiling **A**; graded B for effort **D**. | Only platform exposing the whole PHY/MAC on FPGA, so a keyed rotation *and its inverse* are physically reachable. But it ships SISO 802.11a/g/n with **no native explicit beamforming** (no NDP sounding, no SVD `V`, no compressed report), so WiFi Veil is realized as the client-transparent per-packet keyed unitary on the TX spatial-mapping stage — which requires **new HDL + a 2nd TX chain + a Vivado rebuild**. Carries the P5 measurement protocol. |
| **openwrt** (Linux `mac80211`; mt76 / ath9k / ath1x) | **C** | **Partial — coarse compliant knobs only.** | The per-packet keyed unitary on the compressed-BF angles / LTF precoder is generated **inside the WiFi MCU firmware blob** on every mainstream AP part (Qualcomm ath10k/11k/12k, MediaTek mt76/mt7915) — userspace never touches the pre-TX `V`. Reachable from userspace: TX antenna-map perturbation, hostapd sounding-cadence jitter, beamformer-capability toggles. **ath9k** (802.11n, register-open) is the one credible driver-patch route toward B. |
| **nexmon** (Broadcom/Cypress C-firmware patch; e.g. BCM43455c0) | **C** | **Read = A (solved); write = C/C-.** | *Reading* the compressed-BF angles is already solved (nexmon_csi + Wi-BFI, no firmware change). *Shaping the transmitted* report is graded C: the report is emitted by the proprietary **D11 real-time core** ~10 µs after the NDP, from hardware-updated internal memory — *below* the ARM firmware where Nexmon's C hooks live. Plausible, deep, firmware-version-specific, unproven here. |
| **esp32** (Espressif ESP-IDF) | **F** / **B** | **F** as a self-protecting node; **B** as a supporting device. | The BF-report is emitted by the **closed `esp-phy-lib` blob** with no ESP-IDF hook to intercept or rotate it (`esp_wifi_80211_tx` won't hand-craft sounding feedback) — so **F (infeasible)** for shaping its own feedback. It earns **B (build-only)** in three legitimate, compliance-only supporting roles: **sensing detector** (CSI-rate trigger for the AP-side shield) and **RIS controller** (drive an external passive reconfigurable surface — the honest way ESP32 "helps scramble", via an external surface, never its own PHY). |
**Reading the grades.** Only **openwifi** can host the full keyed-reversible VEIL
**Reading the grades.** Only **openwifi** can host the full keyed-reversible WiFi Veil
design end-to-end (and only after real HDL work). **openwrt** and **nexmon** are
partial: the exact angles are blob-/ucode-locked on commodity silicon, leaving
either coarse compliant perturbations (openwrt) or a deep, unproven ucode-adjacent
@@ -88,7 +88,7 @@ external surface — never by shaping its own transmission.**
## Two firmware variants
- **Keyed-reversible** (VEIL's ~98%-throughput design): the protector rotates and
- **Keyed-reversible** (WiFi Veil's ~98%-throughput design): the protector rotates and
the associated receiver undoes it with the shared key — needs changes on
**both** ends + key agreement. Best result; needs an open PHY (openwifi) for a
true demo, or the client-transparent AP-side variant below.

14
firmware/privshield/esp32/README.md
View File

@@ -1,4 +1,4 @@
# VEIL on ESP32 — feasibility and honest scope
# WiFi Veil on ESP32 — feasibility and honest scope
**Status: `SYNTHETIC / L0` (build-only).** Everything in this directory is an
ESP-IDF component *skeleton*. Nothing here has been flashed, run, or captured on
@@ -18,7 +18,7 @@ surface*.
supporting roles.**
The ESP32 **cannot shape its own transmitted 802.11 beamforming feedback.** The
VEIL shield works by perturbing the *compressed beamforming feedback report* (the
WiFi Veil shield works by perturbing the *compressed beamforming feedback report* (the
Givens/phi-psi angles a station sends back to an AP) with a keyed orthogonal
rotation. On the ESP32 that report is generated **inside the closed Espressif
Wi-Fi PHY/MAC binary blob** (`esp-phy-lib`, shipped in object form; the Wi-Fi
@@ -30,23 +30,23 @@ and action* frames with the PHY choosing the actual precoding — it will not le
you hand-craft the VHT/HE sounding-feedback subtype with a chosen precoder. So
the ESP32 is **not** a beamforming-feedback protector.
**Feasibility grade for "ESP32 as a self-protecting VEIL node": F (infeasible).**
**Feasibility grade for "ESP32 as a self-protecting WiFi Veil node": F (infeasible).**
The one waveform we need to touch is behind a blob with no hook.
**Feasibility grade for "ESP32 as a VEIL supporting device": B (feasible,
**Feasibility grade for "ESP32 as a WiFi Veil supporting device": B (feasible,
build-only).** Three legitimate roles below, best-first.
---
## What the ESP32 can and cannot do
| Capability | ESP-IDF surface | VEIL-relevant? | Verdict |
| Capability | ESP-IDF surface | WiFi Veil-relevant? | Verdict |
|---|---|---|---|
| Read CSI (channel state) | `esp_wifi_set_csi_config` / `esp_wifi_set_csi_rx_cb` / `esp_wifi_set_csi` | Yes — detect *being sensed* | **CAN** (observe only) |
| Promiscuous / sniffer RX | `esp_wifi_set_promiscuous` | Yes — more CSI, frame cadence | **CAN** (observe only) |
| Inject raw mgmt/data frames | `esp_wifi_80211_tx` (beacon, probe, action, non-QoS data only) | Marginal; not for BF feedback | **CAN (limited)** |
| Drive external GPIO/SPI hardware | `gpio_*`, `spi_master_*` | Yes — control an external RIS | **CAN** |
| Shape its own **beamforming feedback** (compressed BF report angles) | *none* — generated in closed PHY blob | This is the actual VEIL waveform | **CANNOT** |
| Shape its own **beamforming feedback** (compressed BF report angles) | *none* — generated in closed PHY blob | This is the actual WiFi Veil waveform | **CANNOT** |
| Choose/replace its own **precoding matrix** | *none* — PHY-internal | Yes, but inaccessible | **CANNOT** |
| Modify the Wi-Fi PHY / `esp-phy-lib` | *none* — object-only, NDA | — | **CANNOT** |
@@ -63,7 +63,7 @@ it does so without the ESP32 emitting any RF of its own.
### 1. `veil_sensing_detector/` — sensing-solicitation detector (strongest, clearly compliant)
Uses the CSI callback (+ promiscuous RX) to estimate how often the node is being
sounded/solicited, and raises an engage **trigger** (GPIO / MQTT / ESP-NOW) that
tells the *AP-side* VEIL shield (running the portable `../core/veil_shield.c`) to
tells the *AP-side* WiFi Veil shield (running the portable `../core/veil_shield.c`) to
turn on. Pure observe-plus-control-signal; the ESP32 shapes nothing on air. This
is the role we would actually build first.

4
firmware/privshield/nexmon/BUILD.md
View File

@@ -1,4 +1,4 @@
# Building the VEIL Nexmon patch — **UNTESTED**
# Building the WiFi Veil Nexmon patch — **UNTESTED**
> **This procedure has never been run.** It has not been built with the Nexmon
> toolchain, not flashed, and not captured on air. Addresses/symbols in
@@ -53,7 +53,7 @@ The core is `no_std`-style C99: no malloc, no libc I/O, only `<math.h>`
- link a small `libm`/`compiler-rt` for `arm-none-eabi`;
- or replace the trig with a fixed-point / CORDIC Givens rotation
(`TODO(reverse-engineer)`), which also avoids float on parts without an FPU.
3. All VEIL working storage is stack-bounded (`VEIL_MAX_FINE`, `CACHE` in the
3. All WiFi Veil working storage is stack-bounded (`VEIL_MAX_FINE`, `CACHE` in the
core) — no heap is introduced on-chip.
## Build

8
firmware/privshield/nexmon/README.md
View File

@@ -1,6 +1,6 @@
# VEIL protector — Nexmon (Broadcom/Cypress) path
# WiFi Veil protector — Nexmon (Broadcom/Cypress) path
C-firmware-patch adapter that would call the portable VEIL core
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.
@@ -35,7 +35,7 @@ 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
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
@@ -83,7 +83,7 @@ The skeleton wires candidate **#1** and leaves #2/#3 documented but unimplemente
## What is realistic
- **Realistic now:** verify VEIL's *effect* by reading — capture the shaped vs.
- **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

6
firmware/privshield/openwifi/MEASUREMENT.md
View File

@@ -1,10 +1,10 @@
# P5 measurement protocol — openwifi VEIL end-to-end
# P5 measurement protocol — openwifi WiFi Veil end-to-end
> **STATUS: SYNTHETIC / L0 — this is a PLAN, not a result. No hardware has been
> run; no capture, log, or number in this repo is real.** This document defines
> exactly what must be executed and captured to earn the first `MEASURED` claim
> under CLAUDE.md's hardware-evidence rule. Until the witness artifact below
> exists, every accuracy/throughput/energy statement about openwifi VEIL is
> exists, every accuracy/throughput/energy statement about openwifi WiFi Veil is
> `SYNTHETIC` and must be labelled so. **Compliant waveform controls only —
> orthogonal, energy-preserving; never jamming.**
@@ -47,7 +47,7 @@ per-packet keying uses `(key, packet_counter)` as in `HDL_NOTES.md`.
## Procedure
Run every condition **twice**: VEIL **OFF** (baseline) and **ON**. Same
Run every condition **twice**: WiFi Veil **OFF** (baseline) and **ON**. Same
positions, same MCS, same duration, same seed for the attacker model.
1. **Correctness precondition (not a defense claim).** Confirm on-FPGA

4
firmware/privshield/openwifi/README.md
View File

@@ -1,4 +1,4 @@
# VEIL protector — openwifi (Xilinx Zynq + AD9361, open PHY/MAC)
# WiFi Veil protector — openwifi (Xilinx Zynq + AD9361, open PHY/MAC)
> **STATUS: SYNTHETIC / L0 — build-only scaffold. No hardware, no flash, no
> capture. Nothing here has run on silicon.** Per CLAUDE.md, none of this is a
@@ -31,7 +31,7 @@ highest-*effort* path:
fmcomms2/3 has two DACs) plus a new spatial-mapping RTL stage and a Vivado
rebuild — days-to-weeks of FPGA work, not a driver patch.
Because of (1), on openwifi VEIL is realized as the **client-transparent
Because of (1), on openwifi WiFi Veil is realized as the **client-transparent
per-packet keyed unitary** (LeakyBeam family) applied at the TX spatial-mapping
stage, with the legitimate STA (a second openwifi node sharing the key)
inverting it — **not** as obfuscation of a compressed-BF report the hardware

6
firmware/privshield/openwrt/INTEGRATION.md
View File

@@ -1,4 +1,4 @@
# VEIL ↔ `mac80211` / driver integration map
# WiFi Veil ↔ `mac80211` / driver integration map
> **`SYNTHETIC / L0` — BUILD-ONLY, UNTESTED ON HARDWARE.** These are hook-point
> designs derived from public API/source, not validated on silicon. Function and
@@ -47,7 +47,7 @@ Legend: **US** = userspace-reachable today · **DP** = needs driver patch ·
firmware change to honor an externally supplied grouping. Not reachable without
both a driver and firmware patch.
## 4. Per-packet keyed unitary (the core VEIL transform) — **FW** (blob-blocked)
## 4. Per-packet keyed unitary (the core WiFi Veil transform) — **FW** (blob-blocked)
- **Daemon:** `veil_apply_keyed_rotation()` → `veil_shield_apply(fine, n, key,
passes)` from the portable core. Orthogonal / energy-preserving (the
@@ -85,7 +85,7 @@ Legend: **US** = userspace-reachable today · **DP** = needs driver patch ·
## Summary of the effort boundary
| Control | Effort to reach full VEIL fidelity |
| Control | Effort to reach full WiFi Veil fidelity |
|---|---|
| TX antenna map | Ready now (US), coarse only |
| Sounding cadence jitter | Wire hostapd `ctrl_iface` (US), coarse only |

12
firmware/privshield/openwrt/README.md
View File

@@ -1,4 +1,4 @@
# VEIL — OpenWRT / Linux `mac80211` adapter
# WiFi 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
@@ -6,7 +6,7 @@
> 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
This directory is the OpenWRT/`mac80211` platform adapter for the WiFi 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
@@ -16,7 +16,7 @@ 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
**Why C, not higher.** WiFi 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
@@ -25,7 +25,7 @@ open driver never touch the pre-transmit V matrix. So the full keyed-rotation pa
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.
but it is not the full WiFi Veil transform.
**Why not D.** Some controls genuinely work from userspace (TX antenna map;
hostapd-mediated sounding/beamformer capability), and one chipset family
@@ -38,14 +38,14 @@ 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 |
| WiFi 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. |
| **Per-packet keyed unitary on LTF / precoder** | ❌ Blob-blocked | — | The core WiFi 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. |