docs/devel/control-flow-integrity.rst

   1 ============================
   2 Control-Flow Integrity (CFI)
   3 ============================
   4
   5 This document describes the current control-flow integrity (CFI) mechanism in
   6 QEMU. How it can be enabled, its benefits and deficiencies, and how it affects
   7 new and existing code in QEMU
   8
   9 Basics
  10 ------
  11
  12 CFI is a hardening technique that focusing on guaranteeing that indirect
  13 function calls have not been altered by an attacker.
  14 The type used in QEMU is a forward-edge control-flow integrity that ensures
  15 function calls performed through function pointers, always call a "compatible"
  16 function. A compatible function is a function with the same signature of the
  17 function pointer declared in the source code.
  18
  19 This type of CFI is entirely compiler-based and relies on the compiler knowing
  20 the signature of every function and every function pointer used in the code.
  21 As of now, the only compiler that provides support for CFI is Clang.
  22
  23 CFI is best used on production binaries, to protect against unknown attack
  24 vectors.
  25
  26 In case of a CFI violation (i.e. call to a non-compatible function) QEMU will
  27 terminate abruptly, to stop the possible attack.
  28
  29 Building with CFI
  30 -----------------
  31
  32 NOTE: CFI requires the use of link-time optimization. Therefore, when CFI is
  33 selected, LTO will be automatically enabled.
  34
  35 To build with CFI, the minimum requirement is Clang 6+. If you
  36 are planning to also enable fuzzing, then Clang 11+ is needed (more on this
  37 later).
  38
  39 Given the use of LTO, a version of AR that supports LLVM IR is required.
  40 The easies way of doing this is by selecting the AR provided by LLVM::
  41
  42  AR=llvm-ar-9 CC=clang-9 CXX=lang++-9 /path/to/configure --enable-cfi
  43
  44 CFI is enabled on every binary produced.
  45
  46 If desired, an additional flag to increase the verbosity of the output in case
  47 of a CFI violation is offered (``--enable-debug-cfi``).
  48
  49 Using QEMU built with CFI
  50 -------------------------
  51
  52 A binary with CFI will work exactly like a standard binary. In case of a CFI
  53 violation, the binary will terminate with an illegal instruction signal.
  54
  55 Incompatible code with CFI
  56 --------------------------
  57
  58 As mentioned above, CFI is entirely compiler-based and therefore relies on
  59 compile-time knowledge of the code. This means that, while generally supported
  60 for most code, some specific use pattern can break CFI compatibility, and
  61 create false-positives. The two main patterns that can cause issues are:
  62
  63 * Just-in-time compiled code: since such code is created at runtime, the jump
  64   to the buffer containing JIT code will fail.
  65
  66 * Libraries loaded dynamically, e.g. with dlopen/dlsym, since the library was
  67   not known at compile time.
  68
  69 Current areas of QEMU that are not entirely compatible with CFI are:
  70
  71 1. TCG, since the idea of TCG is to pre-compile groups of instructions at
  72    runtime to speed-up interpretation, quite similarly to a JIT compiler
  73
  74 2. TCI, where the interpreter has to interpret the generic *call* operation
  75
  76 3. Plugins, since a plugin is implemented as an external library
  77
  78 4. Modules, since they are implemented as an external library
  79
  80 5. Directly calling signal handlers from the QEMU source code, since the
  81    signal handler may have been provided by an external library or even plugged
  82    at runtime.
  83
  84 Disabling CFI for a specific function
  85 -------------------------------------
  86
  87 If you are working on function that is performing a call using an
  88 incompatible way, as described before, you can selectively disable CFI checks
  89 for such function by using the decorator ``QEMU_DISABLE_CFI`` at function
  90 definition, and add an explanation on why the function is not compatible
  91 with CFI. An example of the use of ``QEMU_DISABLE_CFI`` is provided here::
  92
  93         /*
  94          * Disable CFI checks.
  95          * TCG creates binary blobs at runtime, with the transformed code.
  96          * A TB is a blob of binary code, created at runtime and called with an
  97          * indirect function call. Since such function did not exist at compile time,
  98          * the CFI runtime has no way to verify its signature and would fail.
  99          * TCG is not considered a security-sensitive part of QEMU so this does not
 100          * affect the impact of CFI in environment with high security requirements
 101          */
 102         QEMU_DISABLE_CFI
 103         static inline tcg_target_ulong cpu_tb_exec(CPUState *cpu, TranslationBlock *itb)
 104
 105 NOTE: CFI needs to be disabled at the **caller** function, (i.e. a compatible
 106 cfi function that calls a non-compatible one), since the check is performed
 107 when the function call is performed.
 108
 109 CFI and fuzzing
 110 ---------------
 111
 112 There is generally no advantage of using CFI and fuzzing together, because
 113 they target different environments (production for CFI, debug for fuzzing).
 114
 115 CFI could be used in conjunction with fuzzing to identify a broader set of
 116 bugs that may not end immediately in a segmentation fault or triggering
 117 an assertion. However, other sanitizers such as address and ub sanitizers
 118 can identify such bugs in a more precise way than CFI.
 119
 120 There is, however, an interesting use case in using CFI in conjunction with
 121 fuzzing, that is to make sure that CFI is not triggering any false positive
 122 in remote-but-possible parts of the code.
 123
 124 CFI can be enabled with fuzzing, but with some caveats:
 125 1. Fuzzing relies on the linker performing function wrapping at link-time.
 126 The standard BFD linker does not support function wrapping when LTO is
 127 also enabled. The workaround is to use LLVM's lld linker.
 128 2. Fuzzing also relies on a custom linker script, which is only supported by
 129 lld with version 11+.
 130
 131 In other words, to compile with fuzzing and CFI, clang 11+ is required, and
 132 lld needs to be used as a linker::
 133
 134  AR=llvm-ar-11 CC=clang-11 CXX=lang++-11 /path/to/configure --enable-cfi \
 135                            -enable-fuzzing --extra-ldflags="-fuse-ld=lld"
 136
 137 and then, compile the fuzzers as usual.