[Qemu-devel] [PATCH v3 0/2] security.rst: add Security Guide to developer docs

[Qemu-devel] [PATCH v3 0/2] security.rst: add Security Guide to developer docs

[Stefan Hajnoczi]

v3:
 * Split into security.texi for qemu-doc and secure-coding-practices.rst for
   the developer documentation [danpb]
 * Mentioned that QEMU can be started as non-root using UNIX groups on
   /dev/kvm, /dev/net/tun, etc [Alex Bennee]
 * Kept Acked-by and Reviewed-by since the v3 changes are minor
v2:
 * Added mention of passthrough USB and PCI devices [philmd]
 * Reworded resource limits [philmd]
 * Added qemu_log_mask(LOG_GUEST_ERROR) [philmd]

At KVM Forum 2018 I gave a presentation on security in QEMU:
https://www.youtube.com/watch?v=YAdRf_hwxU8 (video)
https://vmsplice.net/~stefan/stefanha-kvm-forum-2018.pdf (slides)

This patch series extends the QEMU documentation to cover security topics,
though this is just the beginning and we could flesh it out more in the future.

Stefan Hajnoczi (2):
  docs: add Secure Coding Practices to developer docs
  docs: add Security chapter to the documentation

 Makefile                               |   2 +-
 docs/devel/index.rst                   |   1 +
 docs/devel/secure-coding-practices.rst | 106 ++++++++++++++++++++
 docs/security.texi                     | 131 +++++++++++++++++++++++++
 qemu-doc.texi                          |   3 +
 5 files changed, 242 insertions(+), 1 deletion(-)
 create mode 100644 docs/devel/secure-coding-practices.rst
 create mode 100644 docs/security.texi

-- 
2.21.0

[Qemu-devel] [PATCH v3 1/2] docs: add Secure Coding Practices to developer docs

[Stefan Hajnoczi]

At KVM Forum 2018 I gave a presentation on security in QEMU:
https://www.youtube.com/watch?v=YAdRf_hwxU8 (video)
https://vmsplice.net/~stefan/stefanha-kvm-forum-2018.pdf (slides)

This patch adds a guide to secure coding practices.  This document
covers things that developers should know about security in QEMU.  It is
just a starting point that we can expand on later.  I hope it will be
useful as a resource for new contributors and will save code reviewers
from explaining the same concepts many times.

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>
---
 docs/devel/index.rst                   |   1 +
 docs/devel/secure-coding-practices.rst | 106 +++++++++++++++++++++++++
 2 files changed, 107 insertions(+)
 create mode 100644 docs/devel/secure-coding-practices.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index ebbab636ce..2a4ddf40ad 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -20,3 +20,4 @@ Contents:
    stable-process
    testing
    decodetree
