From a111824382dad27db8c358b2b9b26cdf30eaf49f Mon Sep 17 00:00:00 2001 From: Daniele Buono Date: Fri, 4 Dec 2020 18:06:15 -0500 Subject: docs: Add CFI Documentation Document how to compile with CFI and how to maintain CFI-safe code Signed-off-by: Daniele Buono Message-Id: <20201204230615.2392-6-dbuono@linux.vnet.ibm.com> [Make build system section in index.rst and add the new file. - Paolo] Signed-off-by: Paolo Bonzini --- docs/devel/control-flow-integrity.rst | 137 ++++++++++++++++++++++++++++++++++ docs/devel/index.rst | 5 +- 2 files changed, 140 insertions(+), 2 deletions(-) create mode 100644 docs/devel/control-flow-integrity.rst (limited to 'docs') diff --git a/docs/devel/control-flow-integrity.rst b/docs/devel/control-flow-integrity.rst new file mode 100644 index 0000000000..d89d70733d --- /dev/null +++ b/docs/devel/control-flow-integrity.rst @@ -0,0 +1,137 @@ +============================ +Control-Flow Integrity (CFI) +============================ + +This document describes the current control-flow integrity (CFI) mechanism in +QEMU. How it can be enabled, its benefits and deficiencies, and how it affects +new and existing code in QEMU + +Basics +------ + +CFI is a hardening technique that focusing on guaranteeing that indirect +function calls have not been altered by an attacker. +The type used in QEMU is a forward-edge control-flow integrity that ensures +function calls performed through function pointers, always call a "compatible" +function. A compatible function is a function with the same signature of the +function pointer declared in the source code. + +This type of CFI is entirely compiler-based and relies on the compiler knowing +the signature of every function and every function pointer used in the code. +As of now, the only compiler that provides support for CFI is Clang. + +CFI is best used on production binaries, to protect against unknown attack +vectors. + +In case of a CFI violation (i.e. call to a non-compatible function) QEMU will +terminate abruptly, to stop the possible attack. + +Building with CFI +----------------- + +NOTE: CFI requires the use of link-time optimization. Therefore, when CFI is +selected, LTO will be automatically enabled. + +To build with CFI, the minimum requirement is Clang 6+. If you +are planning to also enable fuzzing, then Clang 11+ is needed (more on this +later). + +Given the use of LTO, a version of AR that supports LLVM IR is required. +The easies way of doing this is by selecting the AR provided by LLVM:: + + AR=llvm-ar-9 CC=clang-9 CXX=lang++-9 /path/to/configure --enable-cfi + +CFI is enabled on every binary produced. + +If desired, an additional flag to increase the verbosity of the output in case +of a CFI violation is offered (``--enable-debug-cfi``). + +Using QEMU built with CFI +------------------------- + +A binary with CFI will work exactly like a standard binary. In case of a CFI +violation, the binary will terminate with an illegal instruction signal. + +Incompatible code with CFI +-------------------------- + +As mentioned above, CFI is entirely compiler-based and therefore relies on +compile-time knowledge of the code. This means that, while generally supported +for most code, some specific use pattern can break CFI compatibility, and +create false-positives. The two main patterns that can cause issues are: + +* Just-in-time compiled code: since such code is created at runtime, the jump + to the buffer containing JIT code will fail. + +* Libraries loaded dynamically, e.g. with dlopen/dlsym, since the library was + not known at compile time. + +Current areas of QEMU that are not entirely compatible with CFI are: + +1. TCG, since the idea of TCG is to pre-compile groups of instructions at + runtime to speed-up interpretation, quite similarly to a JIT compiler + +2. TCI, where the interpreter has to interpret the generic *call* operation + +3. Plugins, since a plugin is implemented as an external library + +4. Modules, since they are implemented as an external library + +5. Directly calling signal handlers from the QEMU source code, since the + signal handler may have been provided by an external library or even plugged + at runtime. + +Disabling CFI for a specific function +------------------------------------- + +If you are working on function that is performing a call using an +incompatible way, as described before, you can selectively disable CFI checks +for such function by using the decorator ``QEMU_DISABLE_CFI`` at function +definition, and add an explanation on why the function is not compatible +with CFI. An example of the use of ``QEMU_DISABLE_CFI`` is provided here:: + + /* + * Disable CFI checks. + * TCG creates binary blobs at runtime, with the transformed code. + * A TB is a blob of binary code, created at runtime and called with an + * indirect function call. Since such function did not exist at compile time, + * the CFI runtime has no way to verify its signature and would fail. + * TCG is not considered a security-sensitive part of QEMU so this does not + * affect the impact of CFI in environment with high security requirements + */ + QEMU_DISABLE_CFI + static inline tcg_target_ulong cpu_tb_exec(CPUState *cpu, TranslationBlock *itb) + +NOTE: CFI needs to be disabled at the **caller** function, (i.e. a compatible +cfi function that calls a non-compatible one), since the check is performed +when the function call is performed. + +CFI and fuzzing +--------------- + +There is generally no advantage of using CFI and fuzzing together, because +they target different environments (production for CFI, debug for fuzzing). + +CFI could be used in conjunction with fuzzing to identify a broader set of +bugs that may not end immediately in a segmentation fault or triggering +an assertion. However, other sanitizers such as address and ub sanitizers +can identify such bugs in a more precise way than CFI. + +There is, however, an interesting use case in using CFI in conjunction with +fuzzing, that is to make sure that CFI is not triggering any false positive +in remote-but-possible parts of the code. + +CFI can be enabled with fuzzing, but with some caveats: +1. Fuzzing relies on the linker performing function wrapping at link-time. +The standard BFD linker does not support function wrapping when LTO is +also enabled. The workaround is to use LLVM's lld linker. +2. Fuzzing also relies on a custom linker script, which is only supported by +lld with version 11+. + +In other words, to compile with fuzzing and CFI, clang 11+ is required, and +lld needs to be used as a linker:: + + AR=llvm-ar-11 CC=clang-11 CXX=lang++-11 /path/to/configure --enable-cfi \ + -enable-fuzzing --extra-ldflags="-fuse-ld=lld" + +and then, compile the fuzzers as usual. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index f10ed77e4c..ea0e1e17ae 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -15,14 +15,15 @@ Contents: build-system kconfig + testing + fuzzing + control-flow-integrity loads-stores memory migration atomics stable-process - testing qtest - fuzzing decodetree secure-coding-practices tcg -- cgit v1.2.3-55-g7522 From 0a18911074a1b379540446c6a432b796ab7c436d Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 17 Nov 2020 14:58:32 +0100 Subject: meson: cleanup Kconfig.host handling Build the array of command line arguments coming from config_host once for all targets. Add all accelerators to accel/Kconfig so that the command line arguments for accelerators can be computed easily in the existing "foreach sym: accelerators" loop. Reviewed-by: Marc-André Lureau Signed-off-by: Paolo Bonzini --- accel/Kconfig | 9 +++++++++ docs/devel/kconfig.rst | 19 +++++++++---------- meson.build | 43 +++++++++++++++++-------------------------- 3 files changed, 35 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/accel/Kconfig b/accel/Kconfig index 2ad94a3839..461104c771 100644 --- a/accel/Kconfig +++ b/accel/Kconfig @@ -1,3 +1,12 @@ +config WHPX + bool + +config HAX + bool + +config HVF + bool + config TCG bool diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst index 336ba0e8e5..cb2d7ffac0 100644 --- a/docs/devel/kconfig.rst +++ b/docs/devel/kconfig.rst @@ -288,21 +288,20 @@ they will include all these symbols and some help text on what they do. ---------------- In some special cases, a configurable element depends on host features -that are detected by QEMU's configure script; for example some devices -depend on the availability of KVM or on the presence of a library on -the host. +that are detected by QEMU's configure or ``meson.build`` scripts; for +example some devices depend on the availability of KVM or on the presence +of a library on the host. These symbols should be listed in ``Kconfig.host`` like this:: - config KVM + config TPM bool -and also listed as follows in the top-level Makefile's ``MINIKCONF_ARGS`` +and also listed as follows in the top-level meson.build's host_kconfig variable:: - MINIKCONF_ARGS = \ - $@ $*/config-devices.mak.d $< $(MINIKCONF_INPUTS) \ - CONFIG_KVM=$(CONFIG_KVM) \ - CONFIG_SPICE=$(CONFIG_SPICE) \ - CONFIG_TPM=$(CONFIG_TPM) \ + host_kconfig = \ + ('CONFIG_TPM' in config_host ? ['CONFIG_TPM=y'] : []) + \ + ('CONFIG_SPICE' in config_host ? ['CONFIG_SPICE=y'] : []) + \ + ('CONFIG_IVSHMEM' in config_host ? ['CONFIG_IVSHMEM=y'] : []) + \ ... diff --git a/meson.build b/meson.build index 0e70fe7a89..d114a0137b 100644 --- a/meson.build +++ b/meson.build @@ -958,21 +958,19 @@ if link_language == 'cpp' } endif -kconfig_external_symbols = [ - 'CONFIG_KVM', - 'CONFIG_XEN', - 'CONFIG_TPM', - 'CONFIG_SPICE', - 'CONFIG_IVSHMEM', - 'CONFIG_OPENGL', - 'CONFIG_X11', - 'CONFIG_VHOST_USER', - 'CONFIG_VHOST_VDPA', - 'CONFIG_VHOST_KERNEL', - 'CONFIG_VIRTFS', - 'CONFIG_LINUX', - 'CONFIG_PVRDMA', -] +host_kconfig = \ + ('CONFIG_TPM' in config_host ? ['CONFIG_TPM=y'] : []) + \ + ('CONFIG_SPICE' in config_host ? ['CONFIG_SPICE=y'] : []) + \ + ('CONFIG_IVSHMEM' in config_host ? ['CONFIG_IVSHMEM=y'] : []) + \ + ('CONFIG_OPENGL' in config_host ? ['CONFIG_OPENGL=y'] : []) + \ + ('CONFIG_X11' in config_host ? ['CONFIG_X11=y'] : []) + \ + ('CONFIG_VHOST_USER' in config_host ? ['CONFIG_VHOST_USER=y'] : []) + \ + ('CONFIG_VHOST_VDPA' in config_host ? ['CONFIG_VHOST_VDPA=y'] : []) + \ + ('CONFIG_VHOST_KERNEL' in config_host ? ['CONFIG_VHOST_KERNEL=y'] : []) + \ + ('CONFIG_VIRTFS' in config_host ? ['CONFIG_VIRTFS=y'] : []) + \ + ('CONFIG_LINUX' in config_host ? ['CONFIG_LINUX=y'] : []) + \ + ('CONFIG_PVRDMA' in config_host ? ['CONFIG_PVRDMA=y'] : []) + ignored = [ 'TARGET_XML_FILES', 'TARGET_ABI_DIR', 'TARGET_ARCH' ] default_targets = 'CONFIG_DEFAULT_TARGETS' in config_host @@ -1007,7 +1005,7 @@ foreach target : target_dirs } endif - have_accel = false + accel_kconfig = [] foreach sym: accelerators if sym == 'CONFIG_TCG' or target in accelerator_targets.get(sym, []) config_target += { sym: 'y' } @@ -1015,10 +1013,10 @@ foreach target : target_dirs if sym == 'CONFIG_XEN' and have_xen_pci_passthrough config_target += { 'CONFIG_XEN_PCI_PASSTHROUGH': 'y' } endif - have_accel = true + accel_kconfig += [ sym + '=y' ] endif endforeach - if not have_accel + if accel_kconfig.length() == 0 if default_targets continue endif @@ -1072,13 +1070,6 @@ foreach target : target_dirs configuration: config_target_data)} if target.endswith('-softmmu') - base_kconfig = [] - foreach sym : kconfig_external_symbols - if sym in config_target or sym in config_host - base_kconfig += '@0@=y'.format(sym) - endif - endforeach - config_devices_mak = target + '-config-devices.mak' config_devices_mak = configure_file( input: ['default-configs/devices' / target + '.mak', 'Kconfig'], @@ -1087,7 +1078,7 @@ foreach target : target_dirs capture: true, command: [minikconf, config_host['CONFIG_MINIKCONF_MODE'], config_devices_mak, '@DEPFILE@', '@INPUT@', - base_kconfig]) + host_kconfig, accel_kconfig]) config_devices_data = configuration_data() config_devices = keyval.load(config_devices_mak) -- cgit v1.2.3-55-g7522