commit bf286a049cd06b4546f9cd02f390f4c60e0d0c51
Author: Yawning Angel <yawning(a)schwanenlied.me>
Date: Sat Nov 26 07:58:42 2016 +0000
Update the Architecture.txt doc a bit (No functional changes).
The doc should be moderately accurate now, but in all honesty could do
with a total re-write.
---
doc/Architecture.txt | 72 ++++++++++++++++++++++++++++++++++------------------
1 file changed, 48 insertions(+), 24 deletions(-)
diff --git a/doc/Architecture.txt b/doc/Architecture.txt
index 6714bbc..0a5c789 100644
--- a/doc/Architecture.txt
+++ b/doc/Architecture.txt
@@ -18,7 +18,7 @@ Design requirements:
neither.
* Proxy bypass MUST BE impossible without a sandbox escape, even if
- the adversary gets RCE capability.. This is harder than it appears,
+ the adversary gets RCE capability. This is harder than it appears,
and influences a few other thoughts.
* The firefox process's write access to the filesystem MUST be limited
@@ -56,13 +56,29 @@ sandboxed-tor-browser is a Go application that handles:
* Downloading and installing Tor Browser.
- * Fetches and installs the latest Tor Browser over Tor.
+ * Fetches and installs the latest Tor Browser over Tor, or the normal
+ internet, depending on of Tor is already running as a system service.
+ * The TLS cert for the download metadata fetch (`downloads.json`) is
+ validated via static HPKP pins. The actual downloads can come from
+ anywhere (allowing the possibility for CDNs/mirrors).
* Validates the PGP signature with a hard coded copy of the PGP key.
+ * Running a sandboxed instance of the tor daemon.
+
+ * Launches the bundle's tor daemon inside a sandbox.
+ * A seccomp whitelist is used unless pluggable transports are enabled, in
+ which case a blacklist is used.
+ * This process has full network access, but an extremely limited view into
+ the host filesystem.
+ * For the initial release only pluggable transports supported by obfs4proxy
+ are enabled.
+ * Libraries are handled in a similar manner to how they are for the firefox
+ container (as in, only what is needed, nothing more).
+
* Updating Tor Browser.
- * Version check over Tor on launch, validating the `dist.torproject.org`
- cert with an internal copy.
+ * Version check over Tor on launch. Static HPKP pins are used to ensure
+ the remote update metadata server is trusted.
* Download MAR format updates over Tor.
* Validates the MAR signature with hard coded copies of the MAR signing
key(s).
@@ -72,34 +88,42 @@ sandboxed-tor-browser is a Go application that handles:
* Run a sandboxed instance of Tor Browser.
- * (FIXME) Assumes a system Tor instance.
* A LD_PRELOAD stub is used to force firefox to use AF_LOCAL sockets for
- the control and SOCKS ports. This will go away when all released channels
- of the browser support AF_LOCAL socket access.
+ the control and SOCKS ports, and to work around certain Firefox quirks
+ and bugs.
* Uses bubblewrap to instantiate a Linux container.
- * seccomp2 system call filter.
+ * seccomp2 system call filter, with whitelist/blacklist format that is
+ compatible with Subgraph.
* Separate PID table, mount table, etc.
* No external communication except via stdio, and path based AF_LOCAL
sockets.
- * Normalized hostname, `/etc/passwd`, `/etc/group`.
+ * Normalized hostname, `/etc/passwd`, `/etc/group`, D-bus machine ID.
* Limited view of the host filesystem, all directories read-only unless
* otherwise specified. The sandboxed filesystem layout is normalized
as much as possible.
- * System library directories.
+ * System libraries are explcitly bind mounted into the container in
+ standardized locations to reduce attack surface and to make it hard
+ to use the installed libraries to gain much insight into the host
+ system. This is accomplished via reading the ELF dynamic section of
+ the binary to be executed, and then mounting a breadth-first-search
+ with the assistance of the `/etc/ld.so.cache` file.
* Gtk Theme related directories.
- * The X11 AF_LOCAL socket.
- * (Optionally) The PulseAudio socket.
- * The browser directory.
- * The browser caches directory (read/write, might be removed).
- * The browser profile directory (read/write, extensions sub-dir
- read-only unless overriden by the user).
- * The browser downloads directory (read/write)
- * The browser desktop directory (read/write)
- * A runtime directory.
- * A surrogate control port that gives "fake" responses to Tor
- Browser. Does not talk to the real control port.
- * A re-dispatching SOCKS proxy that allows "New Identity" to work,
- that talks to the actual tor instance.
+ * The X11 AF_LOCAL socket.
+ * (Optionally) The PulseAudio socket.
+ * The browser directory.
+ * The browser caches directory (read/write, might be removed).
+ * The browser profile directory (read/write, extensions sub-dir
+ read-only unless overriden by the user).
+ * The browser downloads directory (read/write)
+ * The browser desktop directory (read/write)
+ * A runtime directory.
+ * A surrogate control port that gives "fake" responses to Tor
+ Browser. The bare minimum to get a fully functional circuit
+ display is implemented, and the surrogate ensures that responses
+ are filtered appropriately so that Tor Browser never sees streams
+ or circuits that it is not responsible for.
+ * A re-dispatching SOCKS proxy, required to identify which streams
+ and circuits should be visible to the control port surrogate.
Sandbox weaknesses:
@@ -114,7 +138,7 @@ from a security standpoint things are vastly improved.
* X processes can easily become display server wide keyloggers and other
things that threaten user privacy.
* Certain applications set X root window properties that leak information
- about the host system.
+ about the host system (eg: PulseAudio).
Using a nested X solution such as Xephyr "just works", so that's a way to
mitigate this for those that want that.