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: https://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 - ``-fsanitize=cfi-mfcall``: Indirect call via a member function pointer with 70 wrong dynamic type. 71 72You can use ``-fsanitize=cfi`` to enable all the schemes and use 73``-fno-sanitize`` flag to narrow down the set of schemes as desired. 74For example, you can build your program with 75``-fsanitize=cfi -fno-sanitize=cfi-nvcall,cfi-icall`` 76to use all schemes except for non-virtual member function call and indirect call 77checking. 78 79Remember that you have to provide ``-flto`` or ``-flto=thin`` if at 80least one CFI scheme is enabled. 81 82Trapping and Diagnostics 83======================== 84 85By default, CFI will abort the program immediately upon detecting a control 86flow integrity violation. You can use the :ref:`-fno-sanitize-trap= 87<controlling-code-generation>` flag to cause CFI to print a diagnostic 88similar to the one below before the program aborts. 89 90.. code-block:: console 91 92 bad-cast.cpp:109:7: runtime error: control flow integrity check for type 'B' failed during base-to-derived cast (vtable address 0x000000425a50) 93 0x000000425a50: note: vtable is of type 'A' 94 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 95 ^ 96 97If diagnostics are enabled, you can also configure CFI to continue program 98execution instead of aborting by using the :ref:`-fsanitize-recover= 99<controlling-code-generation>` flag. 100 101Forward-Edge CFI for Virtual Calls 102================================== 103 104This scheme checks that virtual calls take place using a vptr of the correct 105dynamic type; that is, the dynamic type of the called object must be a 106derived class of the static type of the object used to make the call. 107This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``. 108 109For this scheme to work, all translation units containing the definition 110of a virtual member function (whether inline or not), other than members 111of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO 112visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` 113enabled and be statically linked into the program. 114 115Performance 116----------- 117 118A performance overhead of less than 1% has been measured by running the 119Dromaeo benchmark suite against an instrumented version of the Chromium 120web browser. Another good performance benchmark for this mechanism is the 121virtual-call-heavy SPEC 2006 xalancbmk. 122 123Note that this scheme has not yet been optimized for binary size; an increase 124of up to 15% has been observed for Chromium. 125 126Bad Cast Checking 127================= 128 129This scheme checks that pointer casts are made to an object of the correct 130dynamic type; that is, the dynamic type of the object must be a derived class 131of the pointee type of the cast. The checks are currently only introduced 132where the class being casted to is a polymorphic class. 133 134Bad casts are not in themselves control flow integrity violations, but they 135can also create security vulnerabilities, and the implementation uses many 136of the same mechanisms. 137 138There are two types of bad cast that may be forbidden: bad casts 139from a base class to a derived class (which can be checked with 140``-fsanitize=cfi-derived-cast``), and bad casts from a pointer of 141type ``void*`` or another unrelated type (which can be checked with 142``-fsanitize=cfi-unrelated-cast``). 143 144The difference between these two types of casts is that the first is defined 145by the C++ standard to produce an undefined value, while the second is not 146in itself undefined behavior (it is well defined to cast the pointer back 147to its original type) unless the object is uninitialized and the cast is a 148``static_cast`` (see C++14 [basic.life]p5). 149 150If a program as a matter of policy forbids the second type of cast, that 151restriction can normally be enforced. However it may in some cases be necessary 152for a function to perform a forbidden cast to conform with an external API 153(e.g. the ``allocate`` member function of a standard library allocator). Such 154functions may be :ref:`blacklisted <cfi-blacklist>`. 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 or types with public :doc:`LTO 159visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` 160enabled and be statically linked into the program. 161 162Non-Virtual Member Function Call Checking 163========================================= 164 165This scheme checks that non-virtual calls take place using an object of 166the correct dynamic type; that is, the dynamic type of the called object 167must be a derived class of the static type of the object used to make the 168call. The checks are currently only introduced where the object is of a 169polymorphic class type. This CFI scheme can be enabled on its own using 170``-fsanitize=cfi-nvcall``. 171 172For this scheme to work, all translation units containing the definition 173of a virtual member function (whether inline or not), other than members 174of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO 175visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` 176enabled and be statically linked into the program. 177 178.. _cfi-strictness: 179 180Strictness 181---------- 182 183If a class has a single non-virtual base and does not introduce or override 184virtual member functions or fields other than an implicitly defined virtual 185destructor, it will have the same layout and virtual function semantics as 186its base. By default, casts to such classes are checked as if they were made 187to the least derived such class. 188 189Casting an instance of a base class to such a derived class is technically 190undefined behavior, but it is a relatively common hack for introducing 191member functions on class instances with specific properties that works under 192most compilers and should not have security implications, so we allow it by 193default. It can be disabled with ``-fsanitize=cfi-cast-strict``. 194 195Indirect Function Call Checking 196=============================== 197 198This scheme checks that function calls take place using a function of the 199correct dynamic type; that is, the dynamic type of the function must match 200the static type used at the call. This CFI scheme can be enabled on its own 201using ``-fsanitize=cfi-icall``. 202 203For this scheme to work, each indirect function call in the program, other 204than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a 205function which was either compiled with ``-fsanitize=cfi-icall`` enabled, 206or whose address was taken by a function in a translation unit compiled with 207``-fsanitize=cfi-icall``. 208 209If a function in a translation unit compiled with ``-fsanitize=cfi-icall`` 210takes the address of a function not compiled with ``-fsanitize=cfi-icall``, 211that address may differ from the address taken by a function in a translation 212unit not compiled with ``-fsanitize=cfi-icall``. This is technically a 213violation of the C and C++ standards, but it should not affect most programs. 214 215Each translation unit compiled with ``-fsanitize=cfi-icall`` must be 216statically linked into the program or shared library, and calls across 217shared library boundaries are handled as if the callee was not compiled with 218``-fsanitize=cfi-icall``. 219 220This scheme is currently supported on a limited set of targets: x86, 221x86_64, arm, arch64 and wasm. 222 223``-fsanitize-cfi-icall-generalize-pointers`` 224-------------------------------------------- 225 226Mismatched pointer types are a common cause of cfi-icall check failures. 227Translation units compiled with the ``-fsanitize-cfi-icall-generalize-pointers`` 228flag relax pointer type checking for call sites in that translation unit, 229applied across all functions compiled with ``-fsanitize=cfi-icall``. 230 231Specifically, pointers in return and argument types are treated as equivalent as 232long as the qualifiers for the type they point to match. For example, ``char*``, 233``char**``, and ``int*`` are considered equivalent types. However, ``char*`` and 234``const char*`` are considered separate types. 235 236``-fsanitize-cfi-icall-generalize-pointers`` is not compatible with 237``-fsanitize-cfi-cross-dso``. 238 239.. _cfi-canonical-jump-tables: 240 241``-fsanitize-cfi-canonical-jump-tables`` 242---------------------------------------- 243 244The default behavior of Clang's indirect function call checker will replace 245the address of each CFI-checked function in the output file's symbol table 246with the address of a jump table entry which will pass CFI checks. We refer 247to this as making the jump table `canonical`. This property allows code that 248was not compiled with ``-fsanitize=cfi-icall`` to take a CFI-valid address 249of a function, but it comes with a couple of caveats that are especially 250relevant for users of cross-DSO CFI: 251 252- There is a performance and code size overhead associated with each 253 exported function, because each such function must have an associated 254 jump table entry, which must be emitted even in the common case where the 255 function is never address-taken anywhere in the program, and must be used 256 even for direct calls between DSOs, in addition to the PLT overhead. 257 258- There is no good way to take a CFI-valid address of a function written in 259 assembly or a language not supported by Clang. The reason is that the code 260 generator would need to insert a jump table in order to form a CFI-valid 261 address for assembly functions, but there is no way in general for the 262 code generator to determine the language of the function. This may be 263 possible with LTO in the intra-DSO case, but in the cross-DSO case the only 264 information available is the function declaration. One possible solution 265 is to add a C wrapper for each assembly function, but these wrappers can 266 present a significant maintenance burden for heavy users of assembly in 267 addition to adding runtime overhead. 268 269For these reasons, we provide the option of making the jump table non-canonical 270with the flag ``-fno-sanitize-cfi-canonical-jump-tables``. When the jump 271table is made non-canonical, symbol table entries point directly to the 272function body. Any instances of a function's address being taken in C will 273be replaced with a jump table address. 274 275This scheme does have its own caveats, however. It does end up breaking 276function address equality more aggressively than the default behavior, 277especially in cross-DSO mode which normally preserves function address 278equality entirely. 279 280Furthermore, it is occasionally necessary for code not compiled with 281``-fsanitize=cfi-icall`` to take a function address that is valid 282for CFI. For example, this is necessary when a function's address 283is taken by assembly code and then called by CFI-checking C code. The 284``__attribute__((cfi_canonical_jump_table))`` attribute may be used to make 285the jump table entry of a specific function canonical so that the external 286code will end up taking a address for the function that will pass CFI checks. 287 288``-fsanitize=cfi-icall`` and ``-fsanitize=function`` 289---------------------------------------------------- 290 291This tool is similar to ``-fsanitize=function`` in that both tools check 292the types of function calls. However, the two tools occupy different points 293on the design space; ``-fsanitize=function`` is a developer tool designed 294to find bugs in local development builds, whereas ``-fsanitize=cfi-icall`` 295is a security hardening mechanism designed to be deployed in release builds. 296 297``-fsanitize=function`` has a higher space and time overhead due to a more 298complex type check at indirect call sites, as well as a need for run-time 299type information (RTTI), which may make it unsuitable for deployment. Because 300of the need for RTTI, ``-fsanitize=function`` can only be used with C++ 301programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs. 302 303On the other hand, ``-fsanitize=function`` conforms more closely with the C++ 304standard and user expectations around interaction with shared libraries; 305the identity of function pointers is maintained, and calls across shared 306library boundaries are no different from calls within a single program or 307shared library. 308 309Member Function Pointer Call Checking 310===================================== 311 312This scheme checks that indirect calls via a member function pointer 313take place using an object of the correct dynamic type. Specifically, we 314check that the dynamic type of the member function referenced by the member 315function pointer matches the "function pointer" part of the member function 316pointer, and that the member function's class type is related to the base 317type of the member function. This CFI scheme can be enabled on its own using 318``-fsanitize=cfi-mfcall``. 319 320The compiler will only emit a full CFI check if the member function pointer's 321base type is complete. This is because the complete definition of the base 322type contains information that is necessary to correctly compile the CFI 323check. To ensure that the compiler always emits a full CFI check, it is 324recommended to also pass the flag ``-fcomplete-member-pointers``, which 325enables a non-conforming language extension that requires member pointer 326base types to be complete if they may be used for a call. 327 328For this scheme to work, all translation units containing the definition 329of a virtual member function (whether inline or not), other than members 330of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO 331visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` 332enabled and be statically linked into the program. 333 334This scheme is currently not compatible with cross-DSO CFI or the 335Microsoft ABI. 336 337.. _cfi-blacklist: 338 339Blacklist 340========= 341 342A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain 343source files, functions and types using the ``src``, ``fun`` and ``type`` 344entity types. Specific CFI modes can be be specified using ``[section]`` 345headers. 346 347.. code-block:: bash 348 349 # Suppress all CFI checking for code in a file. 350 src:bad_file.cpp 351 src:bad_header.h 352 # Ignore all functions with names containing MyFooBar. 353 fun:*MyFooBar* 354 # Ignore all types in the standard library. 355 type:std::* 356 # Disable only unrelated cast checks for this function 357 [cfi-unrelated-cast] 358 fun:*UnrelatedCast* 359 # Disable CFI call checks for this function without affecting cast checks 360 [cfi-vcall|cfi-nvcall|cfi-icall] 361 fun:*BadCall* 362 363 364.. _cfi-cross-dso: 365 366Shared library support 367====================== 368 369Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control 370flow integrity mode, which allows all CFI schemes listed above to 371apply across DSO boundaries. As in the regular CFI, each DSO must be 372built with ``-flto`` or ``-flto=thin``. 373 374Normally, CFI checks will only be performed for classes that have hidden LTO 375visibility. With this flag enabled, the compiler will emit cross-DSO CFI 376checks for all classes, except for those which appear in the CFI blacklist 377or which use a ``no_sanitize`` attribute. 378 379Design 380====== 381 382Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`. 383 384Publications 385============ 386 387`Control-Flow Integrity: Principles, Implementations, and Applications <https://research.microsoft.com/pubs/64250/ccs05.pdf>`_. 388Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti. 389 390`Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_. 391Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway, 392Úlfar Erlingsson, Luis Lozano, Geoff Pike. 393