snowflake/README.md

Snowflake

A Pluggable Transport using WebRTC

Table of Contents

• Status
• Usage
  • Dependencies
  • More Info
  • Building a Snowflake
• Appendix
  • -- Testing directly via WebRTC Server --
  • -- Via Browser Proxy --

Status

Successfully & automatically bootstraps with a WebRTC transport, using HTTP signaling (with optional domain fronting) speaking to a multitude of volunteer "snowflakes". Still lots of work to do.

Usage

cd client/
go get
go build
tor -f torrc

This should start the client plugin, bootstrapping to 100% using WebRTC.

Dependencies

Client:

• go-webrtc.
• Go 1.5.* (1.6 is not yet supported. See Issue #22)

Proxy:

• CoffeeScript

---

More Info

The client uses the following torrc options:

ClientTransportPlugin snowflake exec ./client \
-url https://snowflake-reg.appspot.com/ \
-front www.google.com \
-ice stun:stun.l.google.com:19302

Which allows it to speak to the Broker, get matched with a "snowflake" browser proxy, and negotiate a WebRTC PeerConnection.

To see logs, do tail -F snowflake.log in a second terminal.

You can modify the torrc to use your own broker, or remove the options entirely which will default to the old copy paste method (see torrc-manual):

ClientTransportPlugin snowflake exec ./client --meek

Also, it is possible to connect directly to the go-webrtc server plugin (skipping all the browser snowflake / broker stuff - see appendix)

Building a Snowflake

This will only work if there are any browser snowflakes running at all. To run your own, first make sure coffeescript is installed. Then, build with:

cd proxy/
cake build

(Type cake by itself to see possible commands)

Then, start a local http server in the proxy/build/ in any way you like. For instance:

cd build/
python -m http.server

Then, open a browser tab to 0.0.0.0:8000/snowflake.html, which causes you to act as an ephemeral Tor bridge.

Appendix

-- Testing directly via WebRTC Server --

Ordinarily, the WebrTC client plugin speaks with a Broker which helps match and signal with a browser proxy, which ultimately speaks with a default websocket server.

However, there is a WebRTC server plugin which uses an HTTP server that simulates the interaction that a client would have with the broker, for direct testing.

Edit server/torrc and add "-http 127.0.0.1:8080" to the end of the ServerTransportPlugin line:

ServerTransportPlugin snowflake exec ./server -http 127.0.0.1:8080

cd server/
go build
tor -f torrc

Edit client/torrc and add "-url http://127.0.0.1:8080" to the end of the ClientTransportPlugin line:

ClientTransportPlugin snowflake exec ./client -url http://127.0.0.1:8080/

-- Testing Copy-Paste Via Browser Proxy --

Open up three terminals for the client:

A: tor -f torrc-manual SOCKSPort auto

B: cat > signal

C: tail -F snowflake.log

Then, in the browser proxy:

• Look for the offer in terminal C; copy and paste it into the browser.
• Copy and paste the answer generated in the browser back to terminal B.
• Once WebRTC successfully connects, the browser terminal should turn green. Shortly after, the tor client should bootstrap to 100%.

More documentation on the way.

Also available at: torproject.org/pluggable-transports/snowflake