[tor-commits] [torspec/master] remove proposals/xxx-bridgefinder-integration.txt
ioerror at torproject.org
ioerror at torproject.org
Wed Mar 21 03:12:36 UTC 2012
commit f8d4e304774c19e4cff8e918d4b4b3c5a2c34e07
Author: Jacob Appelbaum <jacob at appelbaum.net>
Date: Tue Mar 20 20:12:08 2012 -0700
remove proposals/xxx-bridgefinder-integration.txt
---
proposals/xxx-bridgefinder-integration.txt | 415 ----------------------------
1 files changed, 0 insertions(+), 415 deletions(-)
diff --git a/proposals/xxx-bridgefinder-integration.txt b/proposals/xxx-bridgefinder-integration.txt
deleted file mode 100644
index c6c55ec..0000000
--- a/proposals/xxx-bridgefinder-integration.txt
+++ /dev/null
@@ -1,415 +0,0 @@
-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.
-
- 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