Thus spake Robert Ransom (rransom.8774@gmail.com):

[ snip ]

I've updated the proposal to address your concerns at mikeperry/bridgefinder2. I've relaxed some of the requirements a little, but I think I still properly cover everything you mentioned. Here's the updated proposal inline for more comment: Filename: 199-bridgefinder-integration.txt Title: Integration of BridgeFinder and BridgeFinderHelper Author: Mike Perry Reviewed-By: Robert Ransom 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: BridgeFinder and BridgeFinderHelper" 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. Any BridgeFinderHelper implementation that does run in Tor Browser has to take special care to avoid linkability by malicious exit nodes. See "Security Concerns: BridgeFinder and BridgeFinderHelper" for more details. 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.0" 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 completes, BridgeFinder MUST only use POSTMESSAGE to transmit SETCONF Bridge lines (see "Future Implementations: Configuring New Bridges" below). If acknowledgment is expected, but the handshake does not complete for any reason, BridgeFinder should either exit or go dormant. To ensure that there are no race conditions for control port access, the Primary Controller should verify that launched BridgeFinder instances properly connect by using the Proposal 197 command "GETINFO list-controllers" prior to initiating the handshake. Also, for the near future, it is the responsibility of the Primary Controller to avoid launching new BridgeFinder instances before the handshake with previous instances completes. Once the CONTROLLERNAME and POSTMESSAGE SourceControllerIDs portions of Proposal 197 are fully implemented, it will be possible to support concurrent handshakes by tracking the SourceControllerID property, if it is so desired. The exact nature of the version negotiation and exactly how much backwards compatibility should be tolerated is unspecified. "All-or-nothing" is a safe assumption to get started. The version negotiation should be specified completely before anyone tries to implement it, however. 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=42 rocks=2 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 has to navigate to as an independent window apart from any confirmation dialog. The user will 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. Additionally, the Primary Controller MUST NOT store any unapproved BridgeFinder data on disk until such time as the user is able to either accept or reject it. Finally, in the event that multiple BridgeFinderHelper plugins are to be deployed concurrently using the same BridgeFinder, a proposal should be written to introduce a POSTMESSAGE mechanism for BridgeFinderHelper attribution, so that the user is able to see which BridgeFinderHelper provided which bridges at which time in the Primary Controller UI. Up until that point, the POSTMESSAGE SourceControllerID property (set using the CONTROLLERNAME command) can be used to attribute bridges to a particular BridgeFinder instance. 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 has to 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. In specific, the input MUST be subjected to a character whitelist and should also be 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. 4. Exercise care with disk activity If transport plugins or definition/configuration files are to be downloaded, the BridgeFinder MUST ensure that they are only written to a known, controlled subdirectory of the Tor Browser Bundle, and with predictable extensions and properly applied permissions. In particular, BridgeFinder MUST NOT create files with (entirely or partially) attacker-controlled contents or files with attacker-controlled names or file extensions. 5. Exercise care when operating from within Tor Browser Any BridgeFinderHelper operating from within Tor Browser MUST NOT use the same passive side-channel and/or steganographic techniques employed by the Non-Tor BridgeFinderHelper, as these types of techniques can be (ab)used by malicious exit nodes to deanonymize users by feeding them specific, malicious bridges. Any bridge discovery performed from within Tor Browser MUST be active in nature (with bridge sources fully controlled by BridgeFinderHelper) and MUST be authenticated (via TLS+cert pinning and/or HMAC). Further, 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. -- Mike Perry

Thus spake Robert Ransom (rransom.8774@gmail.com):

[ snip ]

