Security and TLS

Where TLS terminates

• Assigned Cruma hostnames (*.tun.cruma.io and *.*.tun.cruma.io): On paid plans with an active subscription, the agent attempts to obtain a certificate for its assigned hostname via ACME DNS-01 and take over TLS termination itself. Once the certificate is ready and the agent has notified the cloud service, TLS is terminated on the agent. If certificate issuance is unavailable, still in progress, or fails for any reason, TLS falls back to the Cruma ingress using Cruma-managed certificates.
• Custom CNAME hostnames: TLS is terminated on your agent using a certificate automatically obtained via ACME TLS-ALPN-01 (Let's Encrypt). Cruma infrastructure never sees the plaintext payload for these hostnames — it only forwards the encrypted TLS stream to your agent, which terminates it locally. It is possible to terminate TLS differently for these if you want to use a specific cert or other ACME modes.
• Local TLS listeners: You can choose between self-signed certificates (good for local development) or ACME TLS-ALPN-01 (requires port 443 reachable from the internet). See Configuration for details.

TCP and raw backends

The backend kind affects what happens after TLS termination:

	Assigned Cruma hostname	CNAME'd custom domain
tcp	Agent terminates TLS when the assigned-hostname certificate is ready; otherwise Cruma ingress terminates TLS. Backend always receives plain TCP.	Agent terminates TLS (ALPN-01) → plain TCP to backend
raw	If the assigned hostname is agent-terminated, the agent terminates TLS and the backend receives plain TCP. If not, Cruma ingress terminates TLS and the backend still receives plain TCP.	Cruma forwards the encrypted TLS stream → agent passes it through untouched → backend handles TLS

Key takeaway: raw only provides true end-to-end TLS pass-through (where the backend terminates TLS itself) when using a CNAME'd custom domain. With assigned Cruma hostnames, TLS is still terminated before the backend, either on the agent or at the Cruma ingress, so raw and tcp both result in plain TCP at the backend.

What we can see

• Assigned Cruma hostnames: Visibility depends on where TLS terminates for that hostname. If the agent has successfully provisioned its assigned-hostname certificate and is actively terminating TLS, Cruma only forwards the encrypted stream. If the hostname is still using fallback ingress termination, payloads are technically accessible to Cruma infrastructure. Today we only handle what's needed for routing and telemetry (e.g., request counts, health checks) and do not run MITM or payload-inspection features. If we ever add a feature that needs payload inspection, it would be explicitly opt-in.
• Custom CNAME hostnames: Cruma sees only control-plane metadata (tunnel ID, target types, health/connection status) plus request/byte counts for abuse prevention. Because TLS terminates on your agent via ACME TLS-ALPN-01, payloads remain end-to-end encrypted between the client and your agent.

Assigned-hostname certificate flow

For eligible paid tunnels, the agent attempts to obtain a certificate for its assigned *.tun.cruma.io or *.*.tun.cruma.io hostname using ACME DNS-01. After the certificate is ready, the agent tells the cloud service that it is ready to terminate TLS locally.

If that process cannot complete, traffic continues to work with the normal fallback: the Cruma ingress terminates TLS using Cruma-managed certificates.

The GUI shows the current state of this handoff on the Certificates page so you can see whether the assigned hostname is agent-terminated or still using cloud termination.

How custom-domain TLS works

When you CNAME a custom hostname to your tunnel FQDN, the agent automatically provisions a Let's Encrypt certificate using the ACME TLS-ALPN-01 challenge. This happens transparently — you don't need to configure certificates manually. The Cruma ingress routes the raw TLS connection to your agent, which presents the certificate and terminates TLS locally.

This means:

• Clients connect with a valid, publicly trusted certificate.
• The payload is encrypted end-to-end between the client and your agent.
• Cruma infrastructure forwards the encrypted stream but cannot decrypt it.

Inspection and opt-in

• Ingress-terminated traffic can be inspected in principle because TLS ends on Cruma. No payload inspection is performed today beyond what's required to operate the service; any future feature needing payload visibility would be opt-in.
• For custom CNAME hostnames, your agent terminates TLS and Cruma cannot inspect payloads. For additional hardening, see the CAA and pinning options below.

Hardening options (custom domains)

The automatic ACME TLS-ALPN-01 issuance on your agent already provides strong end-to-end encryption for custom domains. The options below are for users who want additional guarantees.

CAA records (restrict certificate issuance)

Set CAA records on your custom domain to restrict which Certificate Authority can issue certificates for it. This prevents anyone (including Cruma infrastructure) from obtaining a certificate for your hostname through a different CA or ACME account.

Example — permit only Let's Encrypt:

app.yourdomain.com.  CAA 0 issue "letsencrypt.org"

For tighter control, use accounturi to limit issuance to your agent's specific ACME account:

app.yourdomain.com.  CAA 0 issue "letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/<your-acct-id>"

See Let's Encrypt CAA docs and Cloudflare's CAA overview for more details.

Certificate pinning / mTLS

If your security model requires it, you can pin the certificate your agent presents for custom hostnames. Clients will reject any different certificate, preventing a silent MITM even if someone were to obtain a valid cert for your domain through another path. Pinning is advanced and makes certificate rotation more complex — use it only when your threat model demands it.

Combine CAA with pinning (or mTLS) for the strongest guarantees: CAA restricts who can issue a certificate, and pinning ensures clients only accept the specific certificate your agent presents.

How this compares

• Assigned hostnames: Cruma can fall back to provider-edge termination for assigned *.tun.cruma.io hostnames, similar to Cloudflare, ngrok, and similar services for their default domains. On eligible paid tunnels, the preferred path is now agent-side termination once the assigned-hostname certificate is ready.
• Custom hostnames: Terminating TLS on the agent via ACME TLS-ALPN-01 provides true end-to-end encryption by default — no manual certificate setup needed. This is stronger than providers that terminate custom-domain TLS at their edge. For additional hardening, layer on CAA and/or pinning.