[tbb-dev] Tor Browser TorLauncher Proposal

Matthew Finkel matthew.finkel at gmail.com
Tue Jan 16 23:09:47 UTC 2018

On Wed, Jan 10, 2018 at 03:57:16PM +0000, Yawning Angel wrote:
> Hello,
> This will be me beating one of my favorite dead horses about how
> a TorLauncher extension shouldn't exist at all.  Feel free to ignore
> it, because it doesn't directly pertain to all the API mapping things
> in the proposal, but if you're going to do a mountain of work, maybe
> think about fixing the design.

Thanks for outlining this. So, yes, I agree (and it is something I
thought about). This proposal was specifically for how we move from
the current implementation using a XPCOM-based extention to an
implementation that only uses WebExtensions (where needed).

As you mentioned, the current design is not ideal and it may be worth
using this opportunity for changing it. How we implement this
such that it balances the isolation/usability/complexity differential
seems to be an open question.

The Android model, where Orbot is a separate App and runs as a separate
user in a semi-isolated environment, is a safer design, but it leads
toward usability problems. In addition, the Android model isn't
directly applicable/practical in general on the other platforms.

I put some thoughts into how we can pick up where the sandboxed tor
browser left off. If we go down that route, we'll have a significant
amount of scope-creep. I don't know what engineering effort we can
afford. With that said, and knowing if we are going to do this right
then we need cover Windows, OS X, and Android, we can consider a
slightly different design. It won't provide sufficent sandboxing, but
in reality we can't rely on OS-specific sandboxing functionality in any
way at this point.

As a modification to the previous proposal:

0. TorLauncher V.2

  TorLauncher-v2 refers to an external component in this new design.
  This design attempts to avoid the same pitfalls we experienced with
  Vidalia/TBB considering we already learned how it can fail. If we
  want Tor Browser to be usable, then tor integration must be seamless,
  and the complexity must be hidden from the user. As a result, Firefox
  should be the only window with which the user interacts (or thinks
  they interact).

  TorLauncher-v2 does not introduce sandboxing in addition to the
  sandboxing already provided in Firefox, but TorLauncher-v2 could
  provide this in the future. The immediate goal is providing
  transparent process isolation between tor and firefox processes, and
  reducing the amount of information leakage between components.

  In this design, TorLauncher is split into three parts. The first part
  is integrated into the TorButton WebExtension. The second part is a
  new XPCOM service implementing a simple IPC protocol using unnamed or
  anonymous pipes or Intents (depending on the platform). The third
  part, on desktop, is a new XUL application that handles all tor
  configuration, monitoring and controlling, and it provides the UI for
  adjusting the configuration. On Android, a new UI is needed and this
  is handled by Activities and another background service.

1. The Components

  There are four components:
    - Firefox
    - tor
    - TorLauncher-v2
      - The background/UI program that launches/configures tor
    - TorButton-ext
      - This is the TorButton UI WebExtension, integrating firefox and

2. Seamless Integration

  On Desktop, Firefox/XUL remain the User Interface of Tor Browser.
  Mozilla put significant resources into making Firefox usable, we
  should continue taking advantage of this.

  On Android, the Firefox UI was reimplemented, we'll need do the same
  for the TorLauncher-v2 UI.

2.5. Note on Desktop vs Android

  Due to the different implementation requirements on desktop and
  android, the details here are described from the desktop-centric
  perspective. Whenever it mentions "external application" (or
  similar) this implies a "background service" on Android. Any mention
  of XUL or the TorLauncher-v2 UI implies the Java implementation on
  Android. Unfortunately, explicitly distinguishing between the two
  platforms complicates this document.

3. TorLauncher High-level Implementation

  TorLauncher-v2 is implemented as an external application, providing
  OS-level process/address-space isolation between Firefox and
  TorLauncher. It is implemented using XUL, so from the user's
  perspective TorLauncher is still part of Firefox.

  As expected, TorLauncher-v2 executes tor and firefox when it is
  launched. First, it will launch tor, and if tor successfully
  bootstraps then it launches firefox.

4. Tor Controller

  TorLauncher-v2 implements the Tor Controller functionality and it
  communicates directly with the tor process controlport/socket.

5. Tor Owning Process

  TorLauncher-v2 is the only process that controls and configures tor.

6. Sharing State Between TorLauncher and Firefox

  TorLauncher-v2 provides structured read-only shared memory where tor's
  status is available. TorLauncher-v2 will never read from this shared
  memory, it only writes there. This structured memory will provide the
  current state of bootstraping, details of existing circuits, indicate
  if there is an error, last known/seen successful connection, etc

7. TorLauncher-v2 and Firefox Communication

  TorLauncher-v2 and Firefox will communicate over unnamed/anonymous
  pipes established when TorLauncher-v2 executes firefox. As it
  currently exists, TorButton-ext provides the UI button for opening
  the "Network Settings" UI. This does not change. When the button is
  clicked, TorButton will send a message over the pipe (see below) to
  TorLauncher-v2 requesting it show the "Network Settings" UI. This is
  similar to the current implementation where TorLauncher registers an
  observer for the "TorOpenNetworkSettings" topic and shows the UI when
  the observer is triggered.

  The communication over these pipes should use a very simple protocol.
  TorLauncher-v2 only accepts a small set of pre-defined commands. This
  includes all functionality TorButton needs. As an example,
  "New Identity" will flow from TorButton to an XPCOM service (9. below)
  across the pipe to TorLauncher-v2, then it will reach tor by the

8. TorLauncher-v2 UI

  The TorLauncher-v2 UI provides the same functionality as the
  TorLaucher extension currently provides this. By using XUL, we can
  provide the same look and feel as Firefox, thus a user need not know
  they are interacting with another process. The TorButton popup
  drop-down menu will still contain "Tor Network Settings...", but the
  UI will come from the TorLauncher-v2 process instead of firefox.

9. New XPCOM Service

  A new XPCOM service is implement in Firefox providing connectivity
  between the TorLaucher-v2 pipes and the Firefox/TorButton-ext
  extension. This XPCOM service also reads the shared memory segment
  described in (5) and provides this information for affecting UI
  changes. The service allows observers of tor state changes.


  On Unix-like systems (except Android), Firefox should only make
  AF_UNIX connections, AF_INET/AF_INET6 should not be available. On
  Windows, Firefox only makes AF_INET/AF_INET6 connections on the
  loopback or localhost addresses. On Android, Firefox communicates
  with the background tor service via Intent (*this needs performance
  measurements*). These restrictions are enabled at
  'mach configure'-time and enforced by compile-time logic

11. A Diagram

  |                 |
  |         --------------------------------
  |      -->|    Firefox                   |
  |      |  |                              |
  |      |  |     ----------------------   |
  |      |  |     |   TorButton-ext    |   |
  |      |  |     ----------------------   |
  |      |  --------------|-----------------
  |      |                |
  |      |                | Triggers UI prompts
  |      |                |
  |   ------              |
  |   |shm |     ----------
  |   ------     |
  |      ^       v
  |      |  ---------------------
  |      ---|  TorLauncher-v2   |
  |         ---------------------
  |                 ^
  |                 |
  |                 | ControlPort/Socket Connection
  |                 |
  |                 v
  |             ----------
  ------------->|  Tor   |

  Arrows indicate the flow of information, this may be uni- or bi-directional.

More information about the tbb-dev mailing list