broker

README

This is the Broker component of Snowflake.

Overview

The Broker handles the rendezvous by matching Snowflake Clients with Proxies, and passing their WebRTC Session Descriptions (the "signaling" step). This allows Clients and Proxies to establish a Peer connection.

It is analogous to Flashproxy's Facilitator, but bidirectional and domain-fronted.

The Broker expects:

• Clients to send their SDP offer in a POST request, which will then block until the Broker responds with the answer of the matched Proxy.
• Proxies to announce themselves with a POST request, to which the Broker responds with some Client's SDP offer. The Proxy should then send a second POST request soon after containing its SDP answer, which the Broker passes back to the same Client.

Running your own

The server uses TLS by default. 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 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.

In order to fetch certificates automatically, the server needs to open an additional HTTP listener on port 80. On Linux, you can use the setcap program, part of libcap2, to enable the broker to bind to low-numbered ports without having to run as root:

setcap 'cap_net_bind_service=+ep' /usr/local/bin/broker

You can control the listening broker port with the --addr option. Port 443 is the default.

You'll need to provide the URL of the custom broker to the client plugin using the --url $URL flag.

Documentation

Overview

Broker acts as the HTTP signaling channel. It matches clients and snowflake proxies by passing corresponding SessionDescriptions in order to negotiate a WebRTC connection.

This code is for loading database data that maps ip addresses to countries for collecting and presenting statistics on snowflake use that might alert us to censorship events.

The functions here are heavily based off of how tor maintains and searches their geoip database

The tables used for geoip data must be structured as follows:

Recognized line format for IPv4 is:

INTIPLOW,INTIPHIGH,CC
    where INTIPLOW and INTIPHIGH are IPv4 addresses encoded as big-endian 4-byte unsigned
    integers, and CC is a country code.

Note that the IPv4 line format

"INTIPLOW","INTIPHIGH","CC","CC3","COUNTRY NAME"

is not currently supported.

Recognized line format for IPv6 is:

IPV6LOW,IPV6HIGH,CC
    where IPV6LOW and IPV6HIGH are IPv6 addresses and CC is a country code.

It also recognizes, and skips over, blank lines and lines that start with '#' (comments).