Skip to content
GitLab

Linux · Changes

Page history
Update a few pages authored by Gaba's avatar Gaba
Hide whitespace changes
Inline Side-by-side
Sandbox/Linux.md 0 → 100644
View page @ e02d3f24
# 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](https://github.com/projectatomic/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 (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](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
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](https://developer.mozilla.org/en-US/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)]]