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) unless the object is uninitialized and the cast is a 133``static_cast`` (see C++14 [basic.life]p5). 134 135If a program as a matter of policy forbids the second type of cast, that 136restriction can normally be enforced. However it may in some cases be necessary 137for a function to perform a forbidden cast to conform with an external API 138(e.g. the ``allocate`` member function of a standard library allocator). Such 139functions may be :ref:`blacklisted <cfi-blacklist>`. 140 141For this scheme to work, all translation units containing the definition 142of a virtual member function (whether inline or not), other than members 143of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with 144``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled 145and be statically linked into the program. 146 147Non-Virtual Member Function Call Checking 148========================================= 149 150This scheme checks that non-virtual calls take place using an object of 151the correct dynamic type; that is, the dynamic type of the called object 152must be a derived class of the static type of the object used to make the 153call. The checks are currently only introduced where the object is of a 154polymorphic class type. This CFI scheme can be enabled on its own using 155``-fsanitize=cfi-nvcall``. 156 157For this scheme to work, all translation units containing the definition 158of a virtual member function (whether inline or not), other than members 159of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with 160``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program. 161 162.. _cfi-strictness: 163 164Strictness 165---------- 166 167If a class has a single non-virtual base and does not introduce or override 168virtual member functions or fields other than an implicitly defined virtual 169destructor, it will have the same layout and virtual function semantics as 170its base. By default, casts to such classes are checked as if they were made 171to the least derived such class. 172 173Casting an instance of a base class to such a derived class is technically 174undefined behavior, but it is a relatively common hack for introducing 175member functions on class instances with specific properties that works under 176most compilers and should not have security implications, so we allow it by 177default. It can be disabled with ``-fsanitize=cfi-cast-strict``. 178 179Indirect Function Call Checking 180=============================== 181 182This scheme checks that function calls take place using a function of the 183correct dynamic type; that is, the dynamic type of the function must match 184the static type used at the call. This CFI scheme can be enabled on its own 185using ``-fsanitize=cfi-icall``. 186 187For this scheme to work, each indirect function call in the program, other 188than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a 189function which was either compiled with ``-fsanitize=cfi-icall`` enabled, 190or whose address was taken by a function in a translation unit compiled with 191``-fsanitize=cfi-icall``. 192 193If a function in a translation unit compiled with ``-fsanitize=cfi-icall`` 194takes the address of a function not compiled with ``-fsanitize=cfi-icall``, 195that address may differ from the address taken by a function in a translation 196unit not compiled with ``-fsanitize=cfi-icall``. This is technically a 197violation of the C and C++ standards, but it should not affect most programs. 198 199Each translation unit compiled with ``-fsanitize=cfi-icall`` must be 200statically linked into the program or shared library, and calls across 201shared library boundaries are handled as if the callee was not compiled with 202``-fsanitize=cfi-icall``. 203 204This scheme is currently only supported on the x86 and x86_64 architectures. 205 206``-fsanitize=cfi-icall`` and ``-fsanitize=function`` 207---------------------------------------------------- 208 209This tool is similar to ``-fsanitize=function`` in that both tools check 210the types of function calls. However, the two tools occupy different points 211on the design space; ``-fsanitize=function`` is a developer tool designed 212to find bugs in local development builds, whereas ``-fsanitize=cfi-icall`` 213is a security hardening mechanism designed to be deployed in release builds. 214 215``-fsanitize=function`` has a higher space and time overhead due to a more 216complex type check at indirect call sites, as well as a need for run-time 217type information (RTTI), which may make it unsuitable for deployment. Because 218of the need for RTTI, ``-fsanitize=function`` can only be used with C++ 219programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs. 220 221On the other hand, ``-fsanitize=function`` conforms more closely with the C++ 222standard and user expectations around interaction with shared libraries; 223the identity of function pointers is maintained, and calls across shared 224library boundaries are no different from calls within a single program or 225shared library. 226 227.. _cfi-blacklist: 228 229Blacklist 230========= 231 232A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain 233source files, functions and types using the ``src``, ``fun`` and ``type`` 234entity types. 235 236In addition, if a type has a ``uuid`` attribute and the blacklist contains 237the type entry ``attr:uuid``, CFI checks are suppressed for that type. This 238allows all COM types to be easily blacklisted, which is useful as COM types 239are typically defined outside of the linked program. 240 241.. code-block:: bash 242 243 # Suppress checking for code in a file. 244 src:bad_file.cpp 245 src:bad_header.h 246 # Ignore all functions with names containing MyFooBar. 247 fun:*MyFooBar* 248 # Ignore all types in the standard library. 249 type:std::* 250 # Ignore all types with a uuid attribute. 251 type:attr:uuid 252 253.. _cfi-cross-dso: 254 255Shared library support 256====================== 257 258Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control 259flow integrity mode, which allows all CFI schemes listed above to 260apply across DSO boundaries. As in the regular CFI, each DSO must be 261built with ``-flto``. 262 263Design 264====== 265 266Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`. 267 268Publications 269============ 270 271`Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_. 272Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti. 273 274`Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_. 275Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway, 276Úlfar Erlingsson, Luis Lozano, Geoff Pike. 277