BridgeDB

---

BridgeDB is a collection of backend servers used to distribute Tor Bridges. It currently consists of a webserver with an HTTPS interface, an email responder, and an SQLite database.

What are Tor Bridges?

Tor Bridges are special Tor relays which are not listed in the public relay directory. They are used to help circumvent censorship by providing users with connections to the public relays in the Tor network.

Tor Bridges are different from normal relays in another important way: they can run what are called Pluggable Transports.

What's a Pluggable Transport?

A Pluggable Transport is a program which is pluggable — meaning that it is meant to work with lots of other anonymity and censorship circumvention software, not just Tor — and is a transport — meaning that it transports your internet traffic, usually in a way which makes it look different. For example, Obfsproxy is a Pluggable Transport which disguises your traffic by adding an obfuscating layer of encryption.

So how do I use this?

Well, probably, you don't. But if you're looking for bridges, you can use the web interface of the BridgeDB instance deployed by the Tor Project, which has instructions on getting the Pluggable Transports-capable Tor Browser Bundle, as well as instructions for getting extra Bridges.

Maintainer Setup

Dependencies and installation

BridgeDB requires the following OS-level dependencies:

• python>=2.7
• python-dev
• build-essential
• libgpgme11
• libgpgme11-dev
• OpenSSL>=1.0.1e
• SQLite3
• MaxMind GeoIP
  • libgeoip-dev
  • geoip-database
• python-setuptools

As well as any Python dependencies in requirements.txt.

Deploying BridgeDB

BridgeDB should work with or without a Python virtualenv.

• Install Python 2.7, and other OS-level dependencies. On Debian, you can do:

   sudo apt-get install build-essential openssl python python-dev \
       python-setuptools sqlite3 libgpgme11 libgpgme11-dev libgeoip-dev \
       geoip-database
  

• Install Pip 1.3.1 or later. Debian has this version, but if for some reason that or a newer version isn't available, the easiest way to install a newer Pip is to use the Pip development teams's getpip script:

   wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
   sudo python get-pip.py
  

• (virtualenv installs only) Use Pip to install virtualenv and virtualenvwrapper:

   sudo pip install --upgrade virtualenv virtualenvwrapper
  

• (virtualenv installs only) Configure virtualenvwrapper and create a virtualenv for Bridgedb:

   WORKON_HOME=${HOME}/.virtualenvs
   export WORKON_HOME
   mkdir -p $WORKON_HOME
   source $(which virtualenvwrapper.sh)
   git clone https://git.torproject.org/bridgedb.git && cd bridgedb
   mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools \
      --setuptools bridgedb
  

  From now on, to use BridgeDB's virtualenv, just do $ workon bridgedb (after sourcing virtualenvwrapper.sh, as before). To exit the virtualenv without exiting the shell, do $ deactivate.

• (virtualenv installs only) To install, set PYTHONPATH to include the root directory of the virtualenv:

   export PYTHONPATH=$PYTHONPATH:${VIRTUAL_ENV}/lib/python2.7/site-packages
  

• Then proceed as usual:

   python setup.py install --record installed-files.txt
  

Testing BridgeDB

To create a bunch of fake bridge descriptors to test BridgeDB, do:

    bridgedb mock [-n NUMBER_OF_DESCRIPTORS]

Then to run unittests, see the bridgedb test and bridgedb trial commands.

Enabling additional features:

Translations

Using New Translations: This should be done when newly completed translations are available in Transifex.

Piece of cake. Running maint/get-completed-translations will take care of cloning only the bridgedb_completed branch of Tor's translations repo and placing all the updated files in their correct locations.

Requesting Translations for Altered/Added Source Code: This should be done whenever any of the strings requiring translation -- _("they are formatted like this") -- are changed, or new ones are added. See lib/bridgedb/I18n.py.

Translations for Tor Project repos are kept in a separate repo. You'll need to extract the strings from BridgeDB's source code into .pot templates, and place these .po files into the translation repo in the bridgedb branch. After than the .po files should be put into Transifex (don't ask me how this works…) and translated. After the translations are complete, the finished .po files should be placed into the bridgedb_completed branch.

• To extract all strings from BridgeDB's source:

  python setup.py extract_messages --input-dirs ./lib/bridgedb/templates
  

  A .pot file will be created in ./i18n/templates/bridgedb.pot

• Initialise catalogs for each desired language:

  python setup.py init_catalog -l LANG
  

  where LANG is the 2 or 4 letter country-code, eg. 'es'. If you've already initialised a particular language, do instead:

  python setup.py update_catalog

Enabling HTTPS

Create a self-signed certificate with:

 scripts/make-ssl-cert

Or, place an existing certificate in the path specified in bridgedb.conf by the HTTPS_CERT_FILE option, and a private key where HTTPS_KEY_FILE points to. The defaults are 'cert' and 'privkey.pem', respectively.

CAPTCHAs

To enable Captchas on the webserver interface, set these options in bridgedb.conf:

RECAPTCHA_ENABLED
RECAPTCHA_PUB_KEY
RECAPTCHA_PRIV_KEY

A recaptcha.net account is required.

GnuPG email signing

Add these two options to your bridgedb.conf:

 EMAIL_GPG_SIGNING_ENABLED
 EMAIL_GPG_SIGNING_KEY

The former may be either True or False, and the latter must point to the ascii-armored private key file. The keyfile must not be passphrase protected.

Preventing already-blocked bridges from being distributed

Uncomment or add COUNTRY_BLOCK_FILE to your bridgedb.conf. This file should contain one bridge entry per line, in the format:

fingerprint <bridge fingerprint> country-code <country code>

If the COUNTRY_BLOCK_FILE file is present, bridgedb will filter blocked bridges from the responses it gives to clients requesting bridges.

Updating the SQL schema

Make sure that SQLite3 is installed. (You should have installed it already during the setup and installation stage.) To update, do:

sqlite3 path/to/bridgedist.db.sqlite

Enter the following commands at the sqlite> prompt:

CREATE TABLE BlockedBridges ( id INTEGER PRIMARY KEY NOT NULL, hex_key, blocking_country);
CREATE INDEX BlockedBridgesBlockingCountry on BlockedBridges(hex_key);
CREATE TABLE WarnedEmails ( email PRIMARY KEY NOT NULL, when_warned);
CREATE INDEX WarnedEmailsWasWarned on WarnedEmails ( email );
REPLACE INTO Config VALUES ( 'schema-version', 2 );

Running BridgeDB

To run BridgeDB, simply make any necessary changes to bridgedb.conf, and do: bridgedb.

When you have new lists of bridges, replace the old files and do:

bridgedb --reload

Make sure that the files and directories referred to in bridgedb.conf exist. However, many of them, if not found, will be touched on disk so that attempts to read/write from/to them will not raise excessive errors.

To extract bucket files of all unallocated bridges:

Edit the configuration file value FILE_BUCKETS according to your needs. For example, the following is a possible configuration:

FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }

This configuration for buckets would result in 3 files being created for bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and foobar-2010-07-17.brdgs. The first file would contain 10 bridges from BridgeDB's 'unallocated' pool. The second file would contain 15 bridges from the same pool and the third one similarly 3 bridges. These files can then be handed out to trusted parties via mail or fed to other distribution mechanisms such as Twitter.

To use with HTTPS:

Just connect to the appropriate port.

To use with email:

Any mail sent to the email port with a destination username as defined by the EMAIL_USERNAME configuration option (default is 'bridge', e.g. bridges@...) and sent from a yahoo or gmail address (by default, configured with the EMAIL_DOMAINS option).

Support

Send your questions to isis (A) torproject (circle) org.