README
¶
Snowflake
Pluggable Transport using WebRTC, inspired by Flashproxy.
Table of Contents
Structure of this Repository
broker/contains code for the Snowflake brokerdoc/contains Snowflake documentation and manpagesclient/contains the Tor pluggable transport client and client library codecommon/contains generic libraries used by multiple pieces of Snowflakeproxy/contains code for the Go standalone Snowflake proxyprobetest/contains code for a NAT probetesting serviceserver/contains the Tor pluggable transport server and server library code
Usage
Snowflake is currently deployed as a pluggable transport for Tor.
Using Snowflake with Tor
To use the Snowflake client with Tor, you will need to add the appropriate Bridge and ClientTransportPlugin lines to your torrc file. See the client README for more information on building and running the Snowflake client.
Running a Snowflake Proxy
You can contribute to Snowflake by running a Snowflake proxy. We have the option to run a proxy in your browser or as a standalone Go program. See our community documentation for more details.
Using the Snowflake Library with Other Applications
Snowflake can be used as a Go API, and adheres to the v2.1 pluggable transports specification. For more information on using the Snowflake Go library, see the Snowflake library documentation.
Test Environment
There is a Docker-based test environment at https://github.com/cohosh/snowbox.
FAQ
Q: How does it work?
In the Tor use-case:
- Volunteers visit websites which host the "snowflake" proxy. (just like flashproxy)
- Tor clients automatically find available browser proxies via the Broker (the domain fronted signaling channel).
- Tor client and browser proxy establish a WebRTC peer connection.
- Proxy connects to some relay.
- Tor occurs.
More detailed information about how clients, snowflake proxies, and the Broker fit together on the way...
Q: What are the benefits of this PT compared with other PTs?
Snowflake combines the advantages of flashproxy and meek. Primarily:
-
It has the convenience of Meek, but can support magnitudes more users with negligible CDN costs. (Domain fronting is only used for brief signalling / NAT-piercing to setup the P2P WebRTC DataChannels which handle the actual traffic.)
-
Arbitrarily high numbers of volunteer proxies are possible like in flashproxy, but NATs are no longer a usability barrier - no need for manual port forwarding!
Q: Why is this called Snowflake?
It utilizes the "ICE" negotiation via WebRTC, and also involves a great abundance of ephemeral and short-lived (and special!) volunteer proxies...
More info and links
We have more documentation in the Snowflake wiki and at https://snowflake.torproject.org/.
Using gomobile it is possible to build snowflake as shared libraries for all
the architectures supported by Android. This is in the .gitlab-ci.yml, which
runs in GitLab CI. It is also possible to run this setup in a Virtual Machine
using vagrant. Just run vagrant up and it will
create and provision the VM. vagrant ssh to get into the VM to use it as a
development environment.
Directories
¶
| Path | Synopsis |
|---|---|
|
Broker acts as the HTTP signaling channel.
|
Broker acts as the HTTP signaling channel. |
|
Client transport plugin for the Snowflake pluggable transport.
|
Client transport plugin for the Snowflake pluggable transport. |
|
lib
Package snowflake_client implements functionality necessary for a client to establish a connection to a server using Snowflake.
|
Package snowflake_client implements functionality necessary for a client to establish a connection to a server using Snowflake. |
|
common
|
|
|
amp
Package amp provides functions for working with the AMP (Accelerated Mobile Pages) subset of HTML, and conveying binary data through an AMP cache.
|
Package amp provides functions for working with the AMP (Accelerated Mobile Pages) subset of HTML, and conveying binary data through an AMP cache. |
|
encapsulation
Package encapsulation implements a way of encoding variable-size chunks of data and padding into a byte stream.
|
Package encapsulation implements a way of encoding variable-size chunks of data and padding into a byte stream. |
|
messages
import "git.torproject.org/pluggable-transports/snowflake.git/v2/common/messages"
|
import "git.torproject.org/pluggable-transports/snowflake.git/v2/common/messages" |
|
safelog
import "git.torproject.org/pluggable-transports/snowflake.git/v2/common/safelog"
|
import "git.torproject.org/pluggable-transports/snowflake.git/v2/common/safelog" |
|
task
Package task Reused from https://github.com/v2fly/v2ray-core/blob/784775f68922f07d40c9eead63015b2026af2ade/common/task/periodic.go
|
Package task Reused from https://github.com/v2fly/v2ray-core/blob/784775f68922f07d40c9eead63015b2026af2ade/common/task/periodic.go |
|
turbotunnel
Package turbotunnel provides support for overlaying a virtual net.PacketConn on some other network carrier.
|
Package turbotunnel provides support for overlaying a virtual net.PacketConn on some other network carrier. |
|
Probe test server to check the reachability of Snowflake proxies from clients with symmetric NATs.
|
Probe test server to check the reachability of Snowflake proxies from clients with symmetric NATs. |
|
lib
Package snowflake_proxy provides functionality for creating, starting, and stopping a snowflake proxy.
|
Package snowflake_proxy provides functionality for creating, starting, and stopping a snowflake proxy. |
|
Snowflake-specific websocket server plugin.
|
Snowflake-specific websocket server plugin. |
|
lib
Package snowflake_server implements the functionality necessary to accept Snowflake connections from Snowflake clients.
|
Package snowflake_server implements the functionality necessary to accept Snowflake connections from Snowflake clients. |