Security model#

Tollan's security rests on a few deliberate choices: devices dial out (no inbound attack surface), every tunnel is mutually authenticated with TLS, the relay is zero-knowledge for passthrough traffic, and configuration state is kept away from the traffic path.

No inbound surface#

Because agents make outbound connections and never listen, your device is not a target on the public internet. There is no open port to scan, no service to exploit remotely. The only connection is the one the device chose to make to the relay.

Mutual TLS identity#

Every agent↔relay tunnel is mutual TLS:

• The agent presents a client certificate issued by Tollan's CA. The relay verifies it against the CA before accepting the tunnel.
• The relay presents a server certificate. The agent pins it against the CA certificate it was provisioned with (ca.crt / CA_CERT).

Neither side trusts the network. A stolen device certificate is the only way to impersonate a device — which is why certificates are short-lived, rotatable, and revocable.

Device certificates use modern elliptic-curve cryptography and carry an identity that binds each certificate to exactly one device in one organization.

Provisioning: two ways to get a key#

Bundle mode — the control plane issues the device's key and certificate and packages them in the bundle. Fast for a single machine. The key is downloaded once and the control plane retains only what it needs to verify future renewals.

Enrollment mode — the device generates its own key on first boot and submits a CSR with a one-time enrollment token. The control plane verifies the token and signs the CSR. The private key never leaves the device. Preferred for fleets and high-assurance deployments.

Certificate lifecycle#

• Issue — the CA signs a device certificate with a short validity window (relay certificates get their own, longer window).
• Renew — agents renew automatically before expiry, proving possession of their private key (they sign a challenge like deviceId|ts with it). No operator action, no key transmission.
• Rotate — an operator revokes the active certificate and issues a fresh one (new key, one-time download). Use after suspected exposure.
• Revoke — an operator invalidates a device's certificates. The relay checks revocation status and drops the tunnel; the device can't reconnect until re-provisioned.

Revocation is enforced promptly, and the relay treats an uncertain certificate as untrusted rather than trusted.

Relay ↔ control plane#

In a split deployment the relay and control plane authenticate to each other over an authenticated, private channel that carries configuration, metrics, and certificate-status checks. It is designed to run on trusted infrastructure rather than the public internet. See self-hosting.

Zero-knowledge passthrough#

For hostname (SNI) routes, the relay routes on the SNI field of the TLS handshake — which is not part of the encrypted payload — and then forwards the encrypted stream untouched. Your service terminates TLS. The relay never holds a key that could decrypt your traffic and never sees plaintext.

If you opt into terminate mode (to enforce HTTP-layer access rules or use a custom domain with managed certificates), the relay terminates TLS at the edge using a certificate you control the issuance of, and forwards plaintext to the device over the tunnel. That's an explicit trade you make per route.

Target allowlist#

A forwarding agent — Go or ESP32 — only dials targets on an allowlist the operator controls. The relay can name a target in an OPEN frame, but the agent refuses anything not on its list. This means a compromised relay cannot pivot a device to arbitrary hosts on its LAN: naming a target and authorizing it are separate powers, held by different parties.

Edge access control#

On top of device authentication, you can gate who on the public side may use a route with access rules: IP allowlists, HTTP basic auth, OIDC, or client-certificate mTLS. These are enforced at the relay for terminate-mode routes.

Tenant isolation#

Every resource — device, route, certificate, metric — belongs to exactly one organization, and queries are scoped to the caller's org. Combined with per-org roles (admin / operator / viewer) and an immutable audit log, this keeps tenants' data and actions separate and reviewable.

Control-plane authentication#

• Operators sign in with a session (XSRF-protected) and optional TOTP two-factor.
• Devices prove possession of their key for renewal and target sync.
• Public endpoints (login, signup, password reset, enrollment) are rate-limited per IP, and password reset never reveals whether an address exists.

What this adds up to#