mirror of
https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
synced 2025-10-14 05:11:19 -04:00
162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
# Snowflake
|
|
|
|
[](https://travis-ci.org/keroserene/snowflake)
|
|
|
|
Pluggable Transport using WebRTC, inspired by Flashproxy.
|
|
|
|
### Status
|
|
|
|
- [x] Transport: Successfully connects using WebRTC.
|
|
- [x] Rendezvous: HTTP signaling (with optional domain fronting) to the Broker
|
|
arranges peer-to-peer connections with multitude of volunteer "snowflakes".
|
|
- [x] Client multiplexes remote snowflakes.
|
|
- [x] Can browse using Tor over Snowflake.
|
|
- [ ] Reproducible build with TBB.
|
|
|
|
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
**Table of Contents**
|
|
|
|
- [Usage](#usage)
|
|
- [Dependencies](#dependencies)
|
|
- [More Info](#more-info)
|
|
- [Building](#building)
|
|
- [Test Environment](#test-environment)
|
|
- [FAQ](#faq)
|
|
- [Appendix](#appendix)
|
|
- [-- Testing directly via WebRTC Server --](#---testing-directly-via-webrtc-server---)
|
|
|
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
|
|
### 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](https://github.com/keroserene/go-webrtc)
|
|
- Go 1.5+
|
|
|
|
Proxy:
|
|
- JavaScript
|
|
|
|
---
|
|
|
|
#### More Info
|
|
|
|
Tor can plug in the Snowflake client via a correctly configured `torrc`.
|
|
For example:
|
|
|
|
```
|
|
ClientTransportPlugin snowflake exec ./client \
|
|
-url https://snowflake-broker.azureedge.net/ \
|
|
-front ajax.aspnetcdn.com \
|
|
-ice stun:stun.l.google.com:19302
|
|
-max 3
|
|
```
|
|
|
|
The flags `-url` and `-front` allow the Snowflake client to speak to the Broker,
|
|
in order to get connected with some volunteer's browser proxy. `-ice` is a
|
|
comma-separated list of ICE servers, which are required for NAT traversal.
|
|
|
|
For logging, run `tail -F snowflake.log` in a second terminal.
|
|
|
|
You can modify the `torrc` to use your own broker:
|
|
|
|
```
|
|
ClientTransportPlugin snowflake exec ./client --meek
|
|
```
|
|
|
|
|
|
#### Building
|
|
|
|
This describes how to build the in-browser snowflake. For the client, see Usage,
|
|
above.
|
|
|
|
The client will only work if there are browser snowflakes available.
|
|
To run your own:
|
|
|
|
```
|
|
cd proxy/
|
|
npm run build
|
|
```
|
|
|
|
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 `http://127.0.0.1:8000/snowflake.html` to view
|
|
the debug-console of the snowflake.,
|
|
So long as that tab is open, you are an ephemeral Tor bridge.
|
|
|
|
|
|
#### 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:
|
|
|
|
1. Volunteers visit websites which host the "snowflake" proxy. (just
|
|
like flashproxy)
|
|
2. Tor clients automatically find available browser proxies via the Broker
|
|
(the domain fronted signaling channel).
|
|
3. Tor client and browser proxy establish a WebRTC peer connection.
|
|
4. Proxy connects to some relay.
|
|
5. 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...
|
|
|
|
### Appendix
|
|
|
|
##### -- Testing with Standalone Proxy --
|
|
|
|
```
|
|
cd proxy-go
|
|
go build
|
|
./proxy-go
|
|
```
|
|
|
|
##### -- Testing directly via WebRTC Server --
|
|
|
|
See server-webrtc/README.md for information on connecting directly to a
|
|
WebRTC server transport plugin, bypassing the Broker and browser proxy.
|
|
|
|
More documentation on the way.
|
|
|
|
Also available at:
|
|
[torproject.org/pluggable-transports/snowflake](https://gitweb.torproject.org/pluggable-transports/snowflake.git/)
|