Filename: 199-bridgefinder-integration.txt
Title: Integration of BridgeFinder and BridgeFinderHelper
Author: Mike Perry
Created: 18-03-2012
Status: OBSOLETE
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.
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.
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.
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.
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 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.
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
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.
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.