docs/devel/secure-coding-practices.rst

   1 =======================
   2 Secure Coding Practices
   3 =======================
   4 This document covers topics that both developers and security researchers must
   5 be aware of so that they can develop safe code and audit existing code
   6 properly.
   7
   8 Reporting Security Bugs
   9 -----------------------
  10 For details on how to report security bugs or ask questions about potential
  11 security bugs, see the `Security Process wiki page
  12 <https://wiki.qemu.org/SecurityProcess>`_.
  13
  14 General Secure C Coding Practices
  15 ---------------------------------
  16 Most CVEs (security bugs) reported against QEMU are not specific to
  17 virtualization or emulation.  They are simply C programming bugs.  Therefore
  18 it's critical to be aware of common classes of security bugs.
  19
  20 There is a wide selection of resources available covering secure C coding.  For
  21 example, the `CERT C Coding Standard
  22 <https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard>`_
  23 covers the most important classes of security bugs.
  24
  25 Instead of describing them in detail here, only the names of the most important
  26 classes of security bugs are mentioned:
  27
  28 * Buffer overflows
  29 * Use-after-free and double-free
  30 * Integer overflows
  31 * Format string vulnerabilities
  32
  33 Some of these classes of bugs can be detected by analyzers.  Static analysis is
  34 performed regularly by Coverity and the most obvious of these bugs are even
  35 reported by compilers.  Dynamic analysis is possible with valgrind, tsan, and
  36 asan.
  37
  38 Input Validation
  39 ----------------
  40 Inputs from the guest or external sources (e.g. network, files) cannot be
  41 trusted and may be invalid.  Inputs must be checked before using them in a way
  42 that could crash the program, expose host memory to the guest, or otherwise be
  43 exploitable by an attacker.
  44
  45 The most sensitive attack surface is device emulation.  All hardware register
  46 accesses and data read from guest memory must be validated.  A typical example
  47 is a device that contains multiple units that are selectable by the guest via
  48 an index register::
  49
  50   typedef struct {
  51       ProcessingUnit unit[2];
  52       ...
  53   } MyDeviceState;
  54
  55   static void mydev_writel(void *opaque, uint32_t addr, uint32_t val)
  56   {
  57       MyDeviceState *mydev = opaque;
  58       ProcessingUnit *unit;
  59
  60       switch (addr) {
  61       case MYDEV_SELECT_UNIT:
  62           unit = &mydev->unit[val];   <-- this input wasn't validated!
  63           ...
  64       }
  65   }
  66
  67 If ``val`` is not in range [0, 1] then an out-of-bounds memory access will take
  68 place when ``unit`` is dereferenced.  The code must check that ``val`` is 0 or
  69 1 and handle the case where it is invalid.
  70
  71 Unexpected Device Accesses
  72 --------------------------
  73 The guest may access device registers in unusual orders or at unexpected
  74 moments.  Device emulation code must not assume that the guest follows the
  75 typical "theory of operation" presented in driver writer manuals.  The guest
  76 may make nonsense accesses to device registers such as starting operations
  77 before the device has been fully initialized.
  78
  79 A related issue is that device emulation code must be prepared for unexpected
  80 device register accesses while asynchronous operations are in progress.  A
  81 well-behaved guest might wait for a completion interrupt before accessing
  82 certain device registers.  Device emulation code must handle the case where the
  83 guest overwrites registers or submits further requests before an ongoing
  84 request completes.  Unexpected accesses must not cause memory corruption or
  85 leaks in QEMU.
  86
  87 Invalid device register accesses can be reported with
  88 ``qemu_log_mask(LOG_GUEST_ERROR, ...)``.  The ``-d guest_errors`` command-line
  89 option enables these log messages.
  90
  91 Live Migration
  92 --------------
  93 Device state can be saved to disk image files and shared with other users.
  94 Live migration code must validate inputs when loading device state so an
  95 attacker cannot gain control by crafting invalid device states.  Device state
  96 is therefore considered untrusted even though it is typically generated by QEMU
  97 itself.
  98
  99 Guest Memory Access Races
 100 -------------------------
 101 Guests with multiple vCPUs may modify guest RAM while device emulation code is
 102 running.  Device emulation code must copy in descriptors and other guest RAM
 103 structures and only process the local copy.  This prevents
 104 time-of-check-to-time-of-use (TOCTOU) race conditions that could cause QEMU to
 105 crash when a vCPU thread modifies guest RAM while device emulation is
 106 processing it.
 107
 108 Use of null-co block drivers
 109 ----------------------------
 110
 111 The ``null-co`` block driver is designed for performance: its read accesses are
 112 not initialized by default. In case this driver has to be used for security
 113 research, it must be used with the ``read-zeroes=on`` option which fills read
 114 buffers with zeroes. Security issues reported with the default
 115 (``read-zeroes=off``) will be discarded.