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

[Robert Ransom]

On 2012-03-21, Mike Perry <mikeperry at torproject.org> wrote:
> The following proposal should complete SponsorF tickets #5010-5012.
>
> I've pushed the proposal to my torspec.git branch
> mikeperry/bridgefinder, since the POSTMESSAGE Proposal ended up with
> some garbling at somewhere along the cut and paste chain. That branch
> also contains fixes for the POSTMESSAGE proposal's garbling.
>
>
> Filename: xxx-bridgefinder-integration.txt
> Title: Integration of BridgeFinder and BridgeFinderHelper
> Author: Mike Perry
> Created: 18-03-2012
> Status: Proposed
> Target: 0.2.3.x+
>
>
> Overview
>
>   This proposal describes how the Tor client software can interact with
>   an external program that performs bridge discovery based on user input
>   or information extracted from a web page, QR Code, online game, or
>   other transmission medium.
>
>
> Scope and Audience
>
>   This document describes how all of the components involved in bridge
>   discovery communicate this information to the rest of the Tor
>   software. The mechanisms of bridge discovery are not discussed, though
>   the design aims to be generalized enough to allow arbitrary new
>   discovery mechanisms to be added at any time.
>
>   This document is also written with the hope that those who wish to
>   implement BridgeFinder components and BridgeFinderHelpers can get
>   started immediately after a read of this proposal, so that development
>   of bridge discovery mechanisms can proceed in parallel to supporting
>   functionality improvements in the Tor client software.
>
>
> Components and Responsibilities
>
>  0. Tor Client
>
>     The Tor Client is the piece of software that connects to the Tor
>     network (optionally using bridges) and provides a SOCKS proxy for
>     use by the user.
>
>     In initial implementations, the Tor Client will support only
>     standard bridges. In later implementations, it is expected to
>     support pluggable transports as defined by Proposal 180.
>
>  1. Tor Control Port
>
>     The Tor Control Port provides commands to perform operations,
>     configuration, and to obtain status information. It also optionally
>     provides event driven status updates.
>
>     In initial implementations, it will be used directly by BridgeFinder
>     to configure bridge information via GETINFO and SETCONF. It is covered
>     by control-spec.txt in the tor-specs git repository.
>
>     In later implementations, it will support the inter-controller
>     POSTMESSAGE IPC protocol as defined by Proposal 197 for use
>     in conveying bridge information to the Primary Controller.
>
>  2. Primary Controller
>
>     The Primary Controller is the program that launches and configures the
>     Tor client, and monitors its status.
>
>     On desktop platforms, this program is Vidalia, and it also launches
>     the Tor Browser. On Android, this program is Orbot. Orbot does not
>     launch a browser.
>
>     On all platforms, this proposal requires that the Primary Controller
>     will launch one or more BridgeFinder child processes and provide
>     them with authentication information through the environment variables
>     TOR_CONTROL_PORT and TOR_CONTROL_PASSWD.
>
>     In later implementations, the Primary Controller will be expected
>     to receive Bridge configuration information via the free-form
>     POSTMESSAGE protocol from Proposal 197, validate that information,
>     and hold that information for user approval.
>
>  3. BridgeFinder
>
>     A BridgeFinder is a program that discovers bridges and configures
>     Tor to use them.
>
>     In initial implementations, it is likely to be very dumb, and its main
>     purpose will be to serve as a layer of abstraction that should free
>     the Primary Controller from having to directly implement numerous ways
>     of retrieving bridges for various pluggable transports.
>
>     In later implementations, it may perform arbitrary network operations
>     to discover, authenticate to, and/or verify bridges, possibly using
>     informational hints provided by one or more external
>     BridgeFinderHelpers (see next component). It could even go so far as
>     to download new pluggable transport plugins and/or transform
>     definition files from arbitrary urls.
>
>     It will be launched by the Primary Controller and given access to the
>     Tor Control Port via the environment variables TOR_CONTROL_PORT and
>     TOR_CONTROL_PASSWD.
>
>     Initial control port interactions can be command driven via GETINFO
>     and SETCONF, and do not need to subscribe to or process control port
>     events. Later implementations will use POSTMESSAGE as defined in
>     Proposal 197 to pass command requests to Vidalia, which will parse
>     them and ask for user confirmation before deploying them. Use of
>     POSTMESSAGE may or may not require event driven operation, depending
>     on POSTMESSAGE implementation status (POSTMESSAGE is designed to
>     support both command and event driven operation, but it is possible
>     event driven operation will happen first).
>
>  4. BridgeFinderHelper
>
>     Each BridgeFinder implementation can optionally communicate with one
>     or more BridgeFinderHelpers. BridgeFinderHelpers are plugins to
>     external 3rd party applications that can inspect traffic, handle mime
>     types, or implement protocol handlers for accepting bridge discovery
>     information to pass to BridgeFinder. Example 3rd party applications
>     include Chrome, World of Warcraft, QR Code readers, or simple cut
>     and paste.
>
>     Due to the arbitrary nature of sandboxing that may be present in
>     various BridgeFinderHelper host applications, we do not mandate the
>     exact nature of the IPC between BridgeFinder instances and external
>     BridgeFinderHelper addons. However, please see the "Security Concerns"
>     section for common pitfalls to avoid.
>
>  5. Tor Browser
>
>     This is the browser the user uses with Tor. It is not useful until Tor
>     is properly configured to use bridges. It fails closed.
>
>     It is not expected to run BridgeFinderHelper plugin instances, unless
>     those plugin instances exist to ensure the user always has a pool of
>     working bridges available after successfully configuring an
>     initial bridge. Once all bridges fail, the Tor Browser is useless.

