WebGateway
A WebGateway gives an HTTP API a SCION address. The API stays on TCP. The gateway in front of it accepts the connections over SCION. With a gateway, an app can use SCION for an API that does not support SCION itself. The gateway is part of Anapaya PathGuard.
The engine has two transports:
| Transport | Setting | On the wire |
|---|---|---|
| HTTP/3 | default | HTTP/3 over QUIC over SCION, to the origin |
| WebGateway | webGateway | HTTP/1.1 over TLS, in an HTTP/3 CONNECT tunnel over SCION, to a PathGuard WebGateway |
The Ktor client guide covers the first transport. This page covers the second.
Send the requests through a gateway
The sample app-testing has an API client that knows nothing about SCION, and the client that the
app ships with:
/** The API of the app. It knows nothing about SCION. */
class GreetingApi(private val client: HttpClient, private val baseUrl: String) {
suspend fun greet(name: String): String =
client.get("$baseUrl/greeting") { parameter("name", name) }.bodyAsText()
}
/** The client that the app ships with: the AA, and the WebGateway of the API. */
fun productionClient(apiKey: String): HttpClient = HttpClient(ScionHttp) {
engine {
tokenSource = ScionTokenSource.AnapayaAa(apiKey = apiKey)
webGateway = ScionWebGateway()
}
}
webGateway = ScionWebGateway() sends each request of this client through a gateway. For requests
over HTTP/3 to an origin, use a second client without webGateway.
How the engine finds the gateway
The gateway is transparent. The engine has no setting for the address of the gateway. The engine resolves the host of the request URL, and it expects the gateway at that SCION address. For a host behind a gateway, the TSAR record of the host holds the SCION address of the gateway.
The engine connects to port 443 of the gateway. To use a different port, set
ScionWebGateway(port = ...).
A host without a TSAR record
If the host has no TSAR record, call dnsOverride with the SCION address of the gateway. In this
example, the gateway has the SCION address 1-ff00:0:110,192.0.2.10, and the app sends its requests
to api.example.com:
val client = HttpClient(ScionHttp) {
engine {
tokenSource = ScionTokenSource.AnapayaAa(apiKey = key)
webGateway = ScionWebGateway()
dnsOverride("api.example.com", "1-ff00:0:110,192.0.2.10")
}
}
val response = client.get("https://api.example.com/accounts")
- The first argument is the host of the request URL. It is not a name of the gateway.
- The address has the form
<ISD>-<AS>,<IP>. Do not add brackets or a port. - Call
dnsOverrideonce for each host that the app sends through the gateway. All calls use the same gateway address.
The sample hello-scion does the same with its --gateway-address option:
if (arguments.gateway) {
webGateway = ScionWebGateway(port = arguments.gatewayPort)
}
arguments.gatewayAddress?.let { dnsOverride(Url(arguments.url).host, it) }
The tunnel
The engine opens the tunnel with CONNECT <request host>:<request port>. The gateway selects the
backend by that authority, and connects the tunnel to the backend over TCP.
The connection to the origin runs end to end in the tunnel:
- With an
httpsURL, TLS runs from the engine to the origin, so the gateway sees no plain text.caCertificatesPemand the platform verifier apply to this TLS session. - With an
httpURL, no TLS runs in the tunnel, and the gateway sees the HTTP requests. Usehttpfor tests only.
The engine does not check the certificate of the gateway. The TLS session in the tunnel authenticates the origin.
Test the gateway
ktor-client-scion-testing has a gateway in the test process. Testing your
app tests the sample above against an API on TCP.