[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [torspec/master] remove proposals/xxx-bridgefinder-integration.txt



commit f8d4e304774c19e4cff8e918d4b4b3c5a2c34e07
Author: Jacob Appelbaum <jacob@xxxxxxxxxxxxx>
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.
-
-

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits