archives/snowflake
2
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git synced 2025-10-13 11:11:30 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

README and documentation for server.

Browse source
This commit is contained in:
David Fifield 2017-01-21 14:53:09 -08:00
parent 1f8be86a01
commit a936fc7e9b
3 changed files with 68 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

62
server/README.md Normal file
View file

@ -0,0 +1,62 @@
This is the server transport plugin for Snowflake.
The actual transport protocol it uses is
[WebSocket](https://tools.ietf.org/html/rfc6455).
In Snowflake, the client connects to the proxy using WebRTC,
and the proxy connects to the server (this program) using WebSocket.
# Setup
The server needs to be able to listen on port 443
in order to generate its TLS certificates.
On Linux, use the `setcap` program to enable
the server to listen on port 443 without running as root:
```
setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
```
Here is a short example of configuring your torrc file
to run the Snowflake server under Tor:
```
SocksPort 0
ORPort 9001
ExtORPort auto
BridgeRelay 1
ServerTransportListenAddr snowflake 0.0.0.0:443
ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin@snowflake.example --log /var/log/tor/snowflake-server.log
```
The domain names given to the `--acme-hostnames` option
should resolve to the IP address of the server.
You can give more than one, separated by commas.
# TLS
The server uses TLS WebSockets by default: wss:// not ws://.
There is a `--disable-tls` option for testing purposes,
but you should use TLS in production.
The server automatically fetches certificates
from [Let's Encrypt](https://en.wikipedia.org/wiki/Let's_Encrypt) as needed.
Use the `--acme-hostnames` option to tell the server
what hostnames it may request certificates for.
You can optionally provide a contact email address,
using the `--acme-email` option,
so that Let's Encrypt can inform you of any problems.
The server will cache TLS certificate data in the directory
`pt_state/snowflake-certificate-cache` inside the tor state directory.
In order to fetch certificates automatically,
the server needs to listen on port 443.
This is a requirement of the ACME protocol used by Let's Encrypt.
If your `ServerTransportListenAddr` is not on port 443,
the server will open an listener on port 443 in addition
to the port you requested.
The program will exit if it can't bind to port 443.
On Linux, you can use the `setcap` program,
part of libcap2, to enable the server to bind to low-numbered ports
without having to run as root:
```
setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
```

11
server/server.go
View file

@ -1,11 +1,6 @@
// Snowflake-specific websocket server plugin. This is the same as the websocket
// server used by flash proxy, except that it reports the transport name as
// "snowflake" and does not forward the remote address to the ExtORPort.
//
// Usage in torrc:
// ExtORPort auto
// ServerTransportListenAddr snowflake 0.0.0.0:9902
// ServerTransportPlugin snowflake exec server
// Snowflake-specific websocket server plugin. It reports the transport name as
// "snowflake" and does not forward the (unknown) client address to the
// ExtORPort.
package main
import (

8
server/torrc
View file

@ -1,9 +1,7 @@
BridgeRelay 1
SocksPort 0
ORPort 9001
ExtORPort auto
SocksPort 0
ExitPolicy reject *:*
DataDirectory datadir
BridgeRelay 1
ServerTransportListenAddr snowflake 0.0.0.0:443
ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin@snowflake.example --log snowflake.log
ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin@snowflake.example --log /var/log/tor/snowflake-server.log