npm:snowflake-pt

README

This is the browser proxy component of Snowflake.

Embedding

See https://snowflake.torproject.org/ for more info:

<iframe src="https://snowflake.torproject.org/embed.html" width="88" height="16" frameborder="0" scrolling="no"></iframe>

Building the badge / snowflake.torproject.org

npm install
npm run build

which outputs to the build/ directory.

Building the webextension

npm install
npm run webext

and then load the webext/ directory as an unpacked extension.

Testing

Unit testing with Jasmine are available with:

npm install
npm test

To run locally, start an http server in build/ and navigate to /embed.html.

Preparing to deploy

Background information:

You need to be in LDAP group "snowflake" and have set up an SSH key with your LDAP account. In your ~/.ssh/config file, you should have something like:

Host staticiforme
HostName staticiforme.torproject.org
User <your user name>
ProxyJump people.torproject.org
IdentityFile ~/.ssh/tor

Deploying

npm install
npm run build

Do a "dry run" rsync with -n to check that only expected files are being changed. If you don't understand why a file would be updated, you can add the -i option to see the reason.

rsync -n --chown=:snowflake --chmod ug=rw,D+x --perms --delete -crv build/ staticiforme:/srv/snowflake.torproject.org/htdocs/

If it looks good, then repeat the rsync without -n.

rsync --chown=:snowflake --chmod ug=rw,D+x --perms --delete -crv build/ staticiforme:/srv/snowflake.torproject.org/htdocs/

You can ignore errors of the form rsync: failed to set permissions on "<dirname>/": Operation not permitted (1).

Then run the command to copy the new files to the live web servers:

ssh staticiforme 'static-update-component snowflake.torproject.org'

Parameters

With no parameters, snowflake uses the default relay snowflake.freehaven.net:443 and uses automatic signaling with the default broker at https://snowflake-broker.freehaven.net/.

Reuse as a library

The badge and the webextension make use of the same underlying library and only differ in their UI. That same library can be produced for use with other interfaces, such as Cupcake, by running,

npm install
npm run library

which outputs a ./snowflake-library.js.

You'd then want to create a subclass of UI to perform various actions as the state of the snowflake changes,

class MyUI extends UI {
    ...
}

See WebExtUI in init-webext.js and BadgeUI in init-badge.js for examples.

Finally, initialize the snowflake with,

var log = function(msg) {
  return console.log('Snowflake: ' + msg);
};
var dbg = log;

var config = new Config("myui");  // NOTE: Set a unique proxy type for metrics
var ui = new MyUI();  // NOTE: Using the class defined above
var broker = new Broker(config.brokerUrl);

var snowflake = new Snowflake(config, ui, broker);

snowflake.setRelayAddr(config.relayAddr);
snowflake.beginWebRTC();

This minimal setup is pretty much what's currently in init-node.js.

When configuring the snowflake, set a unique proxyType (first argument to Config) that will be used when recording metrics at the broker. Also, it would be helpful to get in touch with the Anti-Censorship Team at the Tor Project to let them know about your tool.

Usage no npm install needed!