On Tuesday, February 25, 2020, Peter Maydell <peter.mayd...@linaro.org>
wrote:
> security.texi is included from qemu-doc.texi but is not used
> in the qemu.1 manpage. So we can do a straightforward conversion
> of the contents, which go into the system manual.
>
> Signed-off-by: Peter Maydell <peter.mayd...@linaro.org>
> ---
FWIW:
Reviewed-by: Aleksandar Markovic <amarko...@wavecomp.com>
> Makefile | 2 +-
> docs/system/index.rst | 1 +
> docs/{security.texi => system/security.rst} | 82 +++++++++++----------
> qemu-doc.texi | 3 -
> 4 files changed, 46 insertions(+), 42 deletions(-)
> rename docs/{security.texi => system/security.rst} (77%)
>
> diff --git a/Makefile b/Makefile
> index aa9cc0b5847..5f0f803b471 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1117,7 +1117,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf
> qemu-doc.txt: \
> qemu-tech.texi qemu-option-trace.texi \
> qemu-deprecated.texi qemu-monitor.texi \
> qemu-monitor-info.texi \
> - docs/qemu-cpu-models.texi docs/security.texi
> + docs/qemu-cpu-models.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/system/index.rst b/docs/system/index.rst
> index f66e6ea585c..794e5d8de03 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -15,3 +15,4 @@ Contents:
> :maxdepth: 2
>
> qemu-block-drivers
> + security
> diff --git a/docs/security.texi b/docs/system/security.rst
> similarity index 77%
> rename from docs/security.texi
> rename to docs/system/security.rst
> index 0d6b30edfc0..f2092c8768b 100644
> --- a/docs/security.texi
> +++ b/docs/system/security.rst
> @@ -1,19 +1,22 @@
> -@node Security
> -@chapter Security
> +Security
> +========
>
> -@section Overview
> +Overview
> +--------
>
> This chapter explains the security requirements that QEMU is designed to
> meet
> and principles for securely deploying QEMU.
>
> -@section Security Requirements
> +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.
>
> -@subsection Virtualization Use Case
> +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
> @@ -23,18 +26,17 @@ safely on the physical CPU at close-to-native speed.
> The following entities are untrusted, meaning that they may be buggy or
> malicious:
>
> -@itemize
> -@item Guest
> -@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
> -@item Network protocols (e.g. NBD, live migration)
> -@item User-supplied files (e.g. disk images, kernels, device trees)
> -@item Passthrough devices (e.g. PCI, USB)
> -@end itemize
> +- Guest
> +- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
> +- Network protocols (e.g. NBD, live migration)
> +- User-supplied files (e.g. disk images, kernels, device trees)
> +- Passthrough devices (e.g. PCI, USB)
>
> 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.
>
> -@subsection Non-virtualization Use Case
> +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
> @@ -47,12 +49,14 @@ 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.
>
> -@section Architecture
> +Architecture
> +------------
>
> This section describes the design principles that ensure the security
> requirements are met.
>
> -@subsection Guest Isolation
> +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
> @@ -71,7 +75,8 @@ 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.
>
> -@subsection Principle of Least Privilege
> +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
> @@ -84,7 +89,7 @@ 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
> -@code{a.img} and not guest B's disk image file @code{b.img}.
> +``a.img`` and not guest B's disk image file ``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
> @@ -95,7 +100,8 @@ 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.
>
> -@subsection Isolation mechanisms
> +Isolation mechanisms
> +''''''''''''''''''''
>
> Several isolation mechanisms are available to realize this architecture of
> guest isolation and the principle of least privilege. With the exception
> of
> @@ -105,46 +111,46 @@ 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
> +root to give it access to host devices (e.g. ``/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.
> +for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
> Some Linux distros already ship with UNIX groups for these devices by
> default.
>
> -@itemize
> -@item 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.
> +- 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.
>
> -@item Resource limits and cgroup controllers provide throughput and
> utilization
> -limits on key resources such as CPU time, memory, and I/O bandwidth.
> +- Resource limits and cgroup controllers provide throughput and
> utilization
> + limits on key resources such as CPU time, memory, and I/O bandwidth.
>
> -@item 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.
> +- 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.
>
> -@item 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.
> -@end itemize
> +- Linux seccomp is available via the QEMU ``--sandbox`` option. It
> disables
> + system calls that are not needed by QEMU, thereby reducing the host
> kernel
> + attack surface.
>
> -@section Sensitive configurations
> +Sensitive configurations
> +------------------------
>
> There are aspects of QEMU that can have security implications which users
> &
> management applications must be aware of.
>
> -@subsection Monitor console (QMP and HMP)
> +Monitor console (QMP and HMP)
> +'''''''''''''''''''''''''''''
>
> The monitor console (whether used with QMP or HMP) provides an interface
> to dynamically control many aspects of QEMU's runtime operation. Many of
> the
> commands exposed will instruct QEMU to access content on the host file
> system
> and/or trigger spawning of external processes.
>
> -For example, the @code{migrate} command allows for the spawning of
> arbitrary
> +For example, the ``migrate`` command allows for the spawning of arbitrary
> processes for the purpose of tunnelling the migration data stream. The
> -@code{blockdev-add} command instructs QEMU to open arbitrary files,
> exposing
> +``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
> their content to the guest as a virtual disk.
>
> Unless QEMU is otherwise confined using technologies such as SELinux,
> AppArmor,
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 33b9597b1dc..c11b1a5d5ad 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -40,7 +40,6 @@
> * QEMU System emulator for non PC targets::
> * QEMU User space emulator::
> * System requirements::
> -* Security::
> * Implementation notes::
> * Deprecated features::
> * Recently removed features::
> @@ -2836,8 +2835,6 @@ 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.
>
> -@include docs/security.texi
> -
> @include qemu-tech.texi
>
> @include qemu-deprecated.texi
> --
> 2.20.1
>
>
>
