Re: [PATCH 1/4] docs: Convert security.texi to rST format

[Aleksandar Markovic <aleksandar.m.mail@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 10367 bytes --]

On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@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.maydell@linaro.org>
> ---


FWIW:

Reviewed-by: Aleksandar Markovic <amarkovic@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
>
>
>

[-- Attachment #2: Type: text/html, Size: 12327 bytes --]