commit bf286a049cd06b4546f9cd02f390f4c60e0d0c51 Author: Yawning Angel yawning@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.