Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 1 | ====================== |
| 2 | Control Flow Integrity |
| 3 | ====================== |
| 4 | |
| 5 | .. toctree:: |
| 6 | :hidden: |
| 7 | |
| 8 | ControlFlowIntegrityDesign |
| 9 | |
| 10 | .. contents:: |
| 11 | :local: |
| 12 | |
| 13 | Introduction |
| 14 | ============ |
| 15 | |
| 16 | Clang includes an implementation of a number of control flow integrity (CFI) |
| 17 | schemes, which are designed to abort the program upon detecting certain forms |
| 18 | of undefined behavior that can potentially allow attackers to subvert the |
| 19 | program's control flow. These schemes have been optimized for performance, |
| 20 | allowing developers to enable them in release builds. |
| 21 | |
| 22 | To enable Clang's available CFI schemes, use the flag ``-fsanitize=cfi``. |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 23 | You can also enable a subset of available :ref:`schemes <cfi-schemes>`. |
| 24 | As currently implemented, all schemes rely on link-time optimization (LTO); |
| 25 | so it is required to specify ``-flto``, and the linker used must support LTO, |
| 26 | for example via the `gold plugin`_. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 27 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 28 | To allow the checks to be implemented efficiently, the program must |
| 29 | be structured such that certain object files are compiled with CFI |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 30 | enabled, and are statically linked into the program. This may preclude |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 31 | the use of shared libraries in some cases. |
| 32 | |
| 33 | The compiler will only produce CFI checks for a class if it can infer hidden |
| 34 | LTO visibility for that class. LTO visibility is a property of a class that |
| 35 | is inferred from flags and attributes. For more details, see the documentation |
| 36 | for :doc:`LTO visibility <LTOVisibility>`. |
| 37 | |
| 38 | The ``-fsanitize=cfi-{vcall,nvcall,derived-cast,unrelated-cast}`` flags |
| 39 | require that a ``-fvisibility=`` flag also be specified. This is because the |
| 40 | default visibility setting is ``-fvisibility=default``, which would disable |
| 41 | CFI checks for classes without visibility attributes. Most users will want |
| 42 | to specify ``-fvisibility=hidden``, which enables CFI checks for such classes. |
| 43 | |
| 44 | Experimental support for :ref:`cross-DSO control flow integrity |
| 45 | <cfi-cross-dso>` exists that does not require classes to have hidden LTO |
| 46 | visibility. This cross-DSO support has unstable ABI at this time. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 47 | |
| 48 | .. _gold plugin: http://llvm.org/docs/GoldPlugin.html |
| 49 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 50 | .. _cfi-schemes: |
| 51 | |
| 52 | Available schemes |
| 53 | ================= |
| 54 | |
| 55 | Available schemes are: |
| 56 | |
| 57 | - ``-fsanitize=cfi-cast-strict``: Enables :ref:`strict cast checks |
| 58 | <cfi-strictness>`. |
| 59 | - ``-fsanitize=cfi-derived-cast``: Base-to-derived cast to the wrong |
| 60 | dynamic type. |
| 61 | - ``-fsanitize=cfi-unrelated-cast``: Cast from ``void*`` or another |
| 62 | unrelated type to the wrong dynamic type. |
| 63 | - ``-fsanitize=cfi-nvcall``: Non-virtual call via an object whose vptr is of |
| 64 | the wrong dynamic type. |
| 65 | - ``-fsanitize=cfi-vcall``: Virtual call via an object whose vptr is of the |
| 66 | wrong dynamic type. |
| 67 | - ``-fsanitize=cfi-icall``: Indirect call of a function with wrong dynamic |
| 68 | type. |
| 69 | |
| 70 | You can use ``-fsanitize=cfi`` to enable all the schemes and use |
| 71 | ``-fno-sanitize`` flag to narrow down the set of schemes as desired. |
| 72 | For example, you can build your program with |
| 73 | ``-fsanitize=cfi -fno-sanitize=cfi-nvcall,cfi-icall`` |
| 74 | to use all schemes except for non-virtual member function call and indirect call |
| 75 | checking. |
| 76 | |
| 77 | Remember that you have to provide ``-flto`` if at least one CFI scheme is |
| 78 | enabled. |
| 79 | |
| 80 | Trapping and Diagnostics |
| 81 | ======================== |
| 82 | |
| 83 | By default, CFI will abort the program immediately upon detecting a control |
| 84 | flow integrity violation. You can use the :ref:`-fno-sanitize-trap= |
| 85 | <controlling-code-generation>` flag to cause CFI to print a diagnostic |
| 86 | similar to the one below before the program aborts. |
| 87 | |
| 88 | .. code-block:: console |
| 89 | |
| 90 | bad-cast.cpp:109:7: runtime error: control flow integrity check for type 'B' failed during base-to-derived cast (vtable address 0x000000425a50) |
| 91 | 0x000000425a50: note: vtable is of type 'A' |
| 92 | 00 00 00 00 f0 f1 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20 5a 42 00 |
| 93 | ^ |
| 94 | |
| 95 | If diagnostics are enabled, you can also configure CFI to continue program |
| 96 | execution instead of aborting by using the :ref:`-fsanitize-recover= |
| 97 | <controlling-code-generation>` flag. |
| 98 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 99 | Forward-Edge CFI for Virtual Calls |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 100 | ================================== |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 101 | |
| 102 | This scheme checks that virtual calls take place using a vptr of the correct |
| 103 | dynamic type; that is, the dynamic type of the called object must be a |
| 104 | derived class of the static type of the object used to make the call. |
Pirama Arumuga Nainar | 58878f8 | 2015-05-06 11:48:57 -0700 | [diff] [blame] | 105 | This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 106 | |
| 107 | For this scheme to work, all translation units containing the definition |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 108 | of a virtual member function (whether inline or not), other than members |
| 109 | of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with |
| 110 | ``-fsanitize=cfi-vcall`` enabled and be statically linked into the program. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 111 | |
| 112 | Performance |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 113 | ----------- |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 114 | |
| 115 | A performance overhead of less than 1% has been measured by running the |
| 116 | Dromaeo benchmark suite against an instrumented version of the Chromium |
| 117 | web browser. Another good performance benchmark for this mechanism is the |
| 118 | virtual-call-heavy SPEC 2006 xalancbmk. |
| 119 | |
| 120 | Note that this scheme has not yet been optimized for binary size; an increase |
| 121 | of up to 15% has been observed for Chromium. |
| 122 | |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 123 | Bad Cast Checking |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 124 | ================= |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 125 | |
| 126 | This scheme checks that pointer casts are made to an object of the correct |
| 127 | dynamic type; that is, the dynamic type of the object must be a derived class |
| 128 | of the pointee type of the cast. The checks are currently only introduced |
| 129 | where the class being casted to is a polymorphic class. |
| 130 | |
| 131 | Bad casts are not in themselves control flow integrity violations, but they |
| 132 | can also create security vulnerabilities, and the implementation uses many |
| 133 | of the same mechanisms. |
| 134 | |
| 135 | There are two types of bad cast that may be forbidden: bad casts |
| 136 | from a base class to a derived class (which can be checked with |
| 137 | ``-fsanitize=cfi-derived-cast``), and bad casts from a pointer of |
| 138 | type ``void*`` or another unrelated type (which can be checked with |
| 139 | ``-fsanitize=cfi-unrelated-cast``). |
| 140 | |
| 141 | The difference between these two types of casts is that the first is defined |
| 142 | by the C++ standard to produce an undefined value, while the second is not |
| 143 | in itself undefined behavior (it is well defined to cast the pointer back |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 144 | to its original type) unless the object is uninitialized and the cast is a |
| 145 | ``static_cast`` (see C++14 [basic.life]p5). |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 146 | |
| 147 | If a program as a matter of policy forbids the second type of cast, that |
| 148 | restriction can normally be enforced. However it may in some cases be necessary |
| 149 | for a function to perform a forbidden cast to conform with an external API |
| 150 | (e.g. the ``allocate`` member function of a standard library allocator). Such |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 151 | functions may be :ref:`blacklisted <cfi-blacklist>`. |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 152 | |
| 153 | For this scheme to work, all translation units containing the definition |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 154 | of a virtual member function (whether inline or not), other than members |
| 155 | of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 156 | ``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 157 | and be statically linked into the program. |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 158 | |
Pirama Arumuga Nainar | 58878f8 | 2015-05-06 11:48:57 -0700 | [diff] [blame] | 159 | Non-Virtual Member Function Call Checking |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 160 | ========================================= |
Pirama Arumuga Nainar | 58878f8 | 2015-05-06 11:48:57 -0700 | [diff] [blame] | 161 | |
| 162 | This scheme checks that non-virtual calls take place using an object of |
| 163 | the correct dynamic type; that is, the dynamic type of the called object |
| 164 | must be a derived class of the static type of the object used to make the |
| 165 | call. The checks are currently only introduced where the object is of a |
| 166 | polymorphic class type. This CFI scheme can be enabled on its own using |
| 167 | ``-fsanitize=cfi-nvcall``. |
| 168 | |
| 169 | For this scheme to work, all translation units containing the definition |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 170 | of a virtual member function (whether inline or not), other than members |
| 171 | of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with |
| 172 | ``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program. |
Pirama Arumuga Nainar | 58878f8 | 2015-05-06 11:48:57 -0700 | [diff] [blame] | 173 | |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 174 | .. _cfi-strictness: |
| 175 | |
| 176 | Strictness |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 177 | ---------- |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame] | 178 | |
| 179 | If a class has a single non-virtual base and does not introduce or override |
| 180 | virtual member functions or fields other than an implicitly defined virtual |
| 181 | destructor, it will have the same layout and virtual function semantics as |
| 182 | its base. By default, casts to such classes are checked as if they were made |
| 183 | to the least derived such class. |
| 184 | |
| 185 | Casting an instance of a base class to such a derived class is technically |
| 186 | undefined behavior, but it is a relatively common hack for introducing |
| 187 | member functions on class instances with specific properties that works under |
| 188 | most compilers and should not have security implications, so we allow it by |
| 189 | default. It can be disabled with ``-fsanitize=cfi-cast-strict``. |
| 190 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 191 | Indirect Function Call Checking |
| 192 | =============================== |
| 193 | |
| 194 | This scheme checks that function calls take place using a function of the |
| 195 | correct dynamic type; that is, the dynamic type of the function must match |
| 196 | the static type used at the call. This CFI scheme can be enabled on its own |
| 197 | using ``-fsanitize=cfi-icall``. |
| 198 | |
| 199 | For this scheme to work, each indirect function call in the program, other |
| 200 | than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a |
| 201 | function which was either compiled with ``-fsanitize=cfi-icall`` enabled, |
| 202 | or whose address was taken by a function in a translation unit compiled with |
| 203 | ``-fsanitize=cfi-icall``. |
| 204 | |
| 205 | If a function in a translation unit compiled with ``-fsanitize=cfi-icall`` |
| 206 | takes the address of a function not compiled with ``-fsanitize=cfi-icall``, |
| 207 | that address may differ from the address taken by a function in a translation |
| 208 | unit not compiled with ``-fsanitize=cfi-icall``. This is technically a |
| 209 | violation of the C and C++ standards, but it should not affect most programs. |
| 210 | |
| 211 | Each translation unit compiled with ``-fsanitize=cfi-icall`` must be |
| 212 | statically linked into the program or shared library, and calls across |
| 213 | shared library boundaries are handled as if the callee was not compiled with |
| 214 | ``-fsanitize=cfi-icall``. |
| 215 | |
| 216 | This scheme is currently only supported on the x86 and x86_64 architectures. |
| 217 | |
| 218 | ``-fsanitize=cfi-icall`` and ``-fsanitize=function`` |
| 219 | ---------------------------------------------------- |
| 220 | |
| 221 | This tool is similar to ``-fsanitize=function`` in that both tools check |
| 222 | the types of function calls. However, the two tools occupy different points |
| 223 | on the design space; ``-fsanitize=function`` is a developer tool designed |
| 224 | to find bugs in local development builds, whereas ``-fsanitize=cfi-icall`` |
| 225 | is a security hardening mechanism designed to be deployed in release builds. |
| 226 | |
| 227 | ``-fsanitize=function`` has a higher space and time overhead due to a more |
| 228 | complex type check at indirect call sites, as well as a need for run-time |
| 229 | type information (RTTI), which may make it unsuitable for deployment. Because |
| 230 | of the need for RTTI, ``-fsanitize=function`` can only be used with C++ |
| 231 | programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs. |
| 232 | |
| 233 | On the other hand, ``-fsanitize=function`` conforms more closely with the C++ |
| 234 | standard and user expectations around interaction with shared libraries; |
| 235 | the identity of function pointers is maintained, and calls across shared |
| 236 | library boundaries are no different from calls within a single program or |
| 237 | shared library. |
| 238 | |
| 239 | .. _cfi-blacklist: |
| 240 | |
| 241 | Blacklist |
| 242 | ========= |
| 243 | |
| 244 | A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain |
| 245 | source files, functions and types using the ``src``, ``fun`` and ``type`` |
| 246 | entity types. |
| 247 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 248 | .. code-block:: bash |
| 249 | |
| 250 | # Suppress checking for code in a file. |
| 251 | src:bad_file.cpp |
| 252 | src:bad_header.h |
| 253 | # Ignore all functions with names containing MyFooBar. |
| 254 | fun:*MyFooBar* |
| 255 | # Ignore all types in the standard library. |
| 256 | type:std::* |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 257 | |
| 258 | .. _cfi-cross-dso: |
| 259 | |
| 260 | Shared library support |
| 261 | ====================== |
| 262 | |
| 263 | Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control |
| 264 | flow integrity mode, which allows all CFI schemes listed above to |
| 265 | apply across DSO boundaries. As in the regular CFI, each DSO must be |
| 266 | built with ``-flto``. |
| 267 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 268 | Normally, CFI checks will only be performed for classes that have hidden LTO |
| 269 | visibility. With this flag enabled, the compiler will emit cross-DSO CFI |
| 270 | checks for all classes, except for those which appear in the CFI blacklist |
| 271 | or which use a ``no_sanitize`` attribute. |
| 272 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 273 | Design |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 274 | ====== |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 275 | |
| 276 | Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`. |
| 277 | |
| 278 | Publications |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 279 | ============ |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 280 | |
| 281 | `Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_. |
| 282 | Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti. |
| 283 | |
| 284 | `Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_. |
| 285 | Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway, |
| 286 | Úlfar Erlingsson, Luis Lozano, Geoff Pike. |