wiki:doc/TorBrowser/Sandbox/Linux

Version 20 (modified by yawning, 9 months ago) (diff)

Arch Linux's bubblewrap package is in extra now, not AUR.

Linux Sandboxed Tor Browser Documentation

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 #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 "hardened" series with a grsec kernel (ASAN/PaX conflict, not limited to the sandbox).

Functionality that must be explicitly allowed via configuration:

  • Audio support
  • The circuit display
  • Installing/Updating addons from within Tor Browser

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?

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.

For what it's worth, Firefox also requires PulseAudio in recent versions. 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!

For security and privacy reasons this is not recommended.

You need to enable Modifiable Extensions in the sandbox config, for Tor Browser will not be able to write to the addon directory.

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.

How do I protect myself from X exploits?

Good question. "Sit there and pray that Wayland will fix everything" or "Use a nested X11 implementation like Xephyr or Xpra" seem to be the popular options. An advanced configuration option for setting the DISPLAY that Firefox will use is provided for convenience.

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.

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.

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

Ticket Summary Status Owner Keywords Severity Priority
#20773 Stop mounting `/proc` in the various containers once this is feasable. new yawning sandbox-security Normal Medium
#20774 Support foreign language input where possible. new yawning Normal Medium
#20775 Use Tor Browser's integrated `AF_LOCAL` support on alpha. assigned yawning Normal Medium
#20779 Deal with Tor Browser not storing data in the application directory. new yawning Normal Medium
#20783 General `sandboxed-tor-browser` UI/UX improvement catch-all. new yawning Normal Low
#20792 Add more options for changing the install process behavior new yawning Normal Low
#20844 Inform me about sandbox violations new yawning sandbox-security Normal Medium
#20975 Tor Browser fails to launch after update(?) reopened yawning Normal Medium
#21010 Disable RDTSC/RDTSCP to limit side-channel attacks new yawning sandbox-security Normal Medium
#21011 Disable JavaScript JIT new yawning sandbox-security Normal Medium
#21089 Download updates in the background. new yawning sandbox-update Normal Medium
#21090 Integrate the update check/download/apply steps with torbutton. new yawning sandbox-update Normal Medium
#22925 Make the extension whitelist public key cryptography based. new yawning Normal Medium
#22933 Deprecate the extra codecs option. new yawning Normal Medium
#22946 Implement a MAR decompressor/delta updater. new yawning Normal Medium
#22950 Filter out X11 root window property queries. new yawning sandbox-fingerprinting Normal Medium
#22969 Figure out all the other ways that Firefox phones home, and kill them with fire if possible. accepted yawning sandbox-fingerprinting sandbox-security Normal Medium
#23265 Make addon update failures more obvious somehow. new yawning Normal Medium