+   secure-coding-practices
diff --git a/docs/devel/secure-coding-practices.rst b/docs/devel/secure-coding-practices.rst
new file mode 100644
index 0000000000..cbfc8af67e
--- /dev/null
+++ b/docs/devel/secure-coding-practices.rst
@@ -0,0 +1,106 @@
+=======================
+Secure Coding Practices
+=======================
+This document covers topics that both developers and security researchers must
+be aware of so that they can develop safe code and audit existing code
+properly.
+
+Reporting Security Bugs
+-----------------------
+For details on how to report security bugs or ask questions about potential
+security bugs, see the `Security Process wiki page
+<https://wiki.qemu.org/SecurityProcess>`_.
+
+General Secure C Coding Practices
+---------------------------------
+Most CVEs (security bugs) reported against QEMU are not specific to
+virtualization or emulation.  They are simply C programming bugs.  Therefore
+it's critical to be aware of common classes of security bugs.
+
+There is a wide selection of resources available covering secure C coding.  For
+example, the `CERT C Coding Standard
+<https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard>`_
+covers the most important classes of security bugs.
+
+Instead of describing them in detail here, only the names of the most important
+classes of security bugs are mentioned:
+
+* Buffer overflows
+* Use-after-free and double-free
+* Integer overflows
+* Format string vulnerabilities
+
+Some of these classes of bugs can be detected by analyzers.  Static analysis is
+performed regularly by Coverity and the most obvious of these bugs are even
+reported by compilers.  Dynamic analysis is possible with valgrind, tsan, and
+asan.
+
+Input Validation
+----------------
+Inputs from the guest or external sources (e.g. network, files) cannot be
+trusted and may be invalid.  Inputs must be checked before using them in a way
+that could crash the program, expose host memory to the guest, or otherwise be
+exploitable by an attacker.
+
+The most sensitive attack surface is device emulation.  All hardware register
+accesses and data read from guest memory must be validated.  A typical example
+is a device that contains multiple units that are selectable by the guest via
+an index register::
+
+  typedef struct {
+      ProcessingUnit unit[2];
+      ...
+  } MyDeviceState;
+
+  static void mydev_writel(void *opaque, uint32_t addr, uint32_t val)
+  {
+      MyDeviceState *mydev = opaque;
+      ProcessingUnit *unit;
+
+      switch (addr) {
+      case MYDEV_SELECT_UNIT:
+          unit = &mydev->unit[val];   <-- this input wasn't validated!
+          ...
+      }
+  }
+
+If ``val`` is not in range [0, 1] then an out-of-bounds memory access will take
+place when ``unit`` is dereferenced.  The code must check that ``val`` is 0 or
+1 and handle the case where it is invalid.
+
+Unexpected Device Accesses
+--------------------------
+The guest may access device registers in unusual orders or at unexpected
+moments.  Device emulation code must not assume that the guest follows the
+typical "theory of operation" presented in driver writer manuals.  The guest
+may make nonsense accesses to device registers such as starting operations
+before the device has been fully initialized.
+
+A related issue is that device emulation code must be prepared for unexpected
+device register accesses while asynchronous operations are in progress.  A
+well-behaved guest might wait for a completion interrupt before accessing
+certain device registers.  Device emulation code must handle the case where the
+guest overwrites registers or submits further requests before an ongoing
+request completes.  Unexpected accesses must not cause memory corruption or
+leaks in QEMU.
+
+Invalid device register accesses can be reported with
+``qemu_log_mask(LOG_GUEST_ERROR, ...)``.  The ``-d guest_errors`` command-line
+option enables these log messages.
+
+Live Migration
+--------------
+Device state can be saved to disk image files and shared with other users.
+Live migration code must validate inputs when loading device state so an
+attacker cannot gain control by crafting invalid device states.  Device state
+is therefore considered untrusted even though it is typically generated by QEMU
+itself.
+
+Guest Memory Access Races
+-------------------------
+Guests with multiple vCPUs may modify guest RAM while device emulation code is
+running.  Device emulation code must copy in descriptors and other guest RAM
+structures and only process the local copy.  This prevents
+time-of-check-to-time-of-use (TOCTOU) race conditions that could cause QEMU to
+crash when a vCPU thread modifies guest RAM while device emulation is
+processing it.
-- 
2.21.0

Re: [Qemu-devel] [PATCH v3 1/2] docs: add Secure Coding Practices to developer docs

[Daniel P. Berrangé]

On Thu, May 09, 2019 at 01:18:19PM +0100, Stefan Hajnoczi wrote:
> At KVM Forum 2018 I gave a presentation on security in QEMU:
> https://www.youtube.com/watch?v=YAdRf_hwxU8 (video)
> https://vmsplice.net/~stefan/stefanha-kvm-forum-2018.pdf (slides)
> 
> This patch adds a guide to secure coding practices.  This document
> covers things that developers should know about security in QEMU.  It is
> just a starting point that we can expand on later.  I hope it will be
> useful as a resource for new contributors and will save code reviewers
> from explaining the same concepts many times.
> 
> 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>
> ---
>  docs/devel/index.rst                   |   1 +
>  docs/devel/secure-coding-practices.rst | 106 +++++++++++++++++++++++++
>  2 files changed, 107 insertions(+)
>  create mode 100644 docs/devel/secure-coding-practices.rst

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH v3 1/2] docs: add Secure Coding Practices to developer docs

[Li Qiang]

Stefan Hajnoczi <stefanha@redhat.com> 于2019年5月9日周四 下午8:20写道：

> At KVM Forum 2018 I gave a presentation on security in QEMU:
> https://www.youtube.com/watch?v=YAdRf_hwxU8 (video)
> https://vmsplice.net/~stefan/stefanha-kvm-forum-2018.pdf (slides)
>
> This patch adds a guide to secure coding practices.  This document
> covers things that developers should know about security in QEMU.  It is
> just a starting point that we can expand on later.  I hope it will be
> useful as a resource for new contributors and will save code reviewers
> from explaining the same concepts many times.
>
> 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: Li Qiang <liq3ea@gmail.com>




