snowflake-pt

    0.3.1 • Public • Published

    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.

    Keywords

    none

    Install

    npm i snowflake-pt

    DownloadsWeekly Downloads

    1

    Version

    0.3.1

    License

    BSD-3-Clause

    Unpacked Size

    1.06 MB

    Total Files

    88

    Last publish

    Collaborators

    • arlolra