Ok, attempt #2. This time I tried to get at the core of your concerns about attacker controlled input by requring some form of authentication on all bridge information that is to be automatically configured. I also added a requirement for end to end encryption to be performed on the content of any side channels that can be observed by exit nodes, and made a few other minor tweaks. Here's the diff (pushed to mikeperry/bridgefinder2 again): https://gitweb.torproject.org/user/mikeperry/torspec.git/commitdiff/f6fbb43b... And here's the full updated proposal again: Filename: 199-bridgefinder-integration.txt Title: Integration of BridgeFinder and BridgeFinderHelper Author: Mike Perry Reviewed-By: Robert Ransom 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: BridgeFinder and BridgeFinderHelper" 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. Any BridgeFinderHelper implementation that does run in Tor Browser has to take special care to avoid linkability by malicious exit nodes. See "Security Concerns: BridgeFinder and BridgeFinderHelper" for more details. 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.0" 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 completes, BridgeFinder MUST only use POSTMESSAGE to transmit SETCONF Bridge lines (see "Future Implementations: POSTMESSAGE Request and User Confirmation" below). If acknowledgment is expected, but the handshake does not complete for any reason, BridgeFinder should either exit or go dormant. To ensure that there are no race conditions for control port access, the Primary Controller should verify that launched BridgeFinder instances properly connect by using the Proposal 197 command "GETINFO list-controllers" prior to initiating the handshake. Also, for the near future, it is the responsibility of the Primary Controller to avoid launching new BridgeFinder instances before the handshake with previous instances completes. Once the CONTROLLERNAME and POSTMESSAGE SourceControllerID portions of Proposal 197 are fully implemented, it will be possible to support concurrent handshakes by tracking the SourceControllerID property, if it is so desired. The exact nature of the version negotiation and exactly how much backwards compatibility should be tolerated is unspecified. "All-or-nothing" is a safe assumption to get started. The version negotiation should be specified completely before anyone tries to implement it, however. 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 Pluggable Transport 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=42 rocks=2 height=5.6m". For more information on pluggable transports and supporting Tor configuration commands, see Proposal 180. Future Implementations: POSTMESSAGE Request 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. We use it to develop the informal and ad-hoc "POSTMESSAGE Request" protocol, whereby BridgeFinder implementations will use POSTMESSAGE commands to request that bridges be configured by the Primary Controller. 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 Request SETCONF Bridge="www.example.com:8284" ^^^^^^^ ````````````````````````````````````` Notice that the original initial implementation's SETCONF is pasted verbatim inside the POSTMESSAGE free-form message body. Notice also the addition of the "Request" prefix, which is intended to make it easier for POSTMESSAGE subscribers to filter messages of interest. Upon receiving this POSTMESSAGE Request, 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 each POSTMESSAGE "Request" payload 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 has to navigate to as an independent window apart from any confirmation dialog. The user will then explicitly enable recently added bridges 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. Additionally, the Primary Controller MUST NOT store any unapproved BridgeFinder data on disk until such time as the user is able to either accept or reject it. Finally, in the event that multiple BridgeFinderHelper plugins are to be deployed concurrently using the same BridgeFinder, a proposal should be written to introduce a POSTMESSAGE mechanism for BridgeFinderHelper attribution, so that the user is able to see which BridgeFinderHelper provided which bridges at which time in the Primary Controller UI. Up until that point, the POSTMESSAGE SourceControllerID property (set using the CONTROLLERNAME command) can be used to attribute bridges to a particular BridgeFinder instance. 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 has to 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. In specific, the input MUST be subjected to a character whitelist and should also be 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. 4. Authenticate Bridge Information One of BridgeFinder or BridgeFinderHelper MUST authenticate all discovered bridge information using TLS+cert pinning, HMAC, or public key signatures, to protect against malicious bridge injection. 5. Exercise care with disk activity If transport plugins or definition/configuration files are to be downloaded, the BridgeFinder MUST ensure that they are only written to a known, controlled subdirectory of the Tor Browser Bundle, and with predictable extensions and properly applied permissions (such as removal of execute permissions for transform definition files). In particular, BridgeFinder MUST NOT create files with (entirely or partially) attacker-controlled contents or files with attacker-controlled names or file extensions. The prior point about authenticating Bridge Information applies especially to downloaded file content to avoid attacker control over content. 6. Exercise additional care when operating from within Tor Browser In addition to the authentication properties required for all automated bridge transmission, any bridge discovery performed from within Tor Browser MUST deploy end to end encryption layered inside whatever side channels it uses for discovery. This must be done to avoid exit node observation of bridge information and resulting linkability. Further, a BridgeFinder or BridgeFinderHelper MAY make its own active connections through Tor for the purpose of finding new bridge addresses (or updating previously acquired addresses), but MUST use Tor's stream isolation feature (Proposal 171) to separate BridgeFinder streams from the user's anonymous/pseudonymous activities. -- Mike Perry

Thus spake Robert Ransom (rransom.8774@gmail.com):