Information received by a Tor Browser MUST NOT EVER EVER EVER be given
to a BridgeFinder or BridgeFinderHelper.  Doing so would immediately
link the user's anonymous/pseudonymous activities to his/her/its
network address.

(If a user wants to obtain a bridge through Tor, he/she/it can
explicitly copy and paste information about a bridge into a Tor
controller or a BridgeFinder.  BridgeFinders which are intended to
accept such information SHOULD warn the user to avoid linking the
bridge to his/her/it sensitive activities.)

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

>
>  6. Non-Tor Browser (aka BridgeFinderHelper host)
>
>     This is the program the user uses for normal Internet activity to
>     obtain bridges via a BridgeFinderHelper plugin. It does not have to be
>     a browser. In advanced scenarios, this component may not be a browser
>     at all, but may be a program such as World of Warcraft instead.
>
>
> Incremental Deployability
>
>   The system is designed to be incrementally deployable: Simple designs
>   should be possible to develop and test immediately. The design is
>   flexible enough to be easily upgraded as more advanced features become
>   available from both Tor and new pluggable transports.
>
> Initial Implementation
>
>   In the simplest possible initial implementation, BridgeFinder will
>   only discover Tor Bridges as they are deployed today. It will use the
>   Tor Control Port to configure these bridges directly via the SETCONF
>   command. It may or may not receive bridge information from a
>   BridgeFinderHelper. In an even more degenerate case,
>   BridgeFinderHelper may even be Vidalia or Orbot itself, acting upon
>   user input from cut and paste.
>
>  Initial Implementation: BridgeFinder Launch
>
>    In the initial implementation, the Primary Controller will launch one
>    or more BridgeFinders, providing control port authentication
>    information to them through the environment variables TOR_CONTROL_PORT
>    and TOR_CONTROL_PASSWD.
>
>    BridgeFinder will then directly connect to the control port and
>    authenticate. Initial implementations should be able to function
>    without using SETEVENTS, and instead only using command-based
>    status inquiries and configuration (GETINFO and SETCONF).
>
>  Initial Implementation: Obtaining Bridge Hint Information
>
>    In the initial implementation, to test functionality,
>    BridgeFinderHelper can simply scrape bridges directly from
>    https://bridges.torproject.org.
>
>    In slightly more advanced implementations, a BridgeFinderHelper
>    instance may be written for use in the user's Non-Tor Browser. This
>    plugin could extract bridges from images, html comments, and other
>    material present in ad banners and slack space on unrelated pages.
>
>    BridgeFinderHelper would then communicate with the appropriate
>    BridgeFinder instance over an acceptable IPC mechanism. This proposal
>    does not seek to specify the nature of that IPC channel (because
>    BridgeFinderHelper may be arbitrarily constrained due to host
>    application sandboxing), but we do make several security
>    recommendations under the section "Security Concerns: BridgeFinder and
>    BridgeFinderHelper".
>
>  Initial Implementation: Configuring New Bridges
>
>    In the initial implementation, Bridge configuration will be done
>    directly though the control port using the SETCONF command.
>
>    Initial implementations will support only retrieval and configuration
>    of standard Tor Bridges. These are configured using SETCONF on the Tor
>    Control Port as follows:
>      SETCONF Bridge="IP:ORPort [fingerprint]"
>
>
> Future Implementations
>
>   In future implementations, the system can incrementally evolve in a
>   few different directions. As new pluggable transports are created, it
>   is conceivable that BridgeFinder may want to download new plugin
>   binaries (and/or new transport transform definition files) and
>   provide them to Tor.

