|
|
= Linux Sandboxed Tor Browser Documentation =
|
|
|
# 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.'''
|
... | ... | @@ -9,18 +9,18 @@ |
|
|
'''WARNING: Active development is on indefinite hiatus. DO NOT EXPECT ANY SIGNIFICANT
|
|
|
NEW FEATURES OR IMPROVEMENTS'''.
|
|
|
|
|
|
[[TOC]]
|
|
|
|
|
|
|
|
|
The current efforts towards sandboxing Tor Browser on Linux are centered
|
|
|
around `sandboxed-tor-browser` and [https://github.com/projectatomic/bubblewrap bubblewrap].
|
|
|
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.'''
|
|
|
**Note: This documentation refers to the `master` git branch, which may be ahead of tagged revisions.**
|
|
|
|
|
|
== Dependencies ==
|
|
|
## Dependencies
|
|
|
|
|
|
=== Build ===
|
|
|
### Build
|
|
|
|
|
|
Building `sandboxed-tor-browser` requires:
|
|
|
|
... | ... | @@ -29,7 +29,7 @@ Building `sandboxed-tor-browser` requires: |
|
|
* gb (https://getgb.io/)
|
|
|
* Go (Tested with 1.7.x)
|
|
|
|
|
|
=== Runtime ===
|
|
|
### Runtime
|
|
|
|
|
|
Running `sandboxed-tor-browser` requires:
|
|
|
|
... | ... | @@ -40,7 +40,7 @@ Running `sandboxed-tor-browser` requires: |
|
|
* (Optional) The Adwaita Gtk+-2.0 theme (Install `gnome-themes-standard` on Ubuntu).
|
|
|
* (Optional) libnotify
|
|
|
|
|
|
=== Broken functionality ===
|
|
|
### 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
|
... | ... | @@ -71,50 +71,51 @@ Functionality that must be explicitly allowed via configuration: |
|
|
|
|
|
New features will be judged on a case by case basis.
|
|
|
|
|
|
== FAQ ==
|
|
|
## FAQ
|
|
|
|
|
|
=== Where do I get bubblewrap for my distribution? ===
|
|
|
### 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 ||
|
|
|
| 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? ===
|
|
|
### 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? ===
|
|
|
### 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? ===
|
|
|
### 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? ===
|
|
|
### How do I reinstall the browser?
|
|
|
|
|
|
'''This will permanently delete your previous browser installation.'''
|
|
|
**This will permanently delete your previous browser installation.**
|
|
|
|
|
|
`sandboxed-tor-browser install`
|
|
|
|
|
|
=== How do I reconfigure the tor or the sandbox? ===
|
|
|
### 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? ===
|
|
|
### How do I get sound to work?
|
|
|
|
|
|
'''WARNING: This is likely unsafe against sophisticated adversaries.'''
|
|
|
**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
|
... | ... | @@ -133,7 +134,7 @@ 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! ===
|
|
|
### 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
|
... | ... | @@ -142,18 +143,18 @@ 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! ===
|
|
|
### "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? ===
|
|
|
### 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! ===
|
|
|
### Installing addons doesn't work, help!
|
|
|
|
|
|
This is a bad idea for security and privacy reasons and is not supported at all.
|
|
|
|
... | ... | @@ -161,13 +162,13 @@ 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? ===
|
|
|
### 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? ===
|
|
|
### 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.
|
... | ... | @@ -188,9 +189,9 @@ will use is provided to enable easier nested X11 usage. |
|
|
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? ===
|
|
|
### How do I make this use a system tor instance?
|
|
|
|
|
|
'''Using `sandboxed-tor-browser` in this way is not recommended.'''
|
|
|
**Using `sandboxed-tor-browser` in this way is not recommended.**
|
|
|
|
|
|
`TOR_CONTROL_PORT=9051 sandboxed-tor-browser`
|
|
|
|
... | ... | @@ -198,12 +199,12 @@ the threat model.) |
|
|
|
|
|
`TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser`
|
|
|
|
|
|
=== How do I disable the update check/auto update? ===
|
|
|
### 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? ===
|
|
|
### How do I install Flash/Siverlight/etc?
|
|
|
|
|
|
Your tears are delicious, and your plugins will burn.
|
|
|
|
... | ... | @@ -211,7 +212,7 @@ 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? ===
|
|
|
### 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
|
... | ... | @@ -220,17 +221,17 @@ resource limitations. |
|
|
|
|
|
See #20940 for more details.
|
|
|
|
|
|
== Design Goals ==
|
|
|
## Design Goals
|
|
|
|
|
|
* Modern Linux kernels without `USER_NS` support '''MUST''' be capable of
|
|
|
* 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
|
|
|
* 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
|
|
|
* 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
|
|
|
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
|
... | ... | @@ -238,17 +239,17 @@ See #20940 for more details. |
|
|
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 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
|
|
|
* 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 ==
|
|
|
## Implementation
|
|
|
|
|
|
=== `sandboxed-tor-browser` ===
|
|
|
### `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.
|
... | ... | @@ -257,7 +258,7 @@ 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
|
|
|
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory specification],
|
|
|
[XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
|
|
|
honoring the appropriate overrides.
|
|
|
|
|
|
* Config: `~/.config/sandboxed-tor-browser/`
|
... | ... | @@ -265,7 +266,7 @@ honoring the appropriate overrides. |
|
|
* Tor `DataDir`: `~/.local/share/sandboxed-tor-browser/tor/`
|
|
|
* Runtime files (eg: sockets): `/var/run/$UID/sandboxed-tor-browser/`
|
|
|
|
|
|
==== Installer ====
|
|
|
#### Installer
|
|
|
|
|
|
`sandboxed-tor-browser` includes the capability to download and install the
|
|
|
latest version of Tor Browser.
|
... | ... | @@ -279,7 +280,7 @@ latest version of Tor Browser. |
|
|
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 [https://developer.mozilla.org/en-US/Firefox/Enterprise_deployment Firefox Enterprise Deployment]
|
|
|
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
|
... | ... | @@ -287,7 +288,7 @@ latest version of Tor Browser. |
|
|
latter will not work by default due to filesystem permissions in the
|
|
|
sandbox container.
|
|
|
|
|
|
==== Updater ====
|
|
|
#### Updater
|
|
|
|
|
|
`sandboxed-tor-browser` handles keeping the installed bundle up to date,
|
|
|
as the bundle directory is mounted read-only inside the firefox container
|
... | ... | @@ -313,7 +314,7 @@ built in updater. |
|
|
|
|
|
* Re-installs the config overrides after each update.
|
|
|
|
|
|
==== tor daemon interface ====
|
|
|
#### 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
|
... | ... | @@ -341,7 +342,7 @@ and firefox sandbox containers (or the system tor and the firefox container). |
|
|
can use other applications with the sandboxed tor daemon (nb: Some
|
|
|
weirdness with torsocks and the pass-through proxy, needs investigation.).
|
|
|
|
|
|
==== Sandbox container launcher ====
|
|
|
#### 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
|
... | ... | @@ -361,6 +362,6 @@ interface code also includes: |
|
|
|
|
|
* Other misc routines for handling gtk+, PulseAudio, and other things.
|
|
|
|
|
|
== Tickets ==
|
|
|
## Tickets
|
|
|
|
|
|
[[TicketQuery(component=Applications/Tor Browser Sandbox,order=id,status=!closed,format=table,col=id|summary|status|owner|keywords|severity|priority)]] |