DocsGuidesTLS passthrough

TLS passthrough

ngstone portends TLS at the edge with the edge's wildcard certificate, then forwards plain HTTP to your app. ngstone tlsdoes the opposite: the edge never decrypts traffic for a passthrough connection. It reads only the hostname the client asked for, then hands the encrypted connection to your local service, which runs the TLS handshake with its own certificate. An HTTPS request that reaches the edge's own TLS for that hostname (for example on a reused or domain-fronted connection) gets 421 and is never forwarded.

When to use it#

  • The service needs mutual TLS and must see the client certificate.
  • Clients pin your certificate, or you need a specific CA or EV certificate.
  • The protocol inside TLS isn't HTTP (IMAPS, LDAPS, a custom TLS protocol).
  • The edge must never see the plaintext.

Basic usage#

$ ngstone tls 8443 --subdomain secure
tls://secure.example.com -> 127.0.0.1:8443

Clients connect to the edge on port 443 as usual:

$ openssl s_client -connect secure.example.com:443 -servername secure.example.com
$ curl https://secure.example.com/

The positional argument is a bare port, forwarded to 127.0.0.1:<port>, or a host:port target used as-is. Without --subdomain the edge picks a random name.

--subdomain, -sstring
Requested subdomain. Empty means server-assigned.
--allow-cidrstring
Comma-separated CIDRs allowed to reach the tunnel. Checked against the client address, or the PROXY protocol source when the edge is behind a trusted proxy.
--ttlduration
Stop the tunnel after a positive duration such as --ttl 2h.
--jsonbooldefault: false
Emit JSON Lines status events to stdout.

--server, --transport, --token, --insecure, --server-name, and --pin work as they do for ngstone tcp.

How routing works#

Every connection to the edge's public port starts with a peek at the TLS ClientHello. The peek is limited to 16 KiB and to the edge's read-header timeout, and it doesn't consume the bytes. A ClientHello larger than that is closed. If the SNI hostname belongs to a tls tunnel, the edge opens a stream to your agent, replays the ClientHello, and copies bytes both ways. The agent dials your local service and does the same.

Anything else (another hostname, no SNI, or a connection that isn't TLS) continues to the normal TLS-terminating path exactly as before. HTTP tunnels and the agent's WebSocket control fallback share port 443 with passthrough tunnels.

Certificates#

Your service needs a certificate for the public hostname

Clients verify the certificate against the name they dialed, such as secure.example.com, not localhost. The edge's wildcard certificate is never used for a tls tunnel, so the local service must present a certificate for the tunnel hostname that your clients trust.

What applies and what doesn't#

Because the edge can't read the HTTP inside, it rejects --basic-auth, --host-header, --policy-file, --http2, and --multi-connector for tls tunnels. The request inspector shows no requests for them. Source-IP allowlists, per-IP rate and in-flight limits, PROXY protocol client addresses, and the TCP idle timeout all apply.

Project files#

In ngstone.json for ngstone up:

{
"tunnels": {
"secure": {
"kind": "tls",
"target": "8443",
"subdomain": "secure",
"allow_cidr": "203.0.113.0/24"
}
}
}

In ngstone.yml for ngstone start:

tunnels:
secure:
kind: tls
port: 8443
subdomain: secure

ngstone ps, JSON status output, and the inspector's tunnel list show the kind as tls.

Hostname conflicts#

A hostname is either an HTTP tunnel or a tls tunnel at a time. Binding one over a live tunnel of the other kind fails with kind_conflict, and the agent stops instead of retrying. Stop the other tunnel or choose another subdomain.