mirror of
https://github.com/ruvnet/RuView.git
synced 2026-08-31 04:25:54 +00:00
1c2b383075
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
131 lines
7.1 KiB
Markdown
131 lines
7.1 KiB
Markdown
# 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
|
|
silicon. Hardware-touching paths are marked `TODO(hw)`. Per `CLAUDE.md`, no
|
|
runtime or on-air claim is valid without a captured hardware log — none exists.
|
|
|
|
This is a **defensive-security, compliance-only** effort. Nothing here jams,
|
|
transmits into a band to deny it, or amplifies energy. The ESP32 either
|
|
*observes* the channel or *toggles the control pins of a passive external
|
|
surface*.
|
|
|
|
---
|
|
|
|
## The direct question: "can we use the ESP32 to scramble signals?"
|
|
|
|
**Short answer: not the way you probably mean, and yes in three narrow
|
|
supporting roles.**
|
|
|
|
The ESP32 **cannot shape its own transmitted 802.11 beamforming feedback.** 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
|
|
stack is a proprietary blob bound by a hardware NDA and third-party IP
|
|
licensing). There is **no ESP-IDF API to intercept, replace, or rotate the
|
|
compressed-BF-report the PHY emits.** `esp_wifi_80211_tx()` lets you inject raw
|
|
frames, but it is explicitly limited to *beacon, probe req/resp, (non-QoS) data,
|
|
and action* frames with the PHY choosing the actual precoding — it will not let
|
|
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 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 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 | 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 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** |
|
|
|
|
Bottom line: the ESP32 **cannot scramble its own WiFi beamforming feedback**, but
|
|
it **can** (a) tell an AP-side shield *when* to act, and (b) drive an **external
|
|
passive surface** that scrambles the channel in the *sensing* direction. The
|
|
latter is the only honest sense in which an ESP32 "helps scramble" a signal, and
|
|
it does so without the ESP32 emitting any RF of its own.
|
|
|
|
---
|
|
|
|
## The three legitimate roles
|
|
|
|
### 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* 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.
|
|
|
|
### 2. `veil_ris_controller/` — external RIS driver (the honest "help scramble")
|
|
Drives a **reconfigurable intelligent surface** over GPIO/SPI. Following the
|
|
PrivISAC pattern, each surface element has two phase states designed offline so
|
|
the array response is ~identical in the *communication* direction (throughput
|
|
preserved) but differs sharply in the *sensing* direction (an eavesdropper's
|
|
channel is perturbed). The ESP32 is just a keyed pin-driver; the surface is
|
|
**passive** (re-reflects ambient energy, adds none), which is what keeps this on
|
|
the compliant side of the jamming line. The switching **schedule is keyed** via
|
|
the portable core's `veil_rng` (SplitMix64), so an authorized sensor holding the
|
|
key can reconstruct and tolerate the schedule while an eavesdropper cannot.
|
|
|
|
### 3. `esp_wifi_80211_tx` action-frame signaling (minor)
|
|
Not a separate component. The trigger in role 1 could ride an action frame via
|
|
`esp_wifi_80211_tx` instead of GPIO/MQTT/ESP-NOW. Useful only as a transport for
|
|
the control signal — it does **not** touch beamforming feedback.
|
|
|
|
---
|
|
|
|
## Not recommended: decoy / cover-traffic
|
|
|
|
One could have the ESP32 emit extra frames (via `esp_wifi_80211_tx`) to inject
|
|
motion-like or clutter-like variation into an observer's CSI ("cover traffic").
|
|
**We do not implement this and do not recommend it.** It is (a) **legally
|
|
sensitive** — deliberately adding channel-occupying transmissions to degrade
|
|
another party's reception sits close to the *jamming* line and can violate
|
|
radio regulations depending on rate, power, and intent; and (b) **low-value** —
|
|
it costs airtime, harms your own network, and a determined observer can often
|
|
filter periodic decoys. It is documented here only so the option is explicitly
|
|
weighed and rejected in favor of the passive-RIS approach (role 2), which
|
|
perturbs the *sensing* direction without occupying spectrum.
|
|
|
|
---
|
|
|
|
## Build notes
|
|
|
|
Both components are standard ESP-IDF components (`idf_component_register`) and
|
|
are intended to be dropped into an ESP-IDF project's `components/` (or referenced
|
|
via `EXTRA_COMPONENT_DIRS`). `veil_ris_controller` compiles the portable core
|
|
(`../core/veil_shield.c`) directly to reuse `veil_rng`. They **build** as
|
|
skeletons; they do not run — every RF/GPIO/SPI/network path is a `TODO(hw)` stub.
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- ESP-IDF Wi-Fi API (`esp_wifi_80211_tx` supported frame types; CSI APIs):
|
|
<https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/network/esp_wifi.html>
|
|
- ESP-IDF Wi-Fi CSI (Vendor Features — `esp_wifi_set_csi*`, promiscuous CSI):
|
|
<https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/wifi-driver/wifi-vendor-features.html>
|
|
- ESP32-C6 beamforming-feedback limitations (IDFGH-15163):
|
|
<https://github.com/espressif/esp-idf/issues/15839>
|
|
- Closed Wi-Fi PHY blob (`esp-phy-lib`, object-only, NDA):
|
|
<https://github.com/espressif/esp-phy-lib>
|
|
- ESP32 Wi-Fi binary-blob reverse-engineering context (why the PHY is not modifiable):
|
|
<https://esp32-open-mac.be/posts/0005-the-road-ahead/>
|
|
- Raw 802.11 TX capability/limits reference (`esp32-80211-tx`):
|
|
<https://github.com/Jeija/esp32-80211-tx>
|
|
- PrivISAC — RIS-based privacy-preserving ISAC (sensing vs. comm direction):
|
|
<https://arxiv.org/abs/2601.04488>
|
|
- Wi-BFI — beamforming-feedback extraction (why unprotected BF reports leak):
|
|
<https://arxiv.org/pdf/2309.04408>
|