|
|
|
# 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)]] |