> ---
>  docs/devel/index.rst                   |   1 +
>  docs/devel/secure-coding-practices.rst | 106 +++++++++++++++++++++++++
>  2 files changed, 107 insertions(+)
>  create mode 100644 docs/devel/secure-coding-practices.rst
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index ebbab636ce..2a4ddf40ad 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -20,3 +20,4 @@ Contents:
>     stable-process
>     testing
>     decodetree
> +   secure-coding-practices
> diff --git a/docs/devel/secure-coding-practices.rst
> b/docs/devel/secure-coding-practices.rst
> new file mode 100644
> index 0000000000..cbfc8af67e
> --- /dev/null
> +++ b/docs/devel/secure-coding-practices.rst
> @@ -0,0 +1,106 @@
> +=======================
> +Secure Coding Practices
> +=======================
> +This document covers topics that both developers and security researchers
> must
> +be aware of so that they can develop safe code and audit existing code
> +properly.
> +
> +Reporting Security Bugs
> +-----------------------
> +For details on how to report security bugs or ask questions about
> potential
> +security bugs, see the `Security Process wiki page
> +<https://wiki.qemu.org/SecurityProcess>`_.
> +
> +General Secure C Coding Practices
> +---------------------------------
> +Most CVEs (security bugs) reported against QEMU are not specific to
> +virtualization or emulation.  They are simply C programming bugs.
> Therefore
> +it's critical to be aware of common classes of security bugs.
> +
> +There is a wide selection of resources available covering secure C
> coding.  For
> +example, the `CERT C Coding Standard
> +<https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard
> >`_
> +covers the most important classes of security bugs.
> +
> +Instead of describing them in detail here, only the names of the most
> important
> +classes of security bugs are mentioned:
> +
> +* Buffer overflows
> +* Use-after-free and double-free
> +* Integer overflows
> +* Format string vulnerabilities
> +
> +Some of these classes of bugs can be detected by analyzers.  Static
> analysis is
> +performed regularly by Coverity and the most obvious of these bugs are
> even
> +reported by compilers.  Dynamic analysis is possible with valgrind, tsan,
> and
> +asan.
> +
> +Input Validation
> +----------------
> +Inputs from the guest or external sources (e.g. network, files) cannot be
> +trusted and may be invalid.  Inputs must be checked before using them in
> a way
> +that could crash the program, expose host memory to the guest, or
> otherwise be
> +exploitable by an attacker.
> +
> +The most sensitive attack surface is device emulation.  All hardware
> register
> +accesses and data read from guest memory must be validated.  A typical
> example
> +is a device that contains multiple units that are selectable by the guest
> via
> +an index register::
> +
> +  typedef struct {
> +      ProcessingUnit unit[2];
> +      ...
> +  } MyDeviceState;
> +
> +  static void mydev_writel(void *opaque, uint32_t addr, uint32_t val)
> +  {
> +      MyDeviceState *mydev = opaque;
> +      ProcessingUnit *unit;
> +
> +      switch (addr) {
> +      case MYDEV_SELECT_UNIT:
> +          unit = &mydev->unit[val];   <-- this input wasn't validated!
> +          ...
> +      }
> +  }
> +
> +If ``val`` is not in range [0, 1] then an out-of-bounds memory access
> will take
> +place when ``unit`` is dereferenced.  The code must check that ``val`` is
> 0 or
> +1 and handle the case where it is invalid.
> +
> +Unexpected Device Accesses
> +--------------------------
> +The guest may access device registers in unusual orders or at unexpected
> +moments.  Device emulation code must not assume that the guest follows the
> +typical "theory of operation" presented in driver writer manuals.  The
> guest
> +may make nonsense accesses to device registers such as starting operations
> +before the device has been fully initialized.
> +
> +A related issue is that device emulation code must be prepared for
> unexpected
> +device register accesses while asynchronous operations are in progress.  A
> +well-behaved guest might wait for a completion interrupt before accessing
> +certain device registers.  Device emulation code must handle the case
> where the
> +guest overwrites registers or submits further requests before an ongoing
> +request completes.  Unexpected accesses must not cause memory corruption
> or
> +leaks in QEMU.
> +
> +Invalid device register accesses can be reported with
> +``qemu_log_mask(LOG_GUEST_ERROR, ...)``.  The ``-d guest_errors``
> command-line
> +option enables these log messages.
> +
> +Live Migration
> +--------------
> +Device state can be saved to disk image files and shared with other users.
> +Live migration code must validate inputs when loading device state so an
> +attacker cannot gain control by crafting invalid device states.  Device
> state
> +is therefore considered untrusted even though it is typically generated
> by QEMU
> +itself.
> +
> +Guest Memory Access Races
> +-------------------------
> +Guests with multiple vCPUs may modify guest RAM while device emulation
> code is
> +running.  Device emulation code must copy in descriptors and other guest
> RAM
> +structures and only process the local copy.  This prevents
> +time-of-check-to-time-of-use (TOCTOU) race conditions that could cause
> QEMU to
> +crash when a vCPU thread modifies guest RAM while device emulation is
> +processing it.
> --
> 2.21.0
>
>
>