BridgeFinder and BridgeFinderHelper MUST NOT write any data received
from the network to any disk without the user's explicit permission.
In particular, they MUST NOT create files with (entirely or partially)
attacker-controlled contents or files with attacker-controlled names
or file extensions.

>
>   Furthermore, it may prove simpler to deploy multiple concurrent
>   BridgeFinder+BridgeFinderHelper pairs as opposed to adding new
>   functionality to existing prototypes.
>
>   Finally, it is desirable for BridgeFinder to obtain approval
>   from the user before updating bridge configuration, especially for
>   cases where BridgeFinderHelper is automatically discovering bridges
>   in-band during Non-Tor activity.
>
>   The exact mechanisms for accomplishing these improvements is
>   described in the following subsections.
>
>  Future Implementations: BridgeFinder Launch and POSTMESSAGE handshake
>
>    The nature of the BridgeFinder launch and the environment variables
>    provided is not expected to change. However, future Primary Controller
>    implementations may decide to launch more than one BridgeFinder
>    instance side by side.
>
>    Additionally, to negotiate the IPC channel created by Proposal 197
>    for purposes of providing user confirmation, it is recommended that
>    BridgeFinder and the Primary Controller perform a handshake using
>    POSTMESSAGE upon launch, to establish that all parties properly
>    support the feature:
>
>      Primary Controller: "POSTMESSAGE @all Controller wants POSTMESSAGE
> v1.1"
>      BridgeFinder: "POSTMESSAGE @all BridgeFinder has POSTMESSAGE v1.0"
>      Primary Controller: "POSTMESSAGE @all Controller expects POSTMESSAGE
> v1.0"
>      BridgeFinder: "POSTMESSAGE @all BridgeFinder will POSTMESSAGE v1.0"
>
>    If this 4 step handshake proceeds with an acceptable version,
>    BridgeFinder must use POSTMESSAGE to transmit SETCONF Bridge lines
>    (see "Future Implementations: Configuring New Bridges" below). If
>    POSTMESSAGE support is expected, but the handshake does not complete
>    for any reason, BridgeFinder should either exit or go dormant.

“POSTMESSAGE” is the name of the Tor control-port command.  It should
not also be the name of a protocol which BridgeFinder may transmit
over the POSTMESSAGE transport layer.

How does Controller know when BridgeFinder has connected to Tor's
control port, so that it can begin the IPC protocol handshake?

What happens if Controller tries to perform an IPC-protocol handshake
with more than one BridgeFinder at the same time?  What about other
components which try to use this interface?

>
>    The exact nature of the version negotiation and exactly how much
>    backwards compatibility must be tolerated is unspecified.
>    "All-or-nothing" is a safe assumption to get started.

