clang/docs/SafeStack.rst

   1 =========
   2 SafeStack
   3 =========
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 SafeStack is an instrumentation pass that protects programs against attacks
  12 based on stack buffer overflows, without introducing any measurable performance
  13 overhead. It works by separating the program stack into two distinct regions:
  14 the safe stack and the unsafe stack. The safe stack stores return addresses,
  15 register spills, and local variables that are always accessed in a safe way,
  16 while the unsafe stack stores everything else. This separation ensures that
  17 buffer overflows on the unsafe stack cannot be used to overwrite anything
  18 on the safe stack.
  19
  20 SafeStack is a part of the `Code-Pointer Integrity (CPI) Project
  21 <https://dslab.epfl.ch/research/cpi/>`_.
  22
  23 Performance
  24 -----------
  25
  26 The performance overhead of the SafeStack instrumentation is less than 0.1% on
  27 average across a variety of benchmarks (see the `Code-Pointer Integrity
  28 <https://dslab.epfl.ch/pubs/cpi.pdf>`__ paper for details). This is mainly
  29 because most small functions do not have any variables that require the unsafe
  30 stack and, hence, do not need unsafe stack frames to be created. The cost of
  31 creating unsafe stack frames for large functions is amortized by the cost of
  32 executing the function.
  33
  34 In some cases, SafeStack actually improves the performance. Objects that end up
  35 being moved to the unsafe stack are usually large arrays or variables that are
  36 used through multiple stack frames. Moving such objects away from the safe
  37 stack increases the locality of frequently accessed values on the stack, such
  38 as register spills, return addresses, and small local variables.
  39
  40 Compatibility
  41 -------------
  42
  43 Most programs, static libraries, or individual files can be compiled
  44 with SafeStack as is. SafeStack requires basic runtime support, which, on most
  45 platforms, is implemented as a compiler-rt library that is automatically linked
  46 in when the program is compiled with SafeStack.
  47
  48 Linking a DSO with SafeStack is not currently supported.
  49
  50 Known compatibility limitations
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52
  53 Certain code that relies on low-level stack manipulations requires adaption to
  54 work with SafeStack. One example is mark-and-sweep garbage collection
  55 implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be
  56 changed to look for the live pointers on both safe and unsafe stacks.
  57
  58 SafeStack supports linking statically modules that are compiled with and
  59 without SafeStack. An executable compiled with SafeStack can load dynamic
  60 libraries that are not compiled with SafeStack. At the moment, compiling
  61 dynamic libraries with SafeStack is not supported.
  62
  63 Signal handlers that use ``sigaltstack()`` must not use the unsafe stack (see
  64 ``__attribute__((no_sanitize("safe-stack")))`` below).
  65
  66 Programs that use APIs from ``ucontext.h`` are not supported yet.
  67
  68 Security
  69 --------
  70
  71 SafeStack protects return addresses, spilled registers and local variables that
  72 are always accessed in a safe way by separating them in a dedicated safe stack
  73 region. The safe stack is automatically protected against stack-based buffer
  74 overflows, since it is disjoint from the unsafe stack in memory, and it itself
  75 is always accessed in a safe way. In the current implementation, the safe stack
  76 is protected against arbitrary memory write vulnerabilities though
  77 randomization and information hiding: the safe stack is allocated at a random
  78 address and the instrumentation ensures that no pointers to the safe stack are
  79 ever stored outside of the safe stack itself (see limitations below).
  80
  81 Known security limitations
  82 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84 A complete protection against control-flow hijack attacks requires combining
  85 SafeStack with another mechanism that enforces the integrity of code pointers
  86 that are stored on the heap or the unsafe stack, such as `CPI
  87 <https://dslab.epfl.ch/research/cpi/>`_, or a forward-edge control flow integrity
  88 mechanism that enforces correct calling conventions at indirect call sites,
  89 such as `IFCC <https://research.google.com/pubs/archive/42808.pdf>`_ with arity
  90 checks. Clang has control-flow integrity protection scheme for :doc:`C++ virtual
  91 calls <ControlFlowIntegrity>`, but not non-virtual indirect calls. With
  92 SafeStack alone, an attacker can overwrite a function pointer on the heap or
  93 the unsafe stack and cause a program to call arbitrary location, which in turn
  94 might enable stack pivoting and return-oriented programming.
  95
  96 In its current implementation, SafeStack provides precise protection against
  97 stack-based buffer overflows, but protection against arbitrary memory write
  98 vulnerabilities is probabilistic and relies on randomization and information
  99 hiding. The randomization is currently based on system-enforced ASLR and shares
 100 its known security limitations. The safe stack pointer hiding is not perfect
 101 yet either: system library functions such as ``swapcontext``, exception
 102 handling mechanisms, intrinsics such as ``__builtin_frame_address``, or
 103 low-level bugs in runtime support could leak the safe stack pointer. In the
 104 future, such leaks could be detected by static or dynamic analysis tools and
 105 prevented by adjusting such functions to either encrypt the stack pointer when
 106 storing it in the heap (as already done e.g., by ``setjmp``/``longjmp``
 107 implementation in glibc), or store it in a safe region instead.
 108
 109 The `CPI paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ describes two alternative,
 110 stronger safe stack protection mechanisms, that rely on software fault
 111 isolation, or hardware segmentation (as available on x86-32 and some x86-64
 112 CPUs).
 113
 114 At the moment, SafeStack assumes that the compiler's implementation is correct.
 115 This has not been verified except through manual code inspection, and could
 116 always regress in the future. It's therefore desirable to have a separate
 117 static or dynamic binary verification tool that would check the correctness of
 118 the SafeStack instrumentation in final binaries.
 119
 120 Usage
 121 =====
 122
 123 To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile
 124 and link command lines.
 125
 126 Supported Platforms
 127 -------------------
 128
 129 SafeStack was tested on Linux, NetBSD, FreeBSD and macOS.
 130
 131 Low-level API
 132 -------------
 133
 134 ``__has_feature(safe_stack)``
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 In some rare cases one may need to execute different code depending on
 138 whether SafeStack is enabled. The macro ``__has_feature(safe_stack)`` can
 139 be used for this purpose.
 140
 141 .. code-block:: c
 142
 143     #if __has_feature(safe_stack)
 144     // code that builds only under SafeStack
 145     #endif
 146
 147 ``__attribute__((no_sanitize("safe-stack")))``
 148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 149
 150 Use ``__attribute__((no_sanitize("safe-stack")))`` on a function declaration
 151 to specify that the safe stack instrumentation should not be applied to that
 152 function, even if enabled globally (see ``-fsanitize=safe-stack`` flag). This
 153 attribute may be required for functions that make assumptions about the
 154 exact layout of their stack frames.
 155
 156 All local variables in functions with this attribute will be stored on the safe
 157 stack. The safe stack remains unprotected against memory errors when accessing
 158 these variables, so extra care must be taken to manually ensure that all such
 159 accesses are safe. Furthermore, the addresses of such local variables should
 160 never be stored on the heap, as it would leak the location of the SafeStack.
 161
 162 ``__builtin___get_unsafe_stack_ptr()``
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 This builtin function returns current unsafe stack pointer of the current
 166 thread.
 167
 168 ``__builtin___get_unsafe_stack_bottom()``
 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 170
 171 This builtin function returns a pointer to the bottom of the unsafe stack of the
 172 current thread.
 173
 174 ``__builtin___get_unsafe_stack_top()``
 175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 176
 177 This builtin function returns a pointer to the top of the unsafe stack of the
 178 current thread.
 179
 180 ``__builtin___get_unsafe_stack_start()``
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 Deprecated: This builtin function is an alias for
 184 ``__builtin___get_unsafe_stack_bottom()``.
 185
 186 Design
 187 ======
 188
 189 Please refer to the `Code-Pointer Integrity <https://dslab.epfl.ch/research/cpi/>`__
 190 project page for more information about the design of the SafeStack and its
 191 related technologies.
 192
 193 setjmp and exception handling
 194 -----------------------------
 195
 196 The `OSDI'14 paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ mentions that
 197 on Linux the instrumentation pass finds calls to setjmp or functions that
 198 may throw an exception, and inserts required instrumentation at their call
 199 sites. Specifically, the instrumentation pass saves the shadow stack pointer
 200 on the safe stack before the call site, and restores it either after the
 201 call to setjmp or after an exception has been caught. This is implemented
 202 in the function ``SafeStack::createStackRestorePoints``.
 203
 204 Publications
 205 ------------
 206
 207 `Code-Pointer Integrity <https://dslab.epfl.ch/pubs/cpi.pdf>`__.
 208 Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
 209 USENIX Symposium on Operating Systems Design and Implementation
 210 (`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014