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 29be structured 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. 32 33The compiler will only produce CFI checks for a class if it can infer hidden 34LTO visibility for that class. LTO visibility is a property of a class that 35is inferred from flags and attributes. For more details, see the documentation 36for :doc:`LTO visibility <LTOVisibility>`. 37 38The ``-fsanitize=cfi-{vcall,nvcall,derived-cast,unrelated-cast}`` flags 39require that a ``-fvisibility=`` flag also be specified. This is because the 40default visibility setting is ``-fvisibility=default``, which would disable 41CFI checks for classes without visibility attributes. Most users will want 42to specify ``-fvisibility=hidden``, which enables CFI checks for such classes. 43 44Experimental support for :ref:`cross-DSO control flow integrity 45<cfi-cross-dso>` exists that does not require classes to have hidden LTO 46visibility. This cross-DSO support has unstable ABI at this time. 47 48.. _gold plugin: http://llvm.org/docs/GoldPlugin.html 49 50.. _cfi-schemes: 51 52Available schemes 53================= 54 55Available 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 70You can use ``-fsanitize=cfi`` to enable all the schemes and use 71``-fno-sanitize`` flag to narrow down the set of schemes as desired. 72For example, you can build your program with 73``-fsanitize=cfi -fno-sanitize=cfi-nvcall,cfi-icall`` 74to use all schemes except for non-virtual member function call and indirect call 75checking. 76 77Remember that you have to provide ``-flto`` if at least one CFI scheme is 78enabled. 79 80Trapping and Diagnostics 81======================== 82 83By default, CFI will abort the program immediately upon detecting a control 84flow integrity violation. You can use the :ref:`-fno-sanitize-trap= 85<controlling-code-generation>` flag to cause CFI to print a diagnostic 86similar 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 95If diagnostics are enabled, you can also configure CFI to continue program 96execution instead of aborting by using the :ref:`-fsanitize-recover= 97<controlling-code-generation>` flag. 98 99Forward-Edge CFI for Virtual Calls 100================================== 101 102This scheme checks that virtual calls take place using a vptr of the correct 103dynamic type; that is, the dynamic type of the called object must be a 104derived class of the static type of the object used to make the call. 105This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``. 106 107For this scheme to work, all translation units containing the definition 108of a virtual member function (whether inline or not), other than members 109of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with 110``-fsanitize=cfi-vcall`` enabled and be statically linked into the program. 111 112Performance 113----------- 114 115A performance overhead of less than 1% has been measured by running the 116Dromaeo benchmark suite against an instrumented version of the Chromium 117web browser. Another good performance benchmark for this mechanism is the 118virtual-call-heavy SPEC 2006 xalancbmk. 119 120Note that this scheme has not yet been optimized for binary size; an increase 121of up to 15% has been observed for Chromium. 122 123Bad Cast Checking 124================= 125 126This scheme checks that pointer casts are made to an object of the correct 127dynamic type; that is, the dynamic type of the object must be a derived class 128of the pointee type of the cast. The checks are currently only introduced 129where the class being casted to is a polymorphic class. 130 131Bad casts are not in themselves control flow integrity violations, but they 132can also create security vulnerabilities, and the implementation uses many 133of the same mechanisms. 134 135There are two types of bad cast that may be forbidden: bad casts 136from a base class to a derived class (which can be checked with 137``-fsanitize=cfi-derived-cast``), and bad casts from a pointer of 138type ``void*`` or another unrelated type (which can be checked with 139``-fsanitize=cfi-unrelated-cast``). 140 141The difference between these two types of casts is that the first is defined 142by the C++ standard to produce an undefined value, while the second is not 143in itself undefined behavior (it is well defined to cast the pointer back 144to its original type) unless the object is uninitialized and the cast is a 145``static_cast`` (see C++14 [basic.life]p5). 146 147If a program as a matter of policy forbids the second type of cast, that 148restriction can normally be enforced. However it may in some cases be necessary 149for 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 151functions may be :ref:`blacklisted <cfi-blacklist>`. 152 153For this scheme to work, all translation units containing the definition 154of a virtual member function (whether inline or not), other than members 155of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with 156``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled 157and be statically linked into the program. 158 159Non-Virtual Member Function Call Checking 160========================================= 161 162This scheme checks that non-virtual calls take place using an object of 163the correct dynamic type; that is, the dynamic type of the called object 164must be a derived class of the static type of the object used to make the 165call. The checks are currently only introduced where the object is of a 166polymorphic class type. This CFI scheme can be enabled on its own using 167``-fsanitize=cfi-nvcall``. 168 169For this scheme to work, all translation units containing the definition 170of a virtual member function (whether inline or not), other than members 171of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with 172``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program. 173 174.. _cfi-strictness: 175 176Strictness 177---------- 178 179If a class has a single non-virtual base and does not introduce or override 180virtual member functions or fields other than an implicitly defined virtual 181destructor, it will have the same layout and virtual function semantics as 182its base. By default, casts to such classes are checked as if they were made 183to the least derived such class. 184 185Casting an instance of a base class to such a derived class is technically 186undefined behavior, but it is a relatively common hack for introducing 187member functions on class instances with specific properties that works under 188most compilers and should not have security implications, so we allow it by 189default. It can be disabled with ``-fsanitize=cfi-cast-strict``. 190 191Indirect Function Call Checking 192=============================== 193 194This scheme checks that function calls take place using a function of the 195correct dynamic type; that is, the dynamic type of the function must match 196the static type used at the call. This CFI scheme can be enabled on its own 197using ``-fsanitize=cfi-icall``. 198 199For this scheme to work, each indirect function call in the program, other 200than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a 201function which was either compiled with ``-fsanitize=cfi-icall`` enabled, 202or whose address was taken by a function in a translation unit compiled with 203``-fsanitize=cfi-icall``. 204 205If a function in a translation unit compiled with ``-fsanitize=cfi-icall`` 206takes the address of a function not compiled with ``-fsanitize=cfi-icall``, 207that address may differ from the address taken by a function in a translation 208unit not compiled with ``-fsanitize=cfi-icall``. This is technically a 209violation of the C and C++ standards, but it should not affect most programs. 210 211Each translation unit compiled with ``-fsanitize=cfi-icall`` must be 212statically linked into the program or shared library, and calls across 213shared library boundaries are handled as if the callee was not compiled with 214``-fsanitize=cfi-icall``. 215 216This scheme is currently only supported on the x86 and x86_64 architectures. 217 218``-fsanitize=cfi-icall`` and ``-fsanitize=function`` 219---------------------------------------------------- 220 221This tool is similar to ``-fsanitize=function`` in that both tools check 222the types of function calls. However, the two tools occupy different points 223on the design space; ``-fsanitize=function`` is a developer tool designed 224to find bugs in local development builds, whereas ``-fsanitize=cfi-icall`` 225is 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 228complex type check at indirect call sites, as well as a need for run-time 229type information (RTTI), which may make it unsuitable for deployment. Because 230of the need for RTTI, ``-fsanitize=function`` can only be used with C++ 231programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs. 232 233On the other hand, ``-fsanitize=function`` conforms more closely with the C++ 234standard and user expectations around interaction with shared libraries; 235the identity of function pointers is maintained, and calls across shared 236library boundaries are no different from calls within a single program or 237shared library. 238 239.. _cfi-blacklist: 240 241Blacklist 242========= 243 244A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain 245source files, functions and types using the ``src``, ``fun`` and ``type`` 246entity types. 247 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::* 257 258.. _cfi-cross-dso: 259 260Shared library support 261====================== 262 263Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control 264flow integrity mode, which allows all CFI schemes listed above to 265apply across DSO boundaries. As in the regular CFI, each DSO must be 266built with ``-flto``. 267 268Normally, CFI checks will only be performed for classes that have hidden LTO 269visibility. With this flag enabled, the compiler will emit cross-DSO CFI 270checks for all classes, except for those which appear in the CFI blacklist 271or which use a ``no_sanitize`` attribute. 272 273Design 274====== 275 276Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`. 277 278Publications 279============ 280 281`Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_. 282Martin 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>`_. 285Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway, 286Úlfar Erlingsson, Luis Lozano, Geoff Pike. 287