Skip to main content
The gateway runs in your network and holds your connection strings. Rows, results and connection strings stay there: how it works lists what goes up to Midplane Cloud, and linked mode has every detail. Agents reach the gateway at your own URL, or at a Midplane URL through the relay, below.

​
The relay

A gateway behind the relay connects out to the relay of its region, relay.eu.midplane.app in the EU, and keeps a few connections open there, which it authenticates with the token it uses with Midplane Cloud. Setup learns the relay’s name from Midplane Cloud in an answer signed with the key the enrollment token pins (0.26.1+; earlier gateways take it on TLS alone), so a proxy that intercepts TLS can’t point the gateway at another relay. An agent connects to the gateway’s Midplane URL, such as gw-7hq2m4xd.eu.midplane.app, which points at the relay. The relay reads only the name the agent asks for in its TLS handshake, then passes the still-encrypted bytes, unread, over one of that gateway’s connections. TLS ends at the gateway, with a certificate it got from Let’s Encrypt for a key that never leaves its disk. Each connection serves only its own gateway’s name.

​
What the relay sees

  • Host names: the gateway’s Midplane URL, as each agent asks for it.
  • Addresses: each agent’s IP address and port, and the gateway’s.
  • Timing and byte counts: when each connection opens and closes, and how many bytes cross it each way.
  • The gateway’s token, which it checks as Midplane Cloud itself does.
  • Let’s Encrypt’s checks of the gateway’s name on port 80: a request for a token whose answer is public by design. Nothing else on port 80 reaches the gateway.
The relay logs these, never a byte of a connection, and passes each agent’s address to the gateway ahead of its bytes, so the gateway sees the agent as the client rather than the relay.

​
What the relay cannot see

Anything inside TLS: the agent’s requests and its access token, your SQL and its results, and every response the gateway sends. The relay doesn’t hold a key or a certificate for any gateway’s name, and has no way to decrypt the traffic it passes. “Midplane Cloud never sees a row” holds for a gateway behind the relay as for one at your own URL. The one certificate the relay holds is its own, for relay.eu.midplane.app, which it gets from Let’s Encrypt as a gateway does. It serves it only to gateways opening their connections; an agent’s connection to a gateway’s name never ends there.

​
Revoking a gateway behind the relay

Revoking a gateway closes its connections to the relay within 10 seconds, so agents can’t reach it at its Midplane URL from then on, even while its process runs. No other gateway ever gets that URL, even after the gateway is revoked or its organization deleted: agents that have it are never sent to another gateway, and no other gateway can get a certificate for the name through the relay.

​
Who could get a certificate for your gateway

Midplane controls the DNS of midplane.app, where Midplane URLs are. So Midplane could get a certificate for your gateway’s name from a public certificate authority, point the name at a server of its own, and read what agents send there. Nothing in the protocol prevents that. Every publicly trusted certificate is published in Certificate Transparency logs, so such a certificate would be visible, but only after it was issued. The CAA records of eu.midplane.app allow Let’s Encrypt only, by its HTTP challenge, and no wildcard certificate, so any certificate that covers your gateway’s name lists that name, and a Certificate Transparency search for it finds the certificate (dig CAA eu.midplane.app shows the records); Midplane controls those records too. To have no Midplane component that could do this, give the gateway your own URL.

​
Watch Certificate Transparency logs

Look your gateway’s name up on crt.sh, such as https://crt.sh/?q=gw-7hq2m4xd.eu.midplane.app. It lists every certificate logged for the name, usually twice each (a precertificate and the certificate). Each should be one your gateway got: its log says certificate obtained, or certificate renewed about 60 days later, with valid_until, the certificate’s Not After. To check the one it serves now:
A certificate for the name that your gateway didn’t log is one it didn’t request. To be told rather than look, check crt.sh’s JSON (https://crt.sh/?q=gw-7hq2m4xd.eu.midplane.app&output=json, with each certificate’s serial_number, not_before and not_after) from a scheduled job, or add the name to a Certificate Transparency monitor.

​
When the relay is down

Agents can’t reach a gateway behind the relay, and nothing else reaches it: there is no other way in. The gateway keeps enforcing your policies, keeps its link to Midplane Cloud, which doesn’t go through the relay, and tries to reconnect, waiting from 1 second up to a minute between tries. Once the relay is back, agents’ next requests succeed with the tokens they have. The gateway renews its certificate through the relay, from 30 days before it expires, so an outage shorter than that costs no certificate. A gateway at your own URL doesn’t depend on the relay.

​
Reporting a vulnerability

See SECURITY.md on GitHub. Tested by the cloud’s relay tests: marker strings seeded in a query and in its result never appear in anything the relay holds or logs, and the relay creates no TLS server for any name but its own. A smoke test runs the relay from its image with the gateway’s, against Pebble, the test ACME server Let’s Encrypt publishes, in place of Let’s Encrypt itself.