How keroserene/snowflake works
Project Type and Purpose
• Snowflake is a pluggable transport system for Tor, built in Go.
• It consists of these main pieces:
a. Broker: a domain-fronted signaling server that matches Tor clients with volunteer proxies.
b. Client: a Tor pluggable transport client library and binary that initiates WebRTC connections via the Broker.
c. Proxy: volunteers’ Snowflake proxies (browser or standalone Go) that accept WebRTC connections, proxy traffic into Tor.
d. Server: Tor pluggable transport server code for turn-style relaying of WebRTC traffic to the Tor network.
e. Common libraries: shared components (AMP framing, rendezvous, NAT handling, metrics, etc.)
f. Probetest (optional): a containerized NAT probing service used in tests.
Main Components and Their Interactions
• Tor Client (pluggable-transport client)
• Reads torrc, loads the client binary.
• Connects over HTTPS (domain-fronted) to the Broker’s HTTP API to fetch proxy offers.
• Initiates WebRTC ICE negotiation with a volunteer Proxy.
• Once the DataChannel is open, tunnels Tor cell data over WebRTC.
• Broker
• Exposes HTTP(S) endpoints using domain fronting.
• Maintains in-memory peer lists (bridge-list.go).
• Handles AMP-framed requests (amp.go) and plain HTTP rendezvous (http.go).
• Exposes Prometheus metrics.
• Volunteer Proxy (browser or Go binary)
• Registers with Broker by sending “I’m available” messages.
• Listens for ICE offers from Tor clients via the Broker.
• On WebRTC DataChannel establishment, proxies traffic to a Tor relay or a built-in Tor client.
• Tor Pluggable-Transport Server
• Listens for incoming WebRTC DataChannels from proxies.
• Acts as the final hop into the Tor network.
• Common Libraries
• AMP framing, rendezvous protocols, NAT utilities, turbotunnel queueing, metrics, encapsulation.
• Shared by broker, client, proxy, and server.
• (Optional) Probetest
• Dockerized service to test NAT traversal, used only for development/test rigs.
Architectural Patterns and Design Principles
• Microservice-like separation: each role (broker, client, proxy, server) is a standalone Go module.
• Shared “common” code to avoid duplication of transport logic, framing, and utilities.
• Clean separation of signaling (Broker/HTTP+AMP) vs. data plane (WebRTC DataChannels).
• Instrumentation: Prometheus metrics in Broker and server.
• Testing: each component has unit tests under its folder; integration tests in “probetest.”
Detailed Elements
• Clear labels: e.g., “Broker HTTP API (domain-fronted), port 443”
• Protocol annotations: “WebRTC ICE Negotiation,” “DataChannel (DTLS/SCTP)”
• On metrics export endpoints (Broker → /metrics)