mirror of
https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
synced 2025-10-14 14:11:23 -04:00
182 lines
4.3 KiB
Text
182 lines
4.3 KiB
Text
|
|
|
|
Snowflake broker protocol
|
|
|
|
0. Scope and Preliminaries
|
|
|
|
The Snowflake broker is used to hand out Snowflake proxies to clients using the Snowflake pluggable transport. There are some similarities to the function of the broker and how BridgeDB hands out Tor bridges.
|
|
|
|
This document specifies how the Snowflake broker interacts with other parts of the Tor ecosystem, starting with the metrics CollecTor module and to be expanded upon later.
|
|
|
|
1. Metrics Reporting (version 1.0)
|
|
|
|
Metrics data from the Snowflake broker can be retrieved by sending an HTTP GET request to https://[Snowflake broker URL]/metrics and consists of the following items:
|
|
|
|
"snowflake-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
|
|
[At start, exactly once.]
|
|
|
|
YYYY-MM-DD HH:MM:SS defines the end of the included measurement
|
|
interval of length NSEC seconds (86400 seconds by default).
|
|
|
|
"snowflake-ips" [CC=NUM,CC=NUM,...,CC=NUM] NL
|
|
[At most once.]
|
|
|
|
List of mappings from two-letter country codes to the number of
|
|
unique IP addresses of Snowflake proxies that have polled. Each
|
|
country code only appears once.
|
|
|
|
"snowflake-ips-total" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the total number of unique IP addresses of Snowflake
|
|
proxies that have polled.
|
|
|
|
"snowflake-ips-standalone" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the total number of unique IP addresses of snowflake
|
|
proxies of type "standalone" that have polled.
|
|
|
|
"snowflake-ips-badge" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the total number of unique IP addresses of snowflake
|
|
proxies of type "badge" that have polled.
|
|
|
|
"snowflake-ips-webext" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the total number of unique IP addresses of snowflake
|
|
proxies of type "webext" that have polled.
|
|
|
|
"snowflake-idle-count" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the number of times a proxy has polled but received
|
|
no client offer, rounded up to the nearest multiple of 8.
|
|
|
|
"client-denied-count" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the number of times a client has requested a proxy
|
|
from the broker but no proxies were available, rounded up to
|
|
the nearest multiple of 8.
|
|
|
|
"client-snowflake-match-count" NUM NL
|
|
[At most once.]
|
|
|
|
A count of the number of times a client successfully received a
|
|
proxy from the broker, rounded up to the nearest multiple of 8.
|
|
|
|
2. Broker messaging specification and endpoints
|
|
|
|
The broker facilitates the connection of snowflake clients and snowflake proxies
|
|
through the exchange of WebRTC SDP information with its endpoints.
|
|
|
|
2.1. Client interactions with the broker
|
|
|
|
Clients interact with the broker by making a POST request to `/client` with the
|
|
offer SDP in the request body:
|
|
```
|
|
POST /client HTTP
|
|
|
|
[offer SDP]
|
|
```
|
|
If the broker is behind a domain-fronted connection, this request is accompanied
|
|
with the necessary HOST information.
|
|
|
|
If the client is matched up with a proxy, they receive a 200 OK response with
|
|
the proxy's answer SDP in the request body:
|
|
```
|
|
HTTP 200 OK
|
|
|
|
[answer SDP]
|
|
```
|
|
|
|
If no proxies were available, they receive a 503 status code:
|
|
```
|
|
HTTP 503 Service Unavailable
|
|
```
|
|
|
|
|
|
2.2 Proxy interactions with the broker
|
|
|
|
Proxies poll the broker with a proxy poll request to `/proxy`:
|
|
|
|
```
|
|
POST /proxy HTTP
|
|
|
|
{
|
|
Sid: [generated session id of proxy],
|
|
Version: 1.1,
|
|
Type: ["badge"|"webext"|"standalone"|"mobile"]
|
|
}
|
|
```
|
|
|
|
If the request is well-formed, they receive a 200 OK response.
|
|
|
|
If a client is matched:
|
|
```
|
|
HTTP 200 OK
|
|
|
|
{
|
|
Status: "client match",
|
|
{
|
|
type: offer,
|
|
sdp: [WebRTC SDP]
|
|
}
|
|
}
|
|
```
|
|
|
|
If a client is not matched:
|
|
```
|
|
HTTP 200 OK
|
|
|
|
{
|
|
Status: "no match"
|
|
}
|
|
```
|
|
|
|
If the request is malformed:
|
|
```
|
|
HTTP 400 BadRequest
|
|
```
|
|
|
|
If they are matched with a client, they provide their SDP answer with a POST
|
|
request to `/answer`:
|
|
```
|
|
POST /answer HTTP
|
|
|
|
{
|
|
Sid: [generated session id of proxy],
|
|
Version: 1.1,
|
|
Answer:
|
|
{
|
|
type: answer,
|
|
sdp: [WebRTC SDP]
|
|
}
|
|
}
|
|
```
|
|
|
|
If the request is well-formed, they receive a 200 OK response.
|
|
|
|
If the client retrieved the answer:
|
|
```
|
|
HTTP 200 OK
|
|
|
|
{
|
|
Status: "success"
|
|
}
|
|
```
|
|
|
|
If the client left:
|
|
```
|
|
HTTP 200 OK
|
|
|
|
{
|
|
Status: "client gone"
|
|
}
|
|
|
|
3) If the request is malformed:
|
|
HTTP 400 BadRequest
|
|
```
|