mirror of https://github.com/ruvnet/RuView.git synced 2026-08-27 02:25:47 +00:00

Files

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.1 KiB

Raw Blame History

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 attribute names are real (verified against in-tree linux/nl80211.h and public hostapd/driver docs); where a hook does not exist upstream it is marked TODO(hw) with what a patch would have to add. Compliant controls only.

Legend: US = userspace-reachable today · DP = needs driver patch · FW = needs firmware patch (blob-blocked).

1. TX antenna-map perturbation — US (feasible)

Daemon: veil_set_tx_antenna_mask() in veil_shieldd.c.
Kernel path: nl80211 → cfg80211_ops.set_antenna() → driver .set_antenna (e.g. mt7915_set_antenna, ath9k set_antenna).
Attributes: NL80211_CMD_SET_WIPHY, NL80211_ATTR_WIPHY_ANTENNA_TX, NL80211_ATTR_WIPHY_ANTENNA_RX.
Constraints: many drivers require the phy DOWN and accept only symmetric masks; validate per driver. Coarse static spatial-mapping change, not the keyed rotation. Fully standards-compliant.

2. NDP sounding-cadence jitter — US (indirect)

Daemon: veil_randomize_sounding_cadence() / veil_next_cadence_ms(). The schedule is derived from the session key via the core SplitMix64 so the paired receiver can anticipate it (not random spraying).
Real lever: hostapd ctrl_iface (UNIX socket /var/run/hostapd/<iface>): SET he_su_beamformer … / rewrite vht_capab [SOUNDING-DIMENSION-n] / toggle [SU-BEAMFORMER], then RECONFIGURE. Config keys documented in hostapd.conf.
TODO(hw): there is no nl80211 "set sounding interval" command; the per-NDP timer is in driver/firmware. We can only jitter the offered cadence. The ctrl_iface write itself is not yet wired (function currently only computes ms).

3. MU-MIMO group shuffling — FW (blob-blocked)

Daemon: veil_shuffle_mumimo_groups() — explicit -ENOTSUP no-op.
Where it lives: MU group formation + per-group steering matrices are computed in the WiFi MCU firmware on mt76 (mt7915) and all ath1x parts.
TODO(hw): would require NL80211_CMD_VENDOR with a driver-specific NL80211_ATTR_VENDOR_ID / NL80211_ATTR_VENDOR_SUBCMD / NL80211_ATTR_VENDOR_DATA that upstream mt76/ath do not define, plus a 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)

Daemon: veil_apply_keyed_rotation() → veil_shield_apply(fine, n, key, passes) from the portable core. Orthogonal / energy-preserving (the "not jamming" invariant, checked via veil_l2_norm before/after).
What a full path must touch:
- mt76 (mt7915): the MCU firmware stage that builds the compressed beamforming report (φ/ψ angles) or applies the steering/precoder Q to the LTF spatial mapping. A firmware patch would call the rotation on the fine subspace before the report is emitted / precoder applied. The driver (mt7915/mcu.c) would ferry the key/passes down via a new MCU command.
- ath9k (DP, best open case): the static spatial-mapping matrix is set via AR_PHY_* registers in the open PHY init; a driver patch could apply a keyed static Q there. This is coarser than a true per-packet report edit but is the most credible OpenWRT-adjacent route (older 802.11n hardware only).
- ath10k/ath11k/ath12k: report generation + precoder are entirely firmware-side with no open firmware (ath11k/ath12k) — not patchable.
TODO(hw): on OpenWRT there is no userspace/mac80211 hook that hands the pre-precoder V/steering buffer to the daemon before TX. Reaching it needs the driver+firmware patch above, or use the openwifi (FPGA) / Nexmon (Broadcom) adapters, which expose the datapath. The daemon only proves the math is invariant; nothing goes on air.

5. Sensing-solicitation (NDPA) detection — US/DP (partial)

Daemon: veil_event_cb() on NL80211_CMD_FRAME.
Real path: NL80211_CMD_REGISTER_FRAME to subscribe to specific management action categories, delivered as NL80211_CMD_FRAME with NL80211_ATTR_FRAME. Classify VHT/HE compressed beamforming action (categories 21 / 30) and NDP Announcement to measure cadence.
TODO(hw): commodity drivers do not forward raw NDPA to userspace by default; honest external-solicitation detection needs monitor-mode capture or a driver notification that is not guaranteed upstream. Frame parsing is stubbed.

Summary of the effort boundary

Control	Effort to reach full VEIL fidelity
TX antenna map	Ready now (US), coarse only
Sounding cadence jitter	Wire hostapd `ctrl_iface` (US), coarse only
Static spatial Q	ath9k driver patch (DP)
MU grouping	driver vendor subcmd + firmware (FW)
Per-packet keyed rotation	mt76/ath firmware patch, or openwifi/Nexmon adapter (FW)
NDPA detection	frame registration + likely driver patch (US/DP)

5.1 KiB Raw Blame History

VEIL ↔ mac80211 / driver integration map