Skip to content
Snippets Groups Projects

Linux

Last edited by Gaba

Linux Sandboxed Tor Browser Documentation

'''WARNING: This project is no longer maintained. DO NOT EXPECT ANY FURTHER FIXES, INCLUDING SECURITY AND STOP USING THIS AS SOON AS POSSIBLE.'''

'''WARNING: There are several unresolved issues that affect security and fingerprinting. Do not assume that this is perfect, merely "an improvement over nothing".'''

'''WARNING: Active development is on indefinite hiatus. DO NOT EXPECT ANY SIGNIFICANT NEW FEATURES OR IMPROVEMENTS'''.

The current efforts towards sandboxing Tor Browser on Linux are centered around sandboxed-tor-browser and bubblewrap.

Code: https://gitweb.torproject.org/tor-browser/sandboxed-tor-browser.git/

Note: This documentation refers to the master git branch, which may be ahead of tagged revisions.

Dependencies

Build

Building sandboxed-tor-browser requires:

  • Make
  • A C compiler with development libraries for Gtk+3, libnotify, and X11.
  • gb (https://getgb.io/)
  • Go (Tested with 1.7.x)

Runtime

Running sandboxed-tor-browser requires:

  • A modern Linux system on the x86_64 architecture.
  • bubblewrap >= 0.1.3 (https://github.com/projectatomic/bubblewrap).
  • Gtk+ >= 3.14.0
  • (Optional) PulseAudio
  • (Optional) The Adwaita Gtk+-2.0 theme (Install gnome-themes-standard on Ubuntu).
  • (Optional) libnotify

Broken functionality

It is the aim to provide as much of the standard Tor Browser functionality as possible, while improving security. However, some things are broken by the sandbox, either intentionally, inadvertently, or optionally.

Inadvertent broken things that will be fixed:

  • Foreign language input that requires system services like I-Bus (#20774)
  • The meek pluggable transport (#20781)
  • Check for Tor Browser Update... (#21091 (closed) #21090)

Broken things that are unlikely to ever be supported:

  • The FTE pluggable transport
  • Hardware accelerated 3D rendering (Requires a dangerous amount of hardware access, software rendering is allowed)
  • Printing, except to a file (No network interface in the container)
  • Using Tor Browser to connect to something that isn't the Tor Network.
  • Using the (now deprecated) "hardened" series with a grsec kernel (ASAN/PaX conflict, not limited to the sandbox).
  • Installing/Updating addons (The extensions bundled with Tor Browser are explicitly and individually exposed to the container as read-only files).

Functionality that must be explicitly allowed via configuration:

  • Audio support
  • The circuit display

New features will be judged on a case by case basis.

FAQ

Where do I get bubblewrap for my distribution?

Distribution Where
Arch Linux https://www.archlinux.org/packages/extra/x86_64/bubblewrap/
Debian (jessie) https://packages.debian.org/jessie-backports/admin/bubblewrap
Debian (stretch) https://packages.debian.org/stretch/bubblewrap
Fedora https://admin.fedoraproject.org/pkgdb/package/rpms/bubblewrap/
Ubuntu http://packages.ubuntu.com/yakkety/bubblewrap

How do I check the hash/signature of the bundle archive?

sandboxed-tor-browser does that for you, with a hardcoded copy of the Tor Browser Developer's PGP key as part of the install process.

Where are all my files?

The Tor Browser process does not see all of your files, to prevent an attacker that has compromised your browser from reading them all.

Improving the UI/UX surrounding this is a task for future versions.

Where do my downloads go?

By default ~/.local/share/sandboxed-tor-browser/tor-browser/Browser/Downloads. This can be overridden (along with the Desktop directory) via the sandbox config when advanced options are enabled.

How do I reinstall the browser?

This will permanently delete your previous browser installation.

sandboxed-tor-browser install

How do I reconfigure the tor or the sandbox?

sandboxed-tor-browser config

Certain "advanced" options require: sandboxed-tor-browser --advanced config

How do I get sound to work?

WARNING: This is likely unsafe against sophisticated adversaries.

As it stands right now, if PulseAudio is enabled in the sandbox, Firefox will get direct access to the host system's socket. There are likely non-trivial ways to use this to read files from the host filesystem.

(Thanks to "Jann Horn of Google Project Zero" for pointing out that this is a possibility.)

If you don't care about this possibility, assuming your system is running PulseAudio (pulseaudio --check -v), enable it via the sandbox config. PulseAudio is required due to the sandbox container not having direct access to hardware, and there being basically nothing better despite the potential escape vectors.

For what it's worth, un-sandboxed Tor Browser also requires PulseAudio as of version 7.0, due to it being made a requirement for Firefox (See: https://bugzilla.mozilla.org/show_bug.cgi?id=1247056)

The Circuit Display is missing!

Unless it is explicitly enabled via the sandbox config, the Circuit Display is disabled, as that requires exposing more information to the firefox process than would otherwise be needed.

It should be disabled unless you are comfortable with the idea that firefox knows the IP address of your Guard or Bridges.

"Check for Tor Browser Update..." is missing!

Making it work again is a task for a future version. As of version 0.0.3-dev, updates are checked every 2 hours in the background and a notification is sent if your system supports it prompting you to restart the update.

Are the fonts supposed to look different from normal?

To reduce fingerprinting, only the fonts that are bundled with Tor Browser are used to display content and the UI.

Installing addons doesn't work, help!

This is a bad idea for security and privacy reasons and is not supported at all.

As of version 0.0.11-dev, the sandbox takes extra steps to ensure that only addons that are bundled with Tor Browser by default are exposed to the container as a security measure.

How do I edit the torrc?

That ability is not provided at this time. The tor daemon launched by sandboxed-tor-browser uses it's own torrc and does not honor the one contained in the bundle directory.

Wait, Firefox uses X11, isn't security basically hopeless?

Yes. The current implementation of the sandbox does little to nothing to defend against Firefox doing evil things to or via the X socket.

If you want to attempt to mitigate this, the best options are:

  • Run 0.0.8-dev or newer, where "something, but not likely enough" is done to defend against some of the easier evil.
  • Use a nested X11 implementation like Xephyr or Xpra.
  • Sit there and pray that Wayland will fix everything.

The ideal solution at current time is probably to probably do all three.

An advanced configuration option for setting the DISPLAY that Firefox will use is provided to enable easier nested X11 usage.

(Thanks to "Jann Horn of Google Project Zero" for pointing out that the documentation doesn't make it obvious that such things are beyond the threat model.)

How do I make this use a system tor instance?

Using sandboxed-tor-browser in this way is not recommended.

TOR_CONTROL_PORT=9051 sandboxed-tor-browser

TOR_CONTROL_PORT=tcp://127.0.0.1:6969 sandboxed-tor-browser

TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser

How do I disable the update check/auto update?

You don't. This software is for users that want extra security, and running out of date versions runs counter to that goal.

How do I install Flash/Siverlight/etc?

Your tears are delicious, and your plugins will burn.

More concretely, the sandbox only exposes system calls and shared libraries that are required for Tor Browser's functionality, and getting binary plugins to work would likely require loosening those restrictions.

What happened to x86 (32 bit Intel) support?

While early revisions of the software including the 0.0.2 release supported x86, the decision was made to remove support due to several factors including reduced effectiveness due to platform/OS limitations, declining userbase, and development resource limitations.

See #20940 for more details.

Design Goals

  • Modern Linux kernels without USER_NS support MUST be capable of supporting the sandboxed Tor Browser.

  • Proxy bypass MUST be impossible without a sandbox escape, even if the adversary gets RCE capability.

  • The firefox process's write access to the filesystem MUST be limited to the user preferences, download directory and the bookmarks. The firefox process's read access to the filesystem SHOULD be limited to the Tor Browser installation directory.

    There is a UX tradeoff here in that, without access to at least the user's home directory, uploading things is difficult, but there's a lot of data a potentially malicious firefox executable can get at if it can read from the entire home directory.

  • The firefox process MUST NOT be responsible for launching the tor instance. The tor process MUST live in a separate sandbox, with no access to user data (ie: tor MUST only be able to see it's DataDir).

  • The firefox process MUST NOT be responsible for updating Tor Browser. The downloads MUST be fetched over tor, and a more permissive sandbox spawned to handle updating.

Implementation

sandboxed-tor-browser

A user interface based on Gtk+ is provided to control installing/updating Tor Browser and to assist in configuring the tor daemon and sandbox.

Gtk+3.0 was used despite Tor Browser linking against 2.0 to avoid the need for a future migration.

Files are placed in accordance with the XDG Base Directory specification, honoring the appropriate overrides.

  • Config: ~/.config/sandboxed-tor-browser/
  • Bundle: ~/.local/share/sandboxed-tor-browser/tor-browser
  • Tor DataDir: ~/.local/share/sandboxed-tor-browser/tor/
  • Runtime files (eg: sockets): /var/run/$UID/sandboxed-tor-browser/

Installer

sandboxed-tor-browser includes the capability to download and install the latest version of Tor Browser.

  • Supports all of the channels and locales for a given architecture.

  • Supports doing the download over tor, assuming a system tor instance is present, and the TOR_CONTROL_PORT env var is set.

  • Also downloads the PGP signature of the bundle, and verifies it prior to installation with a hardcoded copy of the PGP key.

  • Modifies the bundle configuration post-install via writing out a set of configuration files using the Firefox Enterprise Deployment infrastructure.

    This is needed so that the built in auto updater, and addon updating can be disabled, as the former is handled by sandboxed-tor-browser and the latter will not work by default due to filesystem permissions in the sandbox container.

Updater

sandboxed-tor-browser handles keeping the installed bundle up to date, as the bundle directory is mounted read-only inside the firefox container while the browser is actually running, precluding the ability to use the built in updater.

  • Checks and downloads updates over tor, launching tor in a container if required. Never uses the clear net for either. As of 0.0.3, Onion Services administered by the Tor Project are used for metadata.

  • Checks approximately every two hours in the background, and may check at launch.

  • Uses libnotify if present to notify the user that an update is available.

  • Independently validates the MAR signature prior to updating, with hardcoded copies of the signing keys.

  • Supports both full and incremental updates, favoring incremental.

  • Updates are done in a container with no network access, X11, or other things that are part of the firefox and tor containers.

  • Re-installs the config overrides after each update.

tor daemon interface

sandboxed-tor-browser can either use an existing tor daemon, or launch one in a sandbox container, and is responsible for routing traffic between the tor and firefox sandbox containers (or the system tor and the firefox container).

  • Interface to the system tor instance if one is configured.

  • Launches the tor daemon in a container with a auto-generated torrc based on the user configuration.

  • A SOCKS5 server that firefox talks to, that rewrites the SOCKS authentication (needed to isolate circuit/stream status information visible to the firefox process via the Tor Control Port).

  • A filtering Tor Control Port that firefox talks to. This provides the minimum subset of events/commands required for "New Identity" and (optionally, only if enabled) the circuit display to function.

    Due to the re-writing of SOCKS5 authentication info, even if a system Tor is used, the firefox process never sees circuits or streams it is not responsible for.

  • When sandboxed-tor-browser launches the tor, a SOCKS5 pass-through proxy is provided at the traditional address (127.0.0.1:9150) so that the user can use other applications with the sandboxed tor daemon (nb: Some weirdness with torsocks and the pass-through proxy, needs investigation.).

Sandbox container launcher

sandboxed-tor-browser launches the various sandbox containers by fork() and exec()ing bubblewrap and passing it various arguments and static assets over pipes.

Each container is different, and will be describe in a separate section. The interface code also includes:

  • A seeccomp rule loader, that loads pre-compiled seccomp-bpf rules.

  • A dynamic linker cache parser (/etc/ld.so.conf) along with routines used to enumerate the libraries required from the host system inside the container for the binaries that are to be executed.

  • A ~/.Xauthority parser and generator, so that only the current target $DISPLAY is exposed in the container.

  • Other misc routines for handling gtk+, PulseAudio, and other things.

Tickets

[[TicketQuery(component=Applications/Tor Browser Sandbox,order=id,status=!closed,format=table,col=id|summary|status|owner|keywords|severity|priority)]]

Comments

    Please register or sign in to add a comment.