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