1=========
2SafeStack
3=========
4
5.. contents::
6   :local:
7
8Introduction
9============
10
11SafeStack is an instrumentation pass that protects programs against attacks
12based on stack buffer overflows, without introducing any measurable performance
13overhead. It works by separating the program stack into two distinct regions:
14the safe stack and the unsafe stack. The safe stack stores return addresses,
15register spills, and local variables that are always accessed in a safe way,
16while the unsafe stack stores everything else. This separation ensures that
17buffer overflows on the unsafe stack cannot be used to overwrite anything
18on the safe stack, which includes return addresses.
19
20Performance
21-----------
22
23The performance overhead of the SafeStack instrumentation is less than 0.1% on
24average across a variety of benchmarks (see the `Code-Pointer Integrity
25<http://dslab.epfl.ch/pubs/cpi.pdf>`_ paper for details). This is mainly
26because most small functions do not have any variables that require the unsafe
27stack and, hence, do not need unsafe stack frames to be created. The cost of
28creating unsafe stack frames for large functions is amortized by the cost of
29executing the function.
30
31In some cases, SafeStack actually improves the performance. Objects that end up
32being moved to the unsafe stack are usually large arrays or variables that are
33used through multiple stack frames. Moving such objects away from the safe
34stack increases the locality of frequently accessed values on the stack, such
35as register spills, return addresses, and small local variables.
36
37Limitations
38-----------
39
40SafeStack has not been subjected to a comprehensive security review, and there
41exist known weaknesses, including but not limited to the following.
42
43In its current state, the separation of local variables provides protection
44against stack buffer overflows, but the safe stack itself is not protected
45from being corrupted through a pointer dereference. The Code-Pointer
46Integrity paper describes two ways in which we may protect the safe stack:
47hardware segmentation on the 32-bit x86 architecture or information hiding
48on other architectures.
49
50Even with information hiding, the safe stack would merely be hidden
51from attackers by being somewhere in the address space. Depending on the
52application, the address could be predictable even on 64-bit address spaces
53because not all the bits are addressable, multiple threads each have their
54stack, the application could leak the safe stack address to memory via
55``__builtin_frame_address``, bugs in the low-level runtime support etc.
56Safe stack leaks could be mitigated by writing and deploying a static binary
57analysis or a dynamic binary instrumentation based tool to find leaks.
58
59This approach doesn't prevent an attacker from "imbalancing" the safe
60stack by say having just one call, and doing two rets (thereby returning
61to an address that wasn't meant as a return address). This can be at least
62partially mitigated by deploying SafeStack alongside a forward control-flow
63integrity mechanism to ensure that calls are made using the correct calling
64convention. Clang does not currently implement a comprehensive forward
65control-flow integrity protection scheme; there exists one that protects
66:doc:`virtual calls <ControlFlowIntegrity>` but not non-virtual indirect calls.
67
68Compatibility
69-------------
70
71Most programs, static libraries, or individual files can be compiled
72with SafeStack as is. SafeStack requires basic runtime support, which, on most
73platforms, is implemented as a compiler-rt library that is automatically linked
74in when the program is compiled with SafeStack.
75
76Linking a DSO with SafeStack is not currently supported.
77
78Known compatibility limitations
79~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
81Certain code that relies on low-level stack manipulations requires adaption to
82work with SafeStack. One example is mark-and-sweep garbage collection
83implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be
84changed to look for the live pointers on both safe and unsafe stacks.
85
86SafeStack supports linking together modules that are compiled with and without
87SafeStack, both statically and dynamically. One corner case that is not
88supported is using ``dlopen()`` to load a dynamic library that uses SafeStack into
89a program that is not compiled with SafeStack but uses threads.
90
91Signal handlers that use ``sigaltstack()`` must not use the unsafe stack (see
92``__attribute__((no_sanitize("safe-stack")))`` below).
93
94Programs that use APIs from ``ucontext.h`` are not supported yet.
95
96Usage
97=====
98
99To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile and link
100command lines.
101
102Supported Platforms
103-------------------
104
105SafeStack was tested on Linux, FreeBSD and MacOSX.
106
107Low-level API
108-------------
109
110``__has_feature(safe_stack)``
111~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113In some rare cases one may need to execute different code depending on
114whether SafeStack is enabled. The macro ``__has_feature(safe_stack)`` can
115be used for this purpose.
116
117.. code-block:: c
118
119    #if __has_feature(safe_stack)
120    // code that builds only under SafeStack
121    #endif
122
123``__attribute__((no_sanitize("safe-stack")))``
124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125
126Use ``__attribute__((no_sanitize("safe-stack")))`` on a function declaration
127to specify that the safe stack instrumentation should not be applied to that
128function, even if enabled globally (see ``-fsanitize=safe-stack`` flag). This
129attribute may be required for functions that make assumptions about the
130exact layout of their stack frames.
131
132Care should be taken when using this attribute. The return address is not
133protected against stack buffer overflows, and it is easier to leak the
134address of the safe stack to memory by taking the address of a local variable.
135
136
137``__builtin___get_unsafe_stack_ptr()``
138~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
139
140This builtin function returns current unsafe stack pointer of the current
141thread.
142
143``__builtin___get_unsafe_stack_start()``
144~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145
146This builtin function returns a pointer to the start of the unsafe stack of the
147current thread.
148
149Design
150======
151
152Please refer to
153`http://dslab.epfl.ch/proj/cpi/ <http://dslab.epfl.ch/proj/cpi/>`_ for more
154information about the design of the SafeStack and its related technologies.
155
156
157Publications
158------------
159
160`Code-Pointer Integrity <http://dslab.epfl.ch/pubs/cpi.pdf>`_.
161Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
162USENIX Symposium on Operating Systems Design and Implementation
163(`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014
164