docs/linux_suid_sandbox.md

   1 # Linux `SUID` Sandbox
   2
   3 With [r20110](https://crrev.com/20110), Chromium on Linux can now sandbox its
   4 renderers using a `SUID` helper binary. This is one of
   5 [our layer-1 sandboxing solutions](linux_sandboxing.md).
   6
   7 ## `SUID` helper executable
   8
   9 The `SUID` helper binary is called `chrome_sandbox` and you must build it
  10 separately from the main 'chrome' target. To use this sandbox, you have to
  11 specify its path in the `linux_sandbox_path` GYP variable. When spawning the
  12 [zygote process](linux_zygote/md), if the `SUID` sandbox is enabled, Chromium
  13 will check for the sandbox binary at the location specified by
  14 `linux_sandbox_path`. For Google Chrome, this is set to
  15 `/opt/google/chrome/chrome-sandbox`, and early version had this value hard coded
  16 in `chrome/browser/zygote_host_linux.cc`.
  17
  18
  19 In order for the sandbox to be used, the following conditions must be met:
  20
  21 *   The sandbox binary must be executable by the Chromium process.
  22 *   It must be `SUID` and executable by other.
  23
  24 If these conditions are met then the sandbox binary is used to launch the zygote
  25 process. Once the zygote has started, it asks a helper process to chroot it to a
  26 temp directory.
  27
  28 ## `CLONE_NEWPID` method
  29
  30 The sandbox does three things to restrict the authority of a sandboxed process.
  31 The `SUID` helper is responsible for the first two:
  32
  33 *   The `SUID` helper chroots the process. This takes away access to the
  34     filesystem namespace.
  35 *   The `SUID` helper puts the process in a PID namespace using the
  36     `CLONE_NEWPID` option to
  37     [clone()](http://www.kernel.org/doc/man-pages/online/pages/man2/clone.2.html).
  38     This stops the sandboxed process from being able to `ptrace()` or `kill()`
  39     unsandboxed processes.
  40
  41 In addition:
  42
  43 *   The [Linux Zygote](linux_zygote.md) startup code sets the process to be
  44     _undumpable_ using
  45     [prctl()](http://www.kernel.org/doc/man-pages/online/pages/man2/prctl.2.html).
  46     This stops sandboxed processes from being able to `ptrace()` each other.
  47     More specifically, it stops the sandboxed process from being `ptrace()`'d by
  48     any other process. This can be switched off with the
  49     `--allow-sandbox-debugging` option.
  50
  51 Limitations:
  52
  53 *   Not all kernel versions support `CLONE_NEWPID`. If the `SUID` helper is run
  54     on a kernel that does not support `CLONE_NEWPID`, it will ignore the problem
  55     without a warning, but the protection offered by the sandbox will be
  56     substantially reduced. See LinuxPidNamespaceSupport for how to test whether
  57     your system supports PID namespaces.
  58 *   This does not restrict network access.
  59 *   This does not prevent processes within a given sandbox from sending each
  60     other signals or killing each other.
  61 *   Setting a process to be undumpable is not irreversible. A sandboxed process
  62     can make itself dumpable again, opening itself up to being taken over by
  63     another process (either unsandboxed or within the same sandbox).
  64     *   Breakpad (the crash reporting tool) makes use of this. If a process
  65         crashes, Breakpad makes it dumpable in order to use ptrace() to halt
  66         threads and capture the process's state at the time of the crash. This
  67         opens a small window of vulnerability.
  68
  69 ## `setuid()` method
  70
  71 _This is an alternative to the `CLONE_NEWPID` method; it is not currently
  72 implemented in the Chromium codebase._
  73
  74 Instead of using `CLONE_NEWPID`, the `SUID` helper can use `setuid()` to put the
  75 process into a currently-unused UID, which is allocated out of a range of UIDs.
  76 In order to ensure that the `UID` has not been allocated for another sandbox,
  77 the `SUID` helper uses
  78 [getrlimit()](http://www.kernel.org/doc/man-pages/online/pages/man2/getrlimit.2.html)
  79 to set `RLIMIT_NPROC` temporarily to a soft limit of 1. (Note that the docs
  80 specify that [setuid()](http://www.kernel.org/doc/man-pages/online/pages/man2/setuid.2.html)
  81 returns `EAGAIN` if `RLIMIT_NPROC` is exceeded.)  We can reset `RLIMIT_NPROC`
  82 afterwards in order to allow the sandboxed process to fork child processes.
  83
  84 As before, the `SUID` helper chroots the process.
  85
  86 As before, LinuxZygote can set itself to be undumpable to stop processes in the
  87 sandbox from being able to `ptrace()` each other.
  88
  89 Limitations:
  90
  91 *   It is not possible for an unsandboxed process to `ptrace()` a sandboxed
  92     process because they run under different UIDs. This makes debugging harder.
  93     There is no equivalent of the `--allow-sandbox-debugging` other than turning
  94     the sandbox off with `--no-sandbox`.
  95 *   The `SUID` helper can check that a `UID` is unused before it uses it (hence
  96     this is safe if the `SUID` helper is installed into multiple chroots), but
  97     it cannot prevent other root processes from putting processes into this
  98     `UID` after the sandbox has been started. This means we should make the
  99     `UID` range configurable, or distributions should reserve a `UID` range.
 100
 101 ## `CLONE_NEWNET` method
 102
 103 The `SUID` helper uses
 104 [CLONE_NEWNET](http://www.kernel.org/doc/man-pages/online/pages/man2/clone.2.html)
 105 to restrict network access.
 106
 107 ## Future work
 108
 109 We are splitting the `SUID` sandbox into a separate project which will support
 110 both the `CLONE_NEWNS` and `setuid()` methods:
 111 http://code.google.com/p/setuid-sandbox/
 112
 113 Having the `SUID` helper as a separate project should make it easier for
 114 distributions to review and package.
 115
 116 ## Possible extensions
 117
 118 ## History
 119
 120 Older versions of the sandbox helper process will _only_ run
 121 `/opt/google/chrome/chrome`. This string is hard coded
 122 (`sandbox/linux/suid/sandbox.cc`). If your package is going to place the
 123 Chromium binary somewhere else you need to modify this string.
 124
 125 ## See also
 126
 127 *   [LinuxSUIDSandboxDevelopment](linux_suid_sandbox_development.md)
 128 *   [LinuxSandboxing](linux_sandboxing.md)
 129 *   General information on Chromium sandboxing:
 130     http://dev.chromium.org/developers/design-documents/sandbox