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