mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
feat(privshield): E2E hardware program — validated C core + multi-provider firmware scaffolds
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
This commit is contained in:
Claude
@@ -0,0 +1,94 @@
|
||||
# ADR-290: VEIL end-to-end hardware implementation program (multi-provider firmware)
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed — P4 scaffolding (build-only); portable core validated on host |
|
||||
| **Date** | 2026-08-09 |
|
||||
| **Parent** | ADR-288 (VEIL shield), ADR-289 (harness), ADR-282 (L0–L5 evidence ladder) |
|
||||
| **Location** | `firmware/privshield/` |
|
||||
| **Relates to** | `firmware/esp32-csi-node/` (the CSI sensor/attacker node), ADR-280 (governed actuation), ADR-141 (attestation) |
|
||||
|
||||
## 0. PROOF discipline
|
||||
|
||||
The **only** artifact validated here is the portable C core
|
||||
(`firmware/privshield/core/`): a host test (`make test`) checks energy
|
||||
conservation, reversibility, wrong-key failure, and — pinned — that its
|
||||
SplitMix64 key schedule is **byte-identical to the Rust crate's** PRNG. That is
|
||||
`build`/host-level evidence, not silicon. Every per-provider adapter is a
|
||||
**build-only scaffold** with `TODO(hw)` markers: `SYNTHETIC / L0`, no captured
|
||||
log, no `MEASURED` claim. Nothing in this ADR asserts VEIL works on real
|
||||
hardware; it asserts a *plan and a shared core* to get there (P5).
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-288 shipped VEIL as a deterministic, no-radio Rust model, and the 2025–2026
|
||||
SOTA sweep (ADR-288 §sota) confirmed the mechanism's family is real and
|
||||
standard-permitted. The open question left was **"does this run on real WiFi
|
||||
hardware, and on which?"** — including the user asks: *can OpenWRT / open WiFi
|
||||
software implement it, and can ESP32 help scramble signals?* Answering requires
|
||||
committing to the platform reality rather than assuming a uniform "firmware"
|
||||
target.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Stand up `firmware/privshield/` as a **multi-provider E2E program** around one
|
||||
shared, validated core:
|
||||
|
||||
1. **A portable C shield core** (`core/veil_shield.{h,c}`) — the keyed
|
||||
Givens-rotation obfuscation, `no_std`-friendly C99 (no malloc/libc I/O), with
|
||||
a SplitMix64 key schedule matching the Rust crate so on-air behavior is
|
||||
identical everywhere and every adapter links the *same* math. Host-tested.
|
||||
2. **Per-provider adapters**, each built and graded by a hardware research
|
||||
agent, honest about what its stack can actually touch:
|
||||
- **`openwifi/`** (open PHY/MAC on SDR/FPGA) — the highest-capability path and
|
||||
the one that can host the **keyed-reversible** design end-to-end
|
||||
(protector + AP-side compensation). Carries the **P5 measurement protocol**
|
||||
(`MEASUREMENT.md`) that yields the first `MEASURED` result with a witness.
|
||||
- **`openwrt/`** (Linux `mac80211`, mt76/ath9k…) — the commodity path.
|
||||
Sounding-cadence randomization, MU-group and stream-mapping control are
|
||||
feasible from the driver/hostapd; the per-packet unitary on the LTF spatial
|
||||
mapping is firmware-deep on most parts. Partial.
|
||||
- **`nexmon/`** (Broadcom/Cypress C firmware patches) — the commodity
|
||||
C-firmware route; the read path is proven (Wi-BFI/nexmon_csi), the transmit
|
||||
report-shaping path is research-grade/partial.
|
||||
- **`esp32/`** (ESP-IDF) — **not** a feedback protector (the beamforming path
|
||||
is a closed blob): ESP32 shapes CSI *read*, not transmitted feedback. Its
|
||||
legitimate roles are a **sensing detector** (trigger the AP-side shield) and
|
||||
an **RIS controller** (drive an external reconfigurable surface to scramble
|
||||
the sensing direction — the honest way ESP32 "helps scramble", via an
|
||||
external surface, not its own PHY).
|
||||
3. **Compliance stance carried into hardware:** every control shapes the node's
|
||||
own standards-conformant emission and preserves energy; the ESP32
|
||||
decoy/cover-traffic idea is documented as *legally sensitive / not
|
||||
recommended* precisely because it edges toward the interference line.
|
||||
|
||||
Per-provider feasibility grades live in each subdir README and the top-level
|
||||
feasibility matrix; they are the answer to the "which hardware" question.
|
||||
|
||||
## 3. What this explicitly is NOT
|
||||
|
||||
- **Not validated firmware.** No adapter has run on silicon; there is no witness.
|
||||
The scaffolds compile-*shaped*, not compile-*guaranteed* on their toolchains
|
||||
(which are absent in this environment).
|
||||
- **Not a claim that ESP32 can shield beamforming feedback** — it cannot; it is a
|
||||
detector/RIS-controller only.
|
||||
- **Not jamming, on any platform.** Compliant waveform shaping only.
|
||||
- **Not a MEASURED result.** That is P5, gated on a captured log.
|
||||
|
||||
## 4. Consequences
|
||||
|
||||
- One validated core, four honest provider scaffolds, and a concrete P5
|
||||
measurement plan — a real path from model to silicon, with the effort/blocker
|
||||
reality made explicit per platform.
|
||||
- The shared core keeps every future hardware result consistent with the crate
|
||||
and with each other.
|
||||
- Scope stays inside `firmware/privshield/`; no other crate/firmware is touched
|
||||
(the existing `esp32-csi-node` remains the sensor/attacker node).
|
||||
|
||||
## 5. Validation
|
||||
|
||||
```bash
|
||||
cd firmware/privshield/core && make test # host: energy/reversibility/PRNG parity
|
||||
# per-provider builds require their toolchains (ESP-IDF, OpenWRT SDK, Nexmon,
|
||||
# Vivado) and real hardware — see each subdir's BUILD/INTEGRATION notes.
|
||||
```
|
||||
@@ -147,6 +147,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme
|
||||
| [ADR-286](ADR-286-wifi-densepose-sar-harness-via-metaharness.md) | `wifi-densepose-sar-harness` — MetaHarness with darwin/router/flywheel | Accepted (implemented, published) |
|
||||
| [ADR-288](ADR-288-veil-privacy-shield-compliant-waveform.md) | VEIL — compliant-waveform privacy shield against unauthorized WiFi sensing (`wifi-densepose-privshield`) | Proposed (implemented, P1 reference) |
|
||||
| [ADR-289](ADR-289-wifi-densepose-privshield-harness-via-metaharness.md) | `wifi-densepose-privshield-harness` — npm MetaHarness for the VEIL crate (guidance/router/flywheel) | Proposed (implemented, P1) |
|
||||
| [ADR-290](ADR-290-veil-e2e-hardware-implementation-program.md) | VEIL end-to-end hardware implementation program — portable C core + multi-provider firmware scaffolds (openwifi/openwrt/nexmon/esp32) | Proposed (P4 scaffolding; C core host-validated) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user