[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Qemu-block] [PULL 8/8] docs: add Security chapter to the documentation

From: Stefan Hajnoczi
Subject: [Qemu-block] [PULL 8/8] docs: add Security chapter to the documentation
Date: Fri, 10 May 2019 14:02:43 +0100

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

Signed-off-by: Stefan Hajnoczi <address@hidden>
Acked-by: Stefano Garzarella <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Reviewed-by: Daniel P. Berrangé <address@hidden>
Reviewed-by: Li Qiang <address@hidden>
Message-id: address@hidden
Message-Id: <address@hidden>
Signed-off-by: Stefan Hajnoczi <address@hidden>
 Makefile           |   2 +-
 docs/security.texi | 131 +++++++++++++++++++++++++++++++++++++++++++++
 qemu-doc.texi      |   3 ++
 3 files changed, 135 insertions(+), 1 deletion(-)
 create mode 100644 docs/security.texi

diff --git a/Makefile b/Makefile
index a971247cac..4a8ae0ef95 100644
--- a/Makefile
+++ b/Makefile
@@ -976,7 +976,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
        qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
        qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
        qemu-monitor-info.texi docs/qemu-block-drivers.texi \
-       docs/qemu-cpu-models.texi
+       docs/qemu-cpu-models.texi docs/security.texi
 docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
     docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
diff --git a/docs/security.texi b/docs/security.texi
new file mode 100644
index 0000000000..927764f1e6
--- /dev/null
+++ b/docs/security.texi
@@ -0,0 +1,131 @@
address@hidden Security
address@hidden Security
address@hidden Overview
+This chapter explains the security requirements that QEMU is designed to meet
+and principles for securely deploying QEMU.
address@hidden Security Requirements
+QEMU supports many different use cases, some of which have stricter security
+requirements than others.  The community has agreed on the overall security
+requirements that users may depend on.  These requirements define what is
+considered supported from a security perspective.
address@hidden Virtualization Use Case
+The virtualization use case covers cloud and virtual private server (VPS)
+hosting, as well as traditional data center and desktop virtualization.  These
+use cases rely on hardware virtualization extensions to execute guest code
+safely on the physical CPU at close-to-native speed.
+The following entities are untrusted, meaning that they may be buggy or
address@hidden Guest
address@hidden User-facing interfaces (e.g. VNC, SPICE, WebSocket)
address@hidden Network protocols (e.g. NBD, live migration)
address@hidden User-supplied files (e.g. disk images, kernels, device trees)
address@hidden Passthrough devices (e.g. PCI, USB)
address@hidden itemize
+Bugs affecting these entities are evaluated on whether they can cause damage in
+real-world use cases and treated as security bugs if this is the case.
address@hidden Non-virtualization Use Case
+The non-virtualization use case covers emulation using the Tiny Code Generator
+(TCG).  In principle the TCG and device emulation code used in conjunction with
+the non-virtualization use case should meet the same security requirements as
+the virtualization use case.  However, for historical reasons much of the
+non-virtualization use case code was not written with these security
+requirements in mind.
+Bugs affecting the non-virtualization use case are not considered security
+bugs at this time.  Users with non-virtualization use cases must not rely on
+QEMU to provide guest isolation or any security guarantees.
address@hidden Architecture
+This section describes the design principles that ensure the security
+requirements are met.
address@hidden Guest Isolation
+Guest isolation is the confinement of guest code to the virtual machine.  When
+guest code gains control of execution on the host this is called escaping the
+virtual machine.  Isolation also includes resource limits such as throttling of
+CPU, memory, disk, or network.  Guests must be unable to exceed their resource
+QEMU presents an attack surface to the guest in the form of emulated devices.
+The guest must not be able to gain control of QEMU.  Bugs in emulated devices
+could allow malicious guests to gain code execution in QEMU.  At this point the
+guest has escaped the virtual machine and is able to act in the context of the
+QEMU process on the host.
+Guests often interact with other guests and share resources with them.  A
+malicious guest must not gain control of other guests or access their data.
+Disk image files and network traffic must be protected from other guests unless
+explicitly shared between them by the user.
address@hidden Principle of Least Privilege
+The principle of least privilege states that each component only has access to
+the privileges necessary for its function.  In the case of QEMU this means that
+each process only has access to resources belonging to the guest.
+The QEMU process should not have access to any resources that are inaccessible
+to the guest.  This way the guest does not gain anything by escaping into the
+QEMU process since it already has access to those same resources from within
+the guest.
+Following the principle of least privilege immediately fulfills guest isolation
+requirements.  For example, guest A only has access to its own disk image file
address@hidden and not guest B's disk image file @code{b.img}.
+In reality certain resources are inaccessible to the guest but must be
+available to QEMU to perform its function.  For example, host system calls are
+necessary for QEMU but are not exposed to guests.  A guest that escapes into
+the QEMU process can then begin invoking host system calls.
+New features must be designed to follow the principle of least privilege.
+Should this not be possible for technical reasons, the security risk must be
+clearly documented so users are aware of the trade-off of enabling the feature.
address@hidden Isolation mechanisms
+Several isolation mechanisms are available to realize this architecture of
+guest isolation and the principle of least privilege.  With the exception of
+Linux seccomp, these mechanisms are all deployed by management tools that
+launch QEMU, such as libvirt.  They are also platform-specific so they are only
+described briefly for Linux here.
+The fundamental isolation mechanism is that QEMU processes must run as
+unprivileged users.  Sometimes it seems more convenient to launch QEMU as
+root to give it access to host devices (e.g. @code{/dev/net/tun}) but this 
poses a
+huge security risk.  File descriptor passing can be used to give an otherwise
+unprivileged QEMU process access to host devices without running QEMU as root.
+It is also possible to launch QEMU as a non-root user and configure UNIX groups
+for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes.
+Some Linux distros already ship with UNIX groups for these devices by default.
address@hidden SELinux and AppArmor make it possible to confine processes 
beyond the
+traditional UNIX process and file permissions model.  They restrict the QEMU
+process from accessing processes and files on the host system that are not
+needed by QEMU.
address@hidden Resource limits and cgroup controllers provide throughput and 
+limits on key resources such as CPU time, memory, and I/O bandwidth.
address@hidden Linux namespaces can be used to make process, file system, and 
other system
+resources unavailable to QEMU.  A namespaced QEMU process is restricted to only
+those resources that were granted to it.
address@hidden Linux seccomp is available via the QEMU @option{--sandbox} 
option.  It disables
+system calls that are not needed by QEMU, thereby reducing the host kernel
+attack surface.
address@hidden itemize
diff --git a/qemu-doc.texi b/qemu-doc.texi
index ae3c3f9632..577d1e8376 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -38,6 +38,7 @@
 * QEMU Guest Agent::
 * QEMU User space emulator::
 * System requirements::
+* Security::
 * Implementation notes::
 * Deprecated features::
 * Supported build platforms::
@@ -2878,6 +2879,8 @@ added with Linux 4.5 which is supported by the major 
distros. And even
 if RHEL7 has kernel 3.10, KVM there has the required functionality there
 to make it close to a 4.5 or newer kernel.
address@hidden docs/security.texi
 @include qemu-tech.texi
 @include qemu-deprecated.texi

reply via email to

[Prev in Thread] Current Thread [Next in Thread]