The version negotiation MUST be specified completely before anyone
tries to implement it.

>
>  Future Implementations: Obtaining Bridge Hint Information
>
>    Future BridgeFinder implementations may download additional
>    information based on what is provided by BridgeFinderHelper. They
>    may fetch pluggable transport plugins, transformation parameters,
>    and other material.
>
>  Future Implementations: Configuring New Bridges
>
>    Future implementations will be concerned with providing two new pieces
>    of functionality with respect to configuring bridges: configuring
>    pluggable transports, and properly prompting the user before altering
>    Tor configuration.
>
>    There are two ways to tell Tor clients about pluggable transports
>    (as defined in Proposal 180).
>
>    On the control port, an external Proposal 180 transport will be
>    configured with
>      SETCONF ClientTransportPlugin=<method> socks5 <addr:port> [auth=X]
>    as in
>      SETCONF ClientTransportPlugin="trebuchet socks5 127.0.0.1:9999".
>
>    A managed proxy is configured with
>      SETCONF ClientTransportPlugin=<methods> exec <path> [options]
>    as in
>      SETCONF ClientTransportPlugin="trebuchet exec /usr/libexec/trebuchet
> --managed".
>
>    This example tells Tor to launch an external program to provide a
>    socks proxy for 'trebuchet' connections. The Tor client only
>    launches one instance of each external program with a given set of
>    options, even if the same executable and options are listed for
>    more than one method.
>
>    Pluggable transport bridges discovered for this transport by
>    BridgeFinder would then be set with:
>      SETCONF Bridge="trebuchet 3.2.4.1:8080
> keyid=09F911029D74E35BD84156C5635688C009F909F9 rocks=20 height=5.6m".

For this type of PT, you'll also want the target's position (latitude,
longitude, elevation, and datum), and a signed descriptor proving that
the target is expecting to receive packets from this pluggable
transport.

