commit a936fc7e9b0c3bf81b56e8a2c6815bca949c23a1 Author: David Fifield david@bamsoftware.com Date: Sat Jan 21 14:53:09 2017 -0800

README and documentation for server. --- server/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ server/server.go | 11 +++------- server/torrc | 8 +++----- 3 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..d0fd91d --- /dev/null +++ b/server/README.md @@ -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%27s_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 +``` diff --git a/server/server.go b/server/server.go index aec9b51..7229e06 100644 --- a/server/server.go +++ b/server/server.go @@ -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 ( diff --git a/server/torrc b/server/torrc index ed71a39..5dc2008 100644 --- a/server/torrc +++ b/server/torrc @@ -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