Browse Source

docs: add Security chapter to the documentation

This new chapter in the QEMU documentation covers the security
requirements that QEMU is designed to meet and principles for securely
deploying QEMU.

It is just a starting point that can be extended in the future with more
information.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Acked-by: Stefano Garzarella <sgarzare@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Li Qiang <liq3ea@gmail.com>
Message-id: 2019050912.16294-3-stefanha@redhat.com
Message-Id: <2019050912.16294-3-stefanha@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
master
Stefan Hajnoczi 1 month ago
parent
commit
e84125761f
3 changed files with 135 additions and 1 deletions
  1. 1
    1
      Makefile
  2. 131
    0
      docs/security.texi
  3. 3
    0
      qemu-doc.texi

+ 1
- 1
Makefile View File

@@ -976,7 +976,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
976 976
 	qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
977 977
 	qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
978 978
 	qemu-monitor-info.texi docs/qemu-block-drivers.texi \
979
-	docs/qemu-cpu-models.texi
979
+	docs/qemu-cpu-models.texi docs/security.texi
980 980
 
981 981
 docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
982 982
     docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \

+ 131
- 0
docs/security.texi View File

@@ -0,0 +1,131 @@
1
+@node Security
2
+@chapter Security
3
+
4
+@section Overview
5
+
6
+This chapter explains the security requirements that QEMU is designed to meet
7
+and principles for securely deploying QEMU.
8
+
9
+@section Security Requirements
10
+
11
+QEMU supports many different use cases, some of which have stricter security
12
+requirements than others.  The community has agreed on the overall security
13
+requirements that users may depend on.  These requirements define what is
14
+considered supported from a security perspective.
15
+
16
+@subsection Virtualization Use Case
17
+
18
+The virtualization use case covers cloud and virtual private server (VPS)
19
+hosting, as well as traditional data center and desktop virtualization.  These
20
+use cases rely on hardware virtualization extensions to execute guest code
21
+safely on the physical CPU at close-to-native speed.
22
+
23
+The following entities are untrusted, meaning that they may be buggy or
24
+malicious:
25
+
26
+@itemize
27
+@item Guest
28
+@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
29
+@item Network protocols (e.g. NBD, live migration)
30
+@item User-supplied files (e.g. disk images, kernels, device trees)
31
+@item Passthrough devices (e.g. PCI, USB)
32
+@end itemize
33
+
34
+Bugs affecting these entities are evaluated on whether they can cause damage in
35
+real-world use cases and treated as security bugs if this is the case.
36
+
37
+@subsection Non-virtualization Use Case
38
+
39
+The non-virtualization use case covers emulation using the Tiny Code Generator
40
+(TCG).  In principle the TCG and device emulation code used in conjunction with
41
+the non-virtualization use case should meet the same security requirements as
42
+the virtualization use case.  However, for historical reasons much of the
43
+non-virtualization use case code was not written with these security
44
+requirements in mind.
45
+
46
+Bugs affecting the non-virtualization use case are not considered security
47
+bugs at this time.  Users with non-virtualization use cases must not rely on
48
+QEMU to provide guest isolation or any security guarantees.
49
+
50
+@section Architecture
51
+
52
+This section describes the design principles that ensure the security
53
+requirements are met.
54
+
55
+@subsection Guest Isolation
56
+
57
+Guest isolation is the confinement of guest code to the virtual machine.  When
58
+guest code gains control of execution on the host this is called escaping the
59
+virtual machine.  Isolation also includes resource limits such as throttling of
60
+CPU, memory, disk, or network.  Guests must be unable to exceed their resource
61
+limits.
62
+
63
+QEMU presents an attack surface to the guest in the form of emulated devices.
64
+The guest must not be able to gain control of QEMU.  Bugs in emulated devices
65
+could allow malicious guests to gain code execution in QEMU.  At this point the
66
+guest has escaped the virtual machine and is able to act in the context of the
67
+QEMU process on the host.
68
+
69
+Guests often interact with other guests and share resources with them.  A
70
+malicious guest must not gain control of other guests or access their data.
71
+Disk image files and network traffic must be protected from other guests unless
72
+explicitly shared between them by the user.
73
+
74
+@subsection Principle of Least Privilege
75
+
76
+The principle of least privilege states that each component only has access to
77
+the privileges necessary for its function.  In the case of QEMU this means that
78
+each process only has access to resources belonging to the guest.
79
+
80
+The QEMU process should not have access to any resources that are inaccessible
81
+to the guest.  This way the guest does not gain anything by escaping into the
82
+QEMU process since it already has access to those same resources from within
83
+the guest.
84
+
85
+Following the principle of least privilege immediately fulfills guest isolation
86
+requirements.  For example, guest A only has access to its own disk image file
87
+@code{a.img} and not guest B's disk image file @code{b.img}.
88
+
89
+In reality certain resources are inaccessible to the guest but must be
90
+available to QEMU to perform its function.  For example, host system calls are
91
+necessary for QEMU but are not exposed to guests.  A guest that escapes into
92
+the QEMU process can then begin invoking host system calls.
93
+
94
+New features must be designed to follow the principle of least privilege.
95
+Should this not be possible for technical reasons, the security risk must be
96
+clearly documented so users are aware of the trade-off of enabling the feature.
97
+
98
+@subsection Isolation mechanisms
99
+
100
+Several isolation mechanisms are available to realize this architecture of
101
+guest isolation and the principle of least privilege.  With the exception of
102
+Linux seccomp, these mechanisms are all deployed by management tools that
103
+launch QEMU, such as libvirt.  They are also platform-specific so they are only
104
+described briefly for Linux here.
105
+
106
+The fundamental isolation mechanism is that QEMU processes must run as
107
+unprivileged users.  Sometimes it seems more convenient to launch QEMU as
108
+root to give it access to host devices (e.g. @code{/dev/net/tun}) but this poses a
109
+huge security risk.  File descriptor passing can be used to give an otherwise
110
+unprivileged QEMU process access to host devices without running QEMU as root.
111
+It is also possible to launch QEMU as a non-root user and configure UNIX groups
112
+for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes.
113
+Some Linux distros already ship with UNIX groups for these devices by default.
114
+
115
+@itemize
116
+@item SELinux and AppArmor make it possible to confine processes beyond the
117
+traditional UNIX process and file permissions model.  They restrict the QEMU
118
+process from accessing processes and files on the host system that are not
119
+needed by QEMU.
120
+
121
+@item Resource limits and cgroup controllers provide throughput and utilization
122
+limits on key resources such as CPU time, memory, and I/O bandwidth.
123
+
124
+@item Linux namespaces can be used to make process, file system, and other system
125
+resources unavailable to QEMU.  A namespaced QEMU process is restricted to only
126
+those resources that were granted to it.
127
+
128
+@item Linux seccomp is available via the QEMU @option{--sandbox} option.  It disables
129
+system calls that are not needed by QEMU, thereby reducing the host kernel
130
+attack surface.
131
+@end itemize

+ 3
- 0
qemu-doc.texi View File

@@ -38,6 +38,7 @@
38 38
 * QEMU Guest Agent::
39 39
 * QEMU User space emulator::
40 40
 * System requirements::
41
+* Security::
41 42
 * Implementation notes::
42 43
 * Deprecated features::
43 44
 * Supported build platforms::
@@ -2878,6 +2879,8 @@ added with Linux 4.5 which is supported by the major distros. And even
2878 2879
 if RHEL7 has kernel 3.10, KVM there has the required functionality there
2879 2880
 to make it close to a 4.5 or newer kernel.
2880 2881
 
2882
+@include docs/security.texi
2883
+
2881 2884
 @include qemu-tech.texi
2882 2885
 
2883 2886
 @include qemu-deprecated.texi

Loading…
Cancel
Save