(Sorry.  Couldn't resist.)

>
>    For more information on pluggable transports and supporting Tor
>    configuration commands, see Proposal 180.
>
>  Future Implementations: POSTMESSAGE and User Confirmation
>
>    Because configuring even normal bridges alone can expose the user to
>    attacks, it is strongly desired to provide some mechanism to allow
>    the user to approve new bridges prior to their use, especially for
>    situations where BridgeFinderHelper is extracting them transparently
>    while the user performs unrelated activity.
>
>    If BridgeFinderHelper grows to the point where it is downloading new
>    transform definitions or plugins, user confirmation becomes
>    absolutely required.
>
>    To achieve user confirmation, we depend upon the POSTMESSAGE command
>    defined in Proposal 197.
>
>    If the POSTMESSAGE handshake succeeds, instead of sending SETCONF
>    commands directly to the control port, the commands will be wrapped
>    inside a POSTMESSAGE:
>      POSTMESSAGE @all SETCONF Bridge="www.example.com:8284"
>
>    Upon receiving this POSTMESSAGE, the Primary Controller will
>    validate it, evaluate it, store it to be later enabled by the
>    user, and alert the user that new bridges are available for
>    approval. It is only after the user has approved the new bridges
>    that the Primary Controller should then re-issue the SETCONF commands
>    to configure and deploy them in the tor client.
>
>    Additionally, see "Security Concerns: Primary Controller" for more
>    discussion on potential pitfalls with POSTMESSAGE.
>
> Security Concerns
>
>   While automatic bridge discovery and configuration is quite compelling
>   and powerful, there are several serious security concerns that warrant
>   extreme care. We've broken them down by component.
>
>  Security Concerns: Primary Controller
>
>    In the initial implementation, Orbot and Vidalia must take care to
>    transmit the Tor Control password to BridgeFinder in such a way that
>    it does not end up in system logs, process list, or viewable by other
>    system users. The best known strategy for doing this is by passing the
>    information through exported environment variables.
>
>    Additionally, in future implementations, Orbot and Vidalia will need
>    to validate Proposal 197 POSTMESSAGE input before prompting the user.
>    POSTMESSAGE is a free-form message-passing mechanism. All sorts of
>    unexpected input may be passed through it by any other authenticated
>    Tor Controllers for their own unrelated communication purposes.
>
>    Minimal validation includes verifying that the POSTMESSAGE data is a
>    valid Bridge or ClientTransportPlugin line and is acceptable input for
>    SETCONF. All unexpected characters should be removed through using a
>    whitelist, and format and structure should be checked against a
>    regular expression. Additionally, the POSTMESSAGE string should not be
>    passed through any string processing engines that automatically decode
>    character escape encodings, to avoid arbitrary control port execution.
>
>    At the same time, POSTMESSAGE validation should be light. While fully
>    untrusted input is not expected due to the need for control port
>    authentication and BridgeFinder sanitation, complicated manual string
>    parsing techniques during validation should be avoided. Perform simple
>    easy-to-verify whitelist-based checks, and ignore unrecognized input.
>
>    Beyond POSTMESSAGE validation, the manner in which the Primary
>    Controller achieves consent from the user is absolutely crucial to
>    security under this scheme. A simple "OK/Cancel" dialog is
>    insufficient to protect the user from the dangers of switching
>    bridges and running new plugins automatically.
>
>    Newly discovered bridge lines from POSTMESSAGE should be added to a
>    disabled set that the user must navigate to as an independent window
>    apart from any confirmation dialog. The user must then explicitly
>    enable recently added plugins by checking them off individually. We
>    need the user's brain to be fully engaged and aware that it is
>    interacting with Tor during this step.  If they get an "OK/Cancel"
>    popup that interrupts their online game play, they will almost
>    certainly simply click "OK" just to get back to the game quickly.
>
>    The Primary Controller should transmit the POSTMESSAGE content to the
>    control port only after obtaining this out-of-band approval.
>
> Security Concerns: BridgeFinder and BridgeFinderHelper
>
>   The unspecified nature of the IPC channel between BridgeFinder and
>   BridgeFinderHelper makes it difficult to make concrete security
>   suggestions. However, from past experience, the following best
>   practices must be employed to avoid security vulnerabilities:
>
>   1. Define a non-webby handshake and/or perform authentication
>
>      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.
>
>      Additionally, if possible, it is wise to establish a shared secret
>      between BridgeFinder and BridgeFinderHelper through the filesystem or
>      any other means available for use in authentication. For an a good
>      example on how to use such a shared secret properly for
>      authentication, see Trac Ticket #5185 and/or the SafeCookie Tor
>      Control Port authentication mechanism.

Under Windows, the filesystem is not a good way to transfer an
authentication secret.  (Some computers are used by multiple users
with separate Windows user accounts; files on a USB stick may not have
proper separation of privileges.)  Use environment variables instead;
Tor Browser Bundle users are already rather screwed if those are
available to an attacker.

I was about to say that the protocol described and implemented in
#5185 is not a good example, but it actually is a very good example.
But note that every BridgeFinder/BridgeFinderHelper pair MUST use a
different pair of constant strings as HMAC keys, and note that (at a
minimum) the shared secret (‘cookie’) and server nonce must have fixed
length, enforced by the client.  (Also, if you have a real hash
function like CubeHash, you can drop the HMAC and feed all the strings
into a single hash-function call.)

>
>   2. Perform validation before parsing
>
>      Care must 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
>      BridgeFinder.
>
>      The input should be subjected to a character whitelist and possibly

s/should/MUST/
s/ possibly//

>      also validated against a regular expression to verify format, and if
>      any unexpected or poorly-formed data is encountered, the IPC channel
>      must be closed.

s/must/MUST/

>
>   3. Fail closed on unexpected input
>
>      If the handshake fails, or if any other part of the BridgeFinderHelper
>      input is invalid, the IPC channel must be abandoned and closed. Do
>      *not* continue scanning for good input after any bad input has been
>      encountered.