I rewrote most of the ‘Security Concerns’ section for BridgeFinder/Helper. Please merge: https://git.torproject.org/rransom/torspec.git bridgefinder2

Security Concerns: BridgeFinder and BridgeFinderHelper

1. Do not allow attacks on your IPC channel by malicious local 'live data'

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; that practice may allow cross-protocol attacks by malicious JavaScript running in the user's non-Tor web browser.

Additionally, it is wise to establish a shared secret between BridgeFinder and BridgeFinderHelper, using an environment variable if possible. For an a good example on how to use such a shared secret properly for authentication; see Tor ticket #5185 and/or the SAFECOOKIE Tor control port authentication method.

2. Do not allow attacks against the Controller

Care has to 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.

In specific, the input MUST be subjected to a character whitelist and should also be validated against a regular expression to verify format, and if any unexpected or poorly-formed data is encountered, the IPC channel MUST be closed.

Malicious control-port commands can completely destroy a user's anonymity. BridgeFinder is responsible for preventing strings which could plausibly cause execution of arbitrary control-port commands from reaching the Controller.

3. Provide information about bridge sources to users

BridgeFinder MUST provide complete information about how each bridge was obtained (who provided the bridge data, where the party which provided the data intended that it be sent to users, and what activities BridgeFinder extracted the data from) to users so that they can make an informed decision about whether to trust the bridge.

I like the idea of passing bridge authentication + attribution up to Vidalia via POSTMESSAGE somehow. However, encoding it properly is likely to be problematic and situation-specific. It also feels weird to have this be a MUST, especially if we're not sure how it can be done right..

BridgeFinder MUST authenticate, for every piece of discovered bridge data, the party which provided the bridge address, the party which prepared the bridge data in BridgeFinder's input format, and the time, location, and manner in which the latter party intended that the bridge data be distributed. (Use of an interactive authentication protocol is not sufficient to authenticate the intended location and manner of distribution of the bridge data; those facts must be explicitly authenticated.)

These requirements are intended to prevent or mitigate several serious attacks, including the following:

* A malicious bridge can 'tag' its client's circuits so that a malicious exit node can easily recognize them, thereby associating the client with some or all of its anonymous or pseudonymous activities. (This attack may be mitigated by new cryptographic protocols in a near-future version of Tor.)

* A malicious bridge can attempt to limit its client's knowledge of the Tor network, thereby biasing the client's path selection toward attacker-controlled relays.

* A piece of bridge data containing the address of a malicious bridge may be copied to distribution channels other than those through which it was intended to be distributed, in order to expose more clients to a particular malicious bridge.

* Pieces of bridge data containing the addresses of non-malicious bridges may be copied to other-than-intended distribution channels, in order to cause a particular client to attempt to connect to a known, unusual set of bridges, thus allowing a malicious ISP to monitor the client's movements to other network and/or physical locations.

BridgeFinder MUST warn users about the above attacks, and warn that other attacks may also be possible if users accept improperly distributed bridge data.

Warning users about technically complicated potential attacks is unlikely to substantially protect them in practice, and will have many negative consequences wrt usability... There is a right place to document this stuff, but I'm not sure the BridgeFinder app itself is that place. Warning in the event of unexpected behavior that actually happens is a good plan. But this again is something that requires another channel through Vidalia. I doubt most BridgeFinders will have guis :/ We could define a new POSTMESSAGE type "Alert" for example, so Vidalia can inform the user of something fishy on behalf of BridgeFinder? But that brings up localization issues... Do we leave it to BridgeFinder implementations to specify error codes to be sent over POSTMESSAGE, or do we leave it free-form?

4. Exercise care with what is written to disk

BridgeFinder developers must be aware of the following attacks, and ensure that their software does not expose users to any of them:

* An attacker could plant illegal data on a user's computer, to be used later (after a search) as justification to imprison the user.

* An attacker could plant malicious data intended to exploit bugs in processes which automatically inspect all files on a user's disks. (Some examples of such processes are indexing services for filesystem search tools, or anti-virus software.)

* An attacker could plant malicious data intended to exploit code used by a file manager to extract metadata or thumbnails from files.