[Qemu-devel] [PATCH v3 2/2] docs: add Security chapter to the documentation

[Stefan Hajnoczi]

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>
---
 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 d372493042..e2bc9c8c9d 100644
--- a/Makefile
+++ b/Makefile
@@ -973,7 +973,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 @@
+@node Security
+@chapter Security
+
+@section Overview
+
+This chapter explains the security requirements that QEMU is designed to meet
+and principles for securely deploying QEMU.
+
+@section 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
+
+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
+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
+
+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
+
+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.
+
+@section Architecture
+
+This section describes the design principles that ensure the security
+requirements are met.
+
+@subsection 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
+limits.
+
+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.
+
+@subsection 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
+@code{a.img} 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.
+
+@subsection 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.
+
+@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.
+
+@item 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.
+
+@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
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.
 
+@include docs/security.texi
+
 @include qemu-tech.texi
 
 @include qemu-deprecated.texi
-- 
2.21.0

Re: [Qemu-devel] [PATCH v3 2/2] docs: add Security chapter to the documentation

[Daniel P. Berrangé]

On Thu, May 09, 2019 at 01:18:20PM +0100, Stefan Hajnoczi wrote:
> 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>
> ---
>  Makefile           |   2 +-
>  docs/security.texi | 131 +++++++++++++++++++++++++++++++++++++++++++++
>  qemu-doc.texi      |   3 ++
>  3 files changed, 135 insertions(+), 1 deletion(-)
>  create mode 100644 docs/security.texi

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH v3 2/2] docs: add Security chapter to the documentation

[Li Qiang]

Stefan Hajnoczi <stefanha@redhat.com> 于2019年5月9日周四 下午8:20写道：

> 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: Li Qiang <liq3ea@gmail.com>




>  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 d372493042..e2bc9c8c9d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -973,7 +973,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 @@
> +@node Security
> +@chapter Security
> +
> +@section Overview
> +
> +This chapter explains the security requirements that QEMU is designed to
> meet
> +and principles for securely deploying QEMU.
> +
> +@section 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
> +
> +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
> +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
> +
> +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
> +
> +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.
> +
> +@section Architecture
> +
> +This section describes the design principles that ensure the security
> +requirements are met.
> +
> +@subsection 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
> +limits.
> +
> +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.
> +
> +@subsection 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
> +@code{a.img} 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.
> +
> +@subsection 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.
> +
> +@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.
> +
> +@item 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.
> +
> +@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
> 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.
>
> +@include docs/security.texi
> +
>  @include qemu-tech.texi
>
>  @include qemu-deprecated.texi
> --
> 2.21.0
>
>
>

Re: [Qemu-devel] [PATCH v3 0/2] security.rst: add Security Guide to developer docs

[Stefan Hajnoczi]

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

On Thu, May 09, 2019 at 01:18:18PM +0100, Stefan Hajnoczi wrote:
> v3:
>  * Split into security.texi for qemu-doc and secure-coding-practices.rst for
>    the developer documentation [danpb]
>  * Mentioned that QEMU can be started as non-root using UNIX groups on
>    /dev/kvm, /dev/net/tun, etc [Alex Bennee]
>  * Kept Acked-by and Reviewed-by since the v3 changes are minor
> v2:
>  * Added mention of passthrough USB and PCI devices [philmd]
>  * Reworded resource limits [philmd]
>  * Added qemu_log_mask(LOG_GUEST_ERROR) [philmd]
> 
> At KVM Forum 2018 I gave a presentation on security in QEMU:
> https://www.youtube.com/watch?v=YAdRf_hwxU8 (video)
> https://vmsplice.net/~stefan/stefanha-kvm-forum-2018.pdf (slides)
> 
> This patch series extends the QEMU documentation to cover security topics,
> though this is just the beginning and we could flesh it out more in the future.
> 
> Stefan Hajnoczi (2):
>   docs: add Secure Coding Practices to developer docs
>   docs: add Security chapter to the documentation
> 
>  Makefile                               |   2 +-
>  docs/devel/index.rst                   |   1 +
>  docs/devel/secure-coding-practices.rst | 106 ++++++++++++++++++++
>  docs/security.texi                     | 131 +++++++++++++++++++++++++
>  qemu-doc.texi                          |   3 +
>  5 files changed, 242 insertions(+), 1 deletion(-)
>  create mode 100644 docs/devel/secure-coding-practices.rst
>  create mode 100644 docs/security.texi
> 
> -- 
> 2.21.0
> 

Thanks, applied to my block tree:
https://github.com/stefanha/qemu/commits/block

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]