mirror of https://github.com/ruvnet/RuView synced 2026-08-11 20:41:44 +00:00

Files

T

Claude b827dc40b1 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

2026-08-09 16:34:11 +00:00

5.0 KiB

Raw Blame History

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:

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.
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).
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

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.

5.0 KiB Raw Blame History Unescape Escape