* An attacker could plant malicious data intended to exploit code run when a user tries to open or view a file. (On Unixoid systems, executable files which are not in a recognized binary format are interpreted by /bin/sh if a user is persuaded to run them. A header is not enough to prevent all attacks of this class; malicious data anywhere within a file could take over a user's computer.)

Note that parties which can be trusted to supply bridges to users should not be trusted with full code-exec privileges on every user's computer. (For example, bridge descriptors are generated and signed by the person who runs a bridge -- but *anyone* can run a bridge and start signing bridge descriptors.)

In order to prevent the above attacks (and others), BridgeFinder MUST NOT create files whose contents (entirely or partially) or names or file extensions are controlled by a party not intended to have full code-exec privileges on every user's computer.

BridgeFinder SHOULD mark data files which are not intended to be executed by the operating system as non-executable, whenever that is possible. (It is not possible when Tor Browser Bundle is run on a FAT filesystem on a Unixoid operating system; that configuration is supported and known to be used.)

One way to avoid the code-exec attacks above is to obfuscate data (using strong cryptography) before writing it to disk. Possible obfuscation methods include 'grizzling' the data [1] (note that the random nonce is important here) or encrypting the data with a newly-generated random key and storing the key with the encrypted data on disk. These do not address the illegal-data attack (because the user is, in theory, able to de-obfuscate and read the data), but they do make it significantly harder for the attacker's goons to 'find' the data during a search.

If a BridgeFinder obfuscates data which it stores on disk, its authors MUST provide a simple program to de-obfuscate the data (with full source code) so that users can find out what data BridgeFinder has collected, and BridgeFinder MUST put a text file named "README.txt" in the directory containing the obfuscated files explaining how to obtain and use the de-obfuscation tool and why such a tool is necessary.

BridgeFinder SHOULD NOT store information to disk which reveals the user's activities in his/her/its non-Tor Browser; some of those activities may not otherwise be visible to a censoring attacker. BridgeFinder MUST NOT store such information to disk unless the user has explicitly asked it to.

5. Exercise care with where things are written to disk

The Tor Browser Bundle is designed to not leave traces that it has been run on a computer outside the directory in which it was unpacked, and, to the extent possible, to mitigate any such traces left by the operating system.

BridgeFinder MUST NOT write data to disk outside the Tor Browser Bundle directory at any time. BridgeFinder MUST NOT use any operating system features which are known to write data to disk outside the Tor Browser Bundle directory.

If BridgeFinderHelper operates as an extension of a program which the user has installed on his/her/its computer, it (or configuration data needed to cause the non-Tor Browser to load it) may need to be installed outside the Tor Browser Bundle directory. However, BridgeFinderHelper SHOULD NOT write data to disk or cause data to be written to disk outside the TBB directory.

BridgeFinderHelper MUST NOT be installed outside the TBB directory, and MUST NOT write data to disk, unless the user has explicitly permitted that.

The above paragraph makes many otherwise useful BridgeFinderHelpers impossible to implement in practice. It also contradicts the preceding paragraph in terms of MUST vs SHOULD. In specific, Chrome addons are installed into the user's Chrome profile directory (unless you run them in 'unpacked' mode, which no one will do). I believe WoW addons are similar wrt restricted installation paths. There likely won't be a way to run BridgeFinderHelper plugins for these platforms from inside of the TBB dir. Unless this is just a typo and you meant BridgeFinder above?

BridgeFinder, BridgeFinderHelper, and their installation routines, MUST warn users that traces written to a disk cannot be erased without erasing the entire filesystem before asking for permission to write outside the TBB directory. (The user has already chosen to leave traces of TBB in the directory it was unpacked into.)

On multi-user operating systems which meaningfully support filesystem permissions on the filesystem containing the Tor Browser Bundle, BridgeFinder MUST set permissions correctly on the files it creates. In particular, when filesystem permissions are available, files containing software meant to be run by BridgeFinder MUST NOT be writable by any other OS-level user than the one running BridgeFinder, and files containing data not intended to be loaded by the operating system as an executable file MUST NOT be marked as executable.

6. Avoid assumptions about BridgeFinder's process environment

BridgeFinder and BridgeFinderHelper MUST NOT allow any data to be sent to their standard output and standard error files. (On Linux, those file descriptors often point to $HOME/.xsession-errors; on MacOS, data sent to an application's stdout or stderr is recorded in /var/log/system.log.)

BridgeFinder and BridgeFinderHelper MUST NOT change their behaviour based on the values or presence of environment variables except as required by IPC protocols which they must conform to. Very few users know that environment variables exist, and many of those who do do not understand how environment variables work. Naive users can easily be conned into setting environment variables which will cause BridgeFinder or BridgeFinderHelper to misbehave.

7. Do not attempt to operate from within Tor Browser

BridgeFinder and BridgeFinderHelper MUST NOT attempt to automatically obtain information about bridges from within Tor Browser. Doing so would allow an attacker to de-anonymize a pseudonymous user by sending pieces of bridge information to him/her/it, or learn about a user's anonymous activities by planting pieces of bridge information on websites of interest to the attacker. (Checking that pieces of bridge information are signed by a party trusted to provide them is not sufficient to defend against this class of attack; signatures on a piece of bridge information do not authenticate metadata such as the web page meant to distribute it or the e-mail address to which it was sent.)

BridgeFinder SHOULD NOT use information obtained by the user through the Tor Browser. If it does, it MUST only use information explicitly provided to BridgeFinder by the user for the purpose of bridge discovery, and it MUST warn the user that maliciously placed bridge information could be used to identify and/or locate users who receive and use it.

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

8. Do not stick beans up the user's nose

Deployed versions of BridgeFinder and BridgeFinderHelper MUST NOT have any debugging features which cause them to log sensitive data to disk. Someone *will* turn them on, whether by accident or by malice.

Development versions of BridgeFinder and BridgeFinderHelper which have such debugging features MUST warn users that they are development builds and should not be used by non-developers.

Requiring users to run special development builds to get any logs is going to mean we won't ever get any logs when things break. I think we're hamstringing ourselves development-wise with this rather silly compile-time requirement. Perhaps instead we should recommend a log scrubbing mechanism similar to the ones used by Tor and Torbutton.

If BridgeFinder and/or BridgeFinderHelper open listening sockets for IPC purposes, those sockets MUST be bound to a loopback address (not to e.g. IPADDR_ANY). Otherwise, They could probe for your IPC socket's presence on a user's computer.

9. Inform BridgeFinder developers about these issues

All documents prepared or promoted by Tor Project, Inc. which are intended to be sufficient for the reader to implement a BridgeFinder must describe the known security considerations for BridgeFinders and their underlying rationales.

The BridgeFinder interface is intended to allow developers who are not experts on Tor, and who may not be aware of the unusual threat models which Tor and Tor Browser Bundle address, to write software which users and distributors will integrate into Tor Browser Bundle. These developers are unlikely to be aware of Tor-specific and BridgeFinder-specific security considerations (e.g. attacks involving malicious bridges), and even developers who are informed about the rules stated above may see the rules as unnecessary and ignore them if their rationales are not explicitly stated.

In general, BridgeFinder developers need to be aware that they are writing security-critical code, with a large set of application-specific security requirements on top of the usual security requirements for all software which interacts with an untrusted network.

1. http://www.cl.cam.ac.uk/~rja14/Papers/grizzle.pdf

-- Mike Perry

On 3/27/12 12:09 PM, Robert Ransom wrote:

It's not a typo. Those BridgeFinderHelpers MUST NOT be installed unless the user has explicitly permitted that they be installed. Even if the user has explicitly permitted that a BridgeFinderHelper be installed and write data to disk, it SHOULD NOT write data to disk if that is not absolutely necessary.

It arise to my mind the idea discussed to provide a Tor HS Data support with some specific level of protection in the hands of the Tor operator: http://www.mail-archive.com/tor-dev@lists.torproject.org/msg00855.html It was an idea to protect Tor HS but it may be extended as a general concept for *ALL* tor related data. Fitting everything into sqlite database protected with sqlcipher (or other methods) that ask the user for a password, would probably mitigate this issue and a lot of other ones that are under the hood. -naif

On 2012-03-22, Mike Perry <mikeperry@torproject.org> wrote:

Thus spake Robert Ransom (rransom.8774@gmail.com):

...

[ snip ]

I've updated the proposal to address your concerns at mikeperry/bridgefinder2.

I've relaxed some of the requirements a little, but I think I still properly cover everything you mentioned.

I missed something: You need to use a protocol name other than “POSTMESSAGE” for the protocol which will be spoken over the POSTMESSAGE transport layer. If you aren't feeling creative, ‘pwgen -0A’ might help. Or look through a list of names of potential bikeshed colors. Robert Ransom