Linux Sandboxed Tor Browser Documentation
Table of Contents
- Where do I get bubblewrap for my distribution?
- How do I check the hash/signature of the bundle archive?
- Where are all my files?
- Where do my downloads go?
- How do I reinstall the browser?
- How do I reconfigure the tor or the sandbox?
- How do I get sound to work?
- The Circuit Display is missing!
- "Check for Tor Browser Update..." is missing!
- Are the fonts supposed to look different from normal?
- Installing addons doesn't work, help!
- How do I edit the torrc?
- How do I protect myself from X exploits?
- How do I make this use a system tor instance?
- How do I disable the update check/auto update?
- How do I install Flash/Siverlight/etc?
- What happened to x86 (32 bit Intel) support?
- Design Goals
The current efforts towards sandboxing Tor Browser on Linux are centered around sandboxed-tor-browser and bubblewrap.
Note: This documentation refers to the master git branch, which may be ahead of tagged revisions.
Building sandboxed-tor-browser requires:
- A C compiler with development libraries for Gtk+3, libnotify, and X11.
- gb (https://getgb.io/)
- Go (Tested with 1.7.x)
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
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.
Where do I get bubblewrap for my distribution?
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.
How do I reconfigure the tor or the sandbox?
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.
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.
- 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.
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/
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.
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.