docs/linux_sandboxing.md

   1 # Linux Sandboxing
   2
   3 Chromium uses a multiprocess model, which allows to give different privileges
   4 and restrictions to different parts of the browser. For instance, we want
   5 renderers to run with a limited set of privileges since they process untrusted
   6 input and are likely to be compromised. Renderers will use an IPC mechanism to
   7 request access to resource from a more privileged (browser process).
   8 You can find more about this general design
   9 [here](http://dev.chromium.org/developers/design-documents/sandbox).
  10
  11 We use different sandboxing techniques on Linux and Chrome OS, in combination,
  12 to achieve a good level of sandboxing. You can see which sandboxes are currently
  13 engaged by looking at chrome://sandbox (renderer processes) and chrome://gpu
  14 (gpu process).
  15
  16 We have a two layers approach:
  17
  18 *   Layer-1 (also called the "semantics" layer) prevents access to most
  19     resources from a process where it's engaged. The setuid sandbox is used for
  20     this.
  21 *   Layer-2 (also called "attack surface reduction" layer) restricts access from
  22     a process to the attack surface of the kernel. Seccomp-BPF is used for this.
  23
  24 You can disable all sandboxing (for testing) with `--no-sandbox`.
  25
  26 ## Layered approach
  27
  28 One notable difficulty with `seccomp-bpf` is that filtering at the system call
  29 interface provides difficult to understand semantics. One crucial aspect is that
  30 if a process A runs under `seccomp-bpf`, we need to guarantee that it cannot
  31 affect the integrity of process B running under a different `seccomp-bpf` policy
  32 (which would be a sandbox escape). Besides the obvious system calls such as
  33 `ptrace()` or `process_vm_writev()`, there are multiple subtle issues, such as
  34 using `open()` on `/proc` entries.
  35
  36 Our layer-1 guarantees the integrity of processes running under different
  37 `seccomp-bpf` policies. In addition, it allows restricting access to the
  38 network, something that is difficult to perform at the layer-2.
  39
  40 ## Sandbox types summary
  41
  42 | **Name** | **Layer and process** | **Linux flavors where available** | **State** |
  43 |:---------|:----------------------|:----------------------------------|:----------|
  44 | [Setuid sandbox](#The_setuid_sandbox.md) | Layer-1 in Zygote processes (renderers, PPAPI, [NaCl](http://www.chromium.org/nativeclient), some utility processes) | Linux distributions and Chrome OS | Enabled by default (old kernels) and maintained |
  45 | [User namespaces sandbox](#User_namespaces_sandbox.md) | Modern alternative to the setuid sandbox. Layer-1 in Zygote processes (renderers, PPAPI, [NaCl](http://www.chromium.org/nativeclient), some utility processes) | Linux distributions and Chrome OS (kernel >= 3.8) | Enabled by default (modern kernels) and actively developed |
  46 | [Seccomp-BPF](#The_seccomp-bpf_sandbox.md) | Layer-2 in some Zygote processes (renderers, PPAPI, [NaCl](http://www.chromium.org/nativeclient)), Layer-1 + Layer-2 in GPU process | Linux kernel >= 3.5, Chrome OS and Ubuntu | Enabled by default and actively developed |
  47 | [Seccomp-legacy](#The_seccomp_sandbox.md) | Layer-2 in renderers  | All                               | [Deprecated](https://src.chromium.org/viewvc/chrome?revision=197301&view=revision)  |
  48 | [SELinux](#SELinux.md) | Layer-1 in Zygote processes (renderers, PPAPI) | SELinux distributions             | [Deprecated](https://src.chromium.org/viewvc/chrome?revision=200838&view=revision) |
  49 | Apparmor | Outer layer-1 in Zygote processes (renderers, PPAPI) | Not used                          | Deprecated |
  50
  51 ## The setuid sandbox
  52
  53 Also called SUID sandbox, our main layer-1 sandbox.
  54
  55 A SUID binary that will create a new network and PID namespace, as well as
  56 `chroot()` the process to an empty directory on request.
  57
  58 To disable it, use `--disable-setuid-sandbox`. (Do not remove the binary or
  59 unset `CHROME_DEVEL_SANDBOX`, it is not supported).
  60
  61 Main page: [LinuxSUIDSandbox](linux_suid_sandbox.md)
  62
  63 ## User namespaces sandbox
  64
  65 The namespace sandbox
  66 [aims to replace the setuid sandbox](https://crbug.com/312380). It has the
  67 advantage of not requiring a setuid binary. It's based on (unprivileged)
  68 [user namespaces](https://lwn.net/Articles/531114/) in the Linux kernel. It
  69 generally requires a kernel >= 3.10, although it may work with 3.8 if certain
  70 patches are backported.
  71
  72 Starting with M-43, if the kernel supports it, unprivileged namespaces are used
  73 instead of the setuid sandbox. Starting with M-44, certain processes run
  74 [in their own PID namespace](https://crbug.com/460972), which isolates them
  75 better.
  76
  77 ## The `seccomp-bpf` sandbox
  78
  79 Also called `seccomp-filters` sandbox.
  80
  81 Our main layer-2 sandbox, designed to shelter the kernel from malicious code
  82 executing in userland.
  83
  84 Also used as layer-1 in the GPU process. A
  85 [BPF](http://www.tcpdump.org/papers/bpf-usenix93.pdf) compiler will compile a
  86 process-specific program to filter system calls and send it to the kernel. The
  87 kernel will interpret this program for each system call and allow or disallow
  88 the call.
  89
  90 To help with sandboxing of existing code, the kernel can also synchronously
  91 raise a `SIGSYS` signal. This allows user-land to perform actions such as "log
  92 and return errno", emulate the system call or broker-out the system call
  93 (perform a remote system call via IPC). Implementing this requires a low-level
  94 async-signal safe IPC facility.
  95
  96 `seccomp-bpf` is supported since Linux 3.5, but is also back-ported on Ubuntu
  97 12.04 and is always available on Chrome OS. See
  98 [this page](http://outflux.net/teach-seccomp/) for more information.
  99
 100 See
 101 [this blog post](http://blog.chromium.org/2012/11/a-safer-playground-for-your-linux-and.html)
 102 announcing Chrome support. Or
 103 [this one](http://blog.cr0.org/2012/09/introducing-chromes-next-generation.html)
 104 for a more technical overview.
 105
 106 This sandbox can be disabled with `--disable-seccomp-filter-sandbox`.
 107
 108 ## The `seccomp` sandbox
 109
 110 Also called `seccomp-legacy`. An obsolete layer-1 sandbox, then available as an
 111 optional layer-2 sandbox.
 112
 113 Deprecated by seccomp-bpf and removed from the Chromium code base. It still
 114 exists as a separate project [here](https://code.google.com/p/seccompsandbox/).
 115
 116 See:
 117
 118 *   http://www.imperialviolet.org/2009/08/26/seccomp.html
 119 *   http://lwn.net/Articles/346902/
 120 *   https://code.google.com/p/seccompsandbox/
 121
 122 ## SELinux
 123
 124 [Deprecated](https://src.chromium.org/viewvc/chrome?revision=200838&view=revision).
 125 Was designed to be used instead of the SUID sandbox.
 126
 127 Old information for archival purposes:
 128
 129 One can build Chromium with `selinux=1` and the Zygote (which starts the
 130 renderers and PPAPI processes) will do a dynamic transition. audit2allow will
 131 quickly build a usable module.
 132
 133 Available since
 134 [r26257](http://src.chromium.org/viewvc/chrome?view=rev&revision=26257),
 135 more information in
 136 [this blog post](http://www.imperialviolet.org/2009/07/14/selinux.html) (grep
 137 for 'dynamic' since dynamic transitions are a little obscure in SELinux)
 138
 139 ## Developing and debugging with sandboxing
 140
 141 Sandboxing can make developing harder, see:
 142
 143 *   [this page](https://code.google.com/p/chromium/wiki/LinuxSUIDSandboxDevelopment)
 144     for the `setuid` sandbox
 145 *   [this page](http://www.chromium.org/for-testers/bug-reporting-guidelines/hanging-tabs)
 146     for triggering crashes
 147 *   [this page for debugging tricks](linux_debugging.md)
 148
 149 ## See also
 150
 151 *   [LinuxSandboxIPC](linux_sandbox_ipc.md)
 152 *   [How Chromium's Linux sandbox affects Native Client](https://code.google.com/p/nativeclient/wiki/LinuxOuterSandbox)