[tor-dev] Proposal: Integration of BridgeFinder and BridgeFinderHelper

Robert Ransom rransom.8774 at gmail.com
Mon Mar 26 20:48:08 UTC 2012

On 2012-03-22, Mike Perry <mikeperry at torproject.org> wrote:
> Thus spake Robert Ransom (rransom.8774 at gmail.com):
>> [ snip ]
> Ok, attempt #2. This time I tried to get at the core of your concerns
> about attacker controlled input by requring some form of authentication
> on all bridge information that is to be automatically configured.

I rewrote most of the ‘Security Concerns’ section for
BridgeFinder/Helper.  Please merge:
      https://git.torproject.org/rransom/torspec.git bridgefinder2

 Security Concerns: BridgeFinder and BridgeFinderHelper

  1. Do not allow attacks on your IPC channel by malicious local 'live data'

     The biggest risk is that unexpected applications will be
     manipulated into posting malformed data to the BridgeFinder's IPC
     channel as if it were from BridgeFinderHelper. The best way to
     defend against this is to require a handshake to properly
     complete before accepting input. If the handshake fails at any
     point, the IPC channel MUST be abandoned and closed. Do *not*
     continue scanning for good input after any bad input has been
     encountered; that practice may allow cross-protocol attacks by
     malicious JavaScript running in the user's non-Tor web browser.

     Additionally, it is wise to establish a shared secret between
     BridgeFinder and BridgeFinderHelper, using an environment
     variable if possible.  For an a good example on how to use such a
     shared secret properly for authentication; see Tor ticket #5185
     and/or the SAFECOOKIE Tor control port authentication method.

  2. Do not allow attacks against the Controller

     Care has to be taken before converting BridgeFinderHelper data into
     Bridge lines, especially for cases where the BridgeFinderHelper data
     is fed directly to the control port after passing through

     In specific, the input MUST be subjected to a character whitelist
     and should also be validated against a regular expression to
     verify format, and if any unexpected or poorly-formed data is
     encountered, the IPC channel MUST be closed.

     Malicious control-port commands can completely destroy a user's
     anonymity.  BridgeFinder is responsible for preventing strings
     which could plausibly cause execution of arbitrary control-port
     commands from reaching the Controller.

  3. Provide information about bridge sources to users

     BridgeFinder MUST provide complete information about how each
     bridge was obtained (who provided the bridge data, where the
     party which provided the data intended that it be sent to users,
     and what activities BridgeFinder extracted the data from) to
     users so that they can make an informed decision about whether to
     trust the bridge.

     BridgeFinder MUST authenticate, for every piece of discovered
     bridge data, the party which provided the bridge address, the
     party which prepared the bridge data in BridgeFinder's input
     format, and the time, location, and manner in which the latter
     party intended that the bridge data be distributed.  (Use of an
     interactive authentication protocol is not sufficient to
     authenticate the intended location and manner of distribution of
     the bridge data; those facts must be explicitly authenticated.)

     These requirements are intended to prevent or mitigate several
     serious attacks, including the following:

     * A malicious bridge can 'tag' its client's circuits so that a
       malicious exit node can easily recognize them, thereby
       associating the client with some or all of its anonymous or
       pseudonymous activities.  (This attack may be mitigated by new
       cryptographic protocols in a near-future version of Tor.)

     * A malicious bridge can attempt to limit its client's knowledge
       of the Tor network, thereby biasing the client's path selection
       toward attacker-controlled relays.

     * A piece of bridge data containing the address of a malicious
       bridge may be copied to distribution channels other than those
       through which it was intended to be distributed, in order to
       expose more clients to a particular malicious bridge.

     * Pieces of bridge data containing the addresses of non-malicious
       bridges may be copied to other-than-intended distribution
       channels, in order to cause a particular client to attempt to
       connect to a known, unusual set of bridges, thus allowing a
       malicious ISP to monitor the client's movements to other
       network and/or physical locations.

     BridgeFinder MUST warn users about the above attacks, and warn
     that other attacks may also be possible if users accept
     improperly distributed bridge data.

  4. Exercise care with what is written to disk

     BridgeFinder developers must be aware of the following attacks,
     and ensure that their software does not expose users to any of

     * An attacker could plant illegal data on a user's computer, to
       be used later (after a search) as justification to imprison the

     * An attacker could plant malicious data intended to exploit bugs
       in processes which automatically inspect all files on a user's
       disks.  (Some examples of such processes are indexing services
       for filesystem search tools, or anti-virus software.)

     * An attacker could plant malicious data intended to exploit code
       used by a file manager to extract metadata or thumbnails from

     * An attacker could plant malicious data intended to exploit code
       run when a user tries to open or view a file.  (On Unixoid
       systems, executable files which are not in a recognized binary
       format are interpreted by /bin/sh if a user is persuaded to run
       them.  A header is not enough to prevent all attacks of this
       class; malicious data anywhere within a file could take over a
       user's computer.)

     Note that parties which can be trusted to supply bridges to users
     should not be trusted with full code-exec privileges on every
     user's computer.  (For example, bridge descriptors are generated
     and signed by the person who runs a bridge -- but *anyone* can
     run a bridge and start signing bridge descriptors.)

     In order to prevent the above attacks (and others), BridgeFinder
     MUST NOT create files whose contents (entirely or partially) or
     names or file extensions are controlled by a party not intended
     to have full code-exec privileges on every user's computer.

     BridgeFinder SHOULD mark data files which are not intended to be
     executed by the operating system as non-executable, whenever that
     is possible.  (It is not possible when Tor Browser Bundle is run
     on a FAT filesystem on a Unixoid operating system; that
     configuration is supported and known to be used.)

     One way to avoid the code-exec attacks above is to obfuscate data
     (using strong cryptography) before writing it to disk.  Possible
     obfuscation methods include 'grizzling' the data [1] (note that
     the random nonce is important here) or encrypting the data with a
     newly-generated random key and storing the key with the encrypted
     data on disk.  These do not address the illegal-data attack
     (because the user is, in theory, able to de-obfuscate and read
     the data), but they do make it significantly harder for the
     attacker's goons to 'find' the data during a search.

     If a BridgeFinder obfuscates data which it stores on disk, its
     authors MUST provide a simple program to de-obfuscate the data
     (with full source code) so that users can find out what data
     BridgeFinder has collected, and BridgeFinder MUST put a text file
     named "README.txt" in the directory containing the obfuscated
     files explaining how to obtain and use the de-obfuscation tool
     and why such a tool is necessary.

     BridgeFinder SHOULD NOT store information to disk which reveals
     the user's activities in his/her/its non-Tor Browser; some of
     those activities may not otherwise be visible to a censoring
     attacker.  BridgeFinder MUST NOT store such information to disk
     unless the user has explicitly asked it to.

  5. Exercise care with where things are written to disk

     The Tor Browser Bundle is designed to not leave traces that it
     has been run on a computer outside the directory in which it was
     unpacked, and, to the extent possible, to mitigate any such
     traces left by the operating system.

     BridgeFinder MUST NOT write data to disk outside the Tor Browser
     Bundle directory at any time.  BridgeFinder MUST NOT use any
     operating system features which are known to write data to disk
     outside the Tor Browser Bundle directory.

     If BridgeFinderHelper operates as an extension of a program which
     the user has installed on his/her/its computer, it (or
     configuration data needed to cause the non-Tor Browser to load
     it) may need to be installed outside the Tor Browser Bundle
     directory.  However, BridgeFinderHelper SHOULD NOT write data to
     disk or cause data to be written to disk outside the TBB directory.

     BridgeFinderHelper MUST NOT be installed outside the TBB
     directory, and MUST NOT write data to disk, unless the user has
     explicitly permitted that.

     BridgeFinder, BridgeFinderHelper, and their installation
     routines, MUST warn users that traces written to a disk cannot be
     erased without erasing the entire filesystem before asking for
     permission to write outside the TBB directory.  (The user has
     already chosen to leave traces of TBB in the directory it was
     unpacked into.)

     On multi-user operating systems which meaningfully support
     filesystem permissions on the filesystem containing the Tor
     Browser Bundle, BridgeFinder MUST set permissions correctly on
     the files it creates.  In particular, when filesystem permissions
     are available, files containing software meant to be run by
     BridgeFinder MUST NOT be writable by any other OS-level user than
     the one running BridgeFinder, and files containing data not
     intended to be loaded by the operating system as an executable
     file MUST NOT be marked as executable.

  6. Avoid assumptions about BridgeFinder's process environment

     BridgeFinder and BridgeFinderHelper MUST NOT allow any data to be
     sent to their standard output and standard error files.  (On
     Linux, those file descriptors often point to
     $HOME/.xsession-errors; on MacOS, data sent to an application's
     stdout or stderr is recorded in /var/log/system.log.)

     BridgeFinder and BridgeFinderHelper MUST NOT change their
     behaviour based on the values or presence of environment
     variables except as required by IPC protocols which they must
     conform to.  Very few users know that environment variables
     exist, and many of those who do do not understand how environment
     variables work.  Naive users can easily be conned into setting
     environment variables which will cause BridgeFinder or
     BridgeFinderHelper to misbehave.

  7. Do not attempt to operate from within Tor Browser

     BridgeFinder and BridgeFinderHelper MUST NOT attempt to
     automatically obtain information about bridges from within Tor
     Browser.  Doing so would allow an attacker to de-anonymize a
     pseudonymous user by sending pieces of bridge information to
     him/her/it, or learn about a user's anonymous activities by
     planting pieces of bridge information on websites of interest to
     the attacker.  (Checking that pieces of bridge information are
     signed by a party trusted to provide them is not sufficient to
     defend against this class of attack; signatures on a piece of
     bridge information do not authenticate metadata such as the web
     page meant to distribute it or the e-mail address to which it was

     BridgeFinder SHOULD NOT use information obtained by the user
     through the Tor Browser.  If it does, it MUST only use
     information explicitly provided to BridgeFinder by the user for
     the purpose of bridge discovery, and it MUST warn the user that
     maliciously placed bridge information could be used to identify
     and/or locate users who receive and use it.

     A BridgeFinder or BridgeFinderHelper MAY make its own active
     connections through Tor for the purpose of finding new bridge
     addresses (or updating previously acquired addresses), but MUST
     use Tor's stream isolation feature (Tor proposal 171) to separate
     BridgeFinder streams from the user's anonymous/pseudonymous

  8. Do not stick beans up the user's nose

     Deployed versions of BridgeFinder and BridgeFinderHelper MUST NOT
     have any debugging features which cause them to log sensitive
     data to disk.  Someone *will* turn them on, whether by accident
     or by malice.

     Development versions of BridgeFinder and BridgeFinderHelper which
     have such debugging features MUST warn users that they are
     development builds and should not be used by non-developers.

     If BridgeFinder and/or BridgeFinderHelper open listening sockets
     for IPC purposes, those sockets MUST be bound to a loopback
     address (not to e.g. IPADDR_ANY).  Otherwise, They could probe
     for your IPC socket's presence on a user's computer.

  9. Inform BridgeFinder developers about these issues

     All documents prepared or promoted by Tor Project, Inc. which are
     intended to be sufficient for the reader to implement a
     BridgeFinder must describe the known security considerations for
     BridgeFinders and their underlying rationales.

     The BridgeFinder interface is intended to allow developers who
     are not experts on Tor, and who may not be aware of the unusual
     threat models which Tor and Tor Browser Bundle address, to write
     software which users and distributors will integrate into Tor
     Browser Bundle.  These developers are unlikely to be aware of
     Tor-specific and BridgeFinder-specific security considerations
     (e.g. attacks involving malicious bridges), and even developers
     who are informed about the rules stated above may see the rules
     as unnecessary and ignore them if their rationales are not
     explicitly stated.

     In general, BridgeFinder developers need to be aware that they
     are writing security-critical code, with a large set of
     application-specific security requirements on top of the usual
     security requirements for all software which interacts with an
     untrusted network.

1. http://www.cl.cam.ac.uk/~rja14/Papers/grizzle.pdf

Robert Ransom

More information about the tor-dev mailing list