Tor Gateway

The Tor Gateway is a small always-on computer (for example a Raspberry Pi or VPS) that bridges the ESP32 devices to the Tor network.

The ESP32 itself cannot run Tor. It does not have enough memory, storage, or a full TCP/IP stack capable of handling Tor’s circuit building, directory fetches, and encryption layers.
For this reason every DeadLetter device must talk to a trusted gateway which then forwards traffic into Tor.

Why a Gateway is Required

The ESP32 firmware is intentionally minimal:

  • No Tor binary on the device
  • No SOCKS implementation
  • No directory consensus parsing
  • No onion address resolution

Instead, the ESP32 only performs:

  • Key generation
  • Encryption / decryption
  • Trust fingerprint display
  • Plain HTTP communication to the gateway

All Tor-specific logic lives on the gateway.

Gateway Responsibilities

The gateway is responsible for:

  • Running Tor in client mode
  • Exposing a local HTTP service for the ESP32
  • Forwarding all traffic through Tor using a SOCKS proxy
  • Resolving .onion registry and backend addresses
  • Acting as a privacy boundary between the device and the public internet

The flow is:

ESP32  →  Gateway (HTTP)  →  Tor (SOCKS)  →  Onion Registry / Backend

Example Setup: Raspberry Pi Gateway

A Raspberry Pi running Debian is sufficient.

Install Tor:

sudo apt update
sudo apt install tor socat

Verify Tor is running:

sudo ss -lntp | grep 9050

You should see Tor listening on 127.0.0.1:9050.

Forwarding via socat

The gateway exposes a local port that forwards traffic into Tor:

socat TCP-LISTEN:8080,reuseaddr,fork SOCKS4A:127.0.0.1:REGISTRY_ONION.onion:80,socksport=9050

This means:

  • ESP32 connects to http://gateway-ip:8080
  • socat forwards the traffic through Tor to the hidden service

You can run multiple listeners for backend and registry.

Current Limitation

At the moment the gateway hardcodes the onion addresses inside the systemd service files.

This means:

  • Onion URLs cannot yet be updated dynamically
  • Changing backend or registry onion requires editing the gateway config and restarting services

This is a known limitation and will be improved in future versions.

Trust Boundary

The gateway is trusted for transport only, not for message confidentiality.

  • Messages are always end-to-end encrypted between sender and receiver
  • The gateway cannot decrypt message payloads
  • Fingerprint verification still happens on the ESP32 device itself

If a gateway is compromised, the attacker can observe traffic patterns but cannot read message contents.