[tor-commits] [torspec/master] proposal 199 by mikeperry
ioerror at torproject.org
ioerror at torproject.org
Wed Mar 21 01:43:17 UTC 2012
commit cee63cc90fd6623e1f5b4dad5f608bfd2049cc90
Author: Jacob Appelbaum <jacob at appelbaum.net>
Date: Tue Mar 20 18:42:27 2012 -0700
proposal 199 by mikeperry
---
proposals/000-index.txt | 2 +
proposals/199-bridgefinder-integration.txt | 415 ++++++++++++++++++++++++++++
2 files changed, 417 insertions(+), 0 deletions(-)
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index d553084..86a6d5b 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -119,6 +119,7 @@ Proposals by number:
196 Extended ORPort and TransportControlPort [OPEN]
197 Message-based Inter-Controller IPC Channel [OPEN]
198 Restore semantics of TLS ClientHello [OPEN]
+199 Integration of BridgeFinder and BridgeFinderHelper [OPEN]
Proposals by status:
@@ -158,6 +159,7 @@ Proposals by status:
196 Extended ORPort and TransportControlPort [for 0.2.4.x]
197 Message-based Inter-Controller IPC Channel [for 0.2.4.x]
198 Restore semantics of TLS ClientHello
+ 199 Integration of BridgeFinder and BridgeFinderHelper [for 0.2.3.x+]
ACCEPTED:
117 IPv6 exits [for 0.2.3.x]
140 Provide diffs between consensuses
diff --git a/proposals/199-bridgefinder-integration.txt b/proposals/199-bridgefinder-integration.txt
new file mode 100644
index 0000000..d3796ad
--- /dev/null
+++ b/proposals/199-bridgefinder-integration.txt
@@ -0,0 +1,415 @@
+Filename: 199-bridgefinder-integration.txt
+Title: Integration of BridgeFinder and BridgeFinderHelper
+Author: Mike Perry
+Created: 18-03-2012
+Status: Open
+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.
+
+ 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.
+
+
More information about the tor-commits
mailing list