|
 |
a41c76 |
From 026160bc76bab26772c2a80bd50ae55119e3b60b Mon Sep 17 00:00:00 2001
|
|
|
a41c76 |
Message-Id: <026160bc76bab26772c2a80bd50ae55119e3b60b@dist-git>
|
|
|
a41c76 |
From: Viktor Mihajlovski <mihajlov@linux.ibm.com>
|
|
|
a41c76 |
Date: Wed, 24 Jun 2020 13:16:23 +0200
|
|
|
a41c76 |
Subject: [PATCH] docs: Describe protected virtualization guest setup
|
|
|
a41c76 |
MIME-Version: 1.0
|
|
|
a41c76 |
Content-Type: text/plain; charset=UTF-8
|
|
|
a41c76 |
Content-Transfer-Encoding: 8bit
|
|
|
a41c76 |
|
|
|
a41c76 |
Protected virtualization/IBM Secure Execution for Linux protects
|
|
|
a41c76 |
guest memory and state from the host.
|
|
|
a41c76 |
|
|
|
a41c76 |
Add some basic information about technology and a brief guide
|
|
|
a41c76 |
on setting up secure guests with libvirt.
|
|
|
a41c76 |
|
|
|
a41c76 |
Signed-off-by: Viktor Mihajlovski <mihajlov@linux.ibm.com>
|
|
|
a41c76 |
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
|
|
|
a41c76 |
Reviewed-by: Paulo de Rezende Pinatti <ppinatti@linux.ibm.com>
|
|
|
a41c76 |
Reviewed-by: Erik Skultety <eskultet@redhat.com>
|
|
|
a41c76 |
(cherry picked from commit f0d0cd6179709461b026f24569a688065e90d766)
|
|
|
a41c76 |
|
|
|
a41c76 |
https://bugzilla.redhat.com/show_bug.cgi?id=1848997
|
|
|
a41c76 |
https://bugzilla.redhat.com/show_bug.cgi?id=1850351
|
|
|
a41c76 |
|
|
|
a41c76 |
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
|
|
|
a41c76 |
Message-Id: <cf598d01d242bb56e64e14bfc32cece69341d949.1592996194.git.jdenemar@redhat.com>
|
|
|
a41c76 |
Reviewed-by: Ján Tomko <jtomko@redhat.com>
|
|
|
a41c76 |
---
|
|
|
a41c76 |
docs/kbase.html.in | 3 +
|
|
|
a41c76 |
docs/kbase/s390_protected_virt.rst | 189 +++++++++++++++++++++++++++++
|
|
|
a41c76 |
2 files changed, 192 insertions(+)
|
|
|
a41c76 |
create mode 100644 docs/kbase/s390_protected_virt.rst
|
|
|
a41c76 |
|
|
|
a41c76 |
diff --git a/docs/kbase.html.in b/docs/kbase.html.in
|
|
|
a41c76 |
index f2975960f6..05773db16d 100644
|
|
|
a41c76 |
--- a/docs/kbase.html.in
|
|
|
a41c76 |
+++ b/docs/kbase.html.in
|
|
|
a41c76 |
@@ -14,6 +14,9 @@
|
|
|
a41c76 |
Secure usage
|
|
|
a41c76 |
Secure usage of the libvirt APIs
|
|
|
a41c76 |
|
|
|
a41c76 |
+ Protected virtualization on s390
|
|
|
a41c76 |
+ Running secure s390 guests with IBM Secure Execution
|
|
|
a41c76 |
+
|
|
|
a41c76 |
Launch security
|
|
|
a41c76 |
Securely launching VMs with AMD SEV
|
|
|
a41c76 |
|
|
|
a41c76 |
diff --git a/docs/kbase/s390_protected_virt.rst b/docs/kbase/s390_protected_virt.rst
|
|
|
a41c76 |
new file mode 100644
|
|
|
a41c76 |
index 0000000000..f38d16d743
|
|
|
a41c76 |
--- /dev/null
|
|
|
a41c76 |
+++ b/docs/kbase/s390_protected_virt.rst
|
|
|
a41c76 |
@@ -0,0 +1,189 @@
|
|
|
a41c76 |
+================================
|
|
|
a41c76 |
+Protected Virtualization on s390
|
|
|
a41c76 |
+================================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+.. contents::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Overview
|
|
|
a41c76 |
+========
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Protected virtualization, also known as IBM Secure Execution is a
|
|
|
a41c76 |
+hardware-based privacy protection technology for s390x (IBM Z).
|
|
|
a41c76 |
+It allows to execute virtual machines such that the host system
|
|
|
a41c76 |
+has no access to a VM's state and memory contents.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Unlike other similar technologies, the memory of a running guest
|
|
|
a41c76 |
+is not encrypted but protected by hardware access controls, which
|
|
|
a41c76 |
+may only be manipulated by trusted system firmware, called
|
|
|
a41c76 |
+ultravisor.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+For the cases where the host needs access to guest memory (e.g. for
|
|
|
a41c76 |
+paging), it can request pages to be exported to it. The exported page
|
|
|
a41c76 |
+will be encrypted with a unique key for the running guest by the
|
|
|
a41c76 |
+ultravisor. The ultravisor also computes an integrity value for
|
|
|
a41c76 |
+the page, and stores it in a special table, together with the page
|
|
|
a41c76 |
+index and a counter. This way it can verify the integrity of
|
|
|
a41c76 |
+the page content upon re-import into the guest.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+In other cases it may be necessary for a guest to grant the host access
|
|
|
a41c76 |
+to dedicated memory regions (e.g. for I/O). The guest can request
|
|
|
a41c76 |
+that the ultravisor removes the memory protection from individual
|
|
|
a41c76 |
+pages, so that they can be shared with the host. Likewise, the
|
|
|
a41c76 |
+guest can undo the sharing.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+A secure guest will initially start in a regular non-protected VM.
|
|
|
a41c76 |
+The start-up is controlled by a small bootstrap program loaded
|
|
|
a41c76 |
+into memory together with encrypted operating system components and
|
|
|
a41c76 |
+a control structure (the PV header).
|
|
|
a41c76 |
+The operating system components (e.g. Linux kernel, initial RAM
|
|
|
a41c76 |
+file system, kernel parameters) are encrypted and integrity
|
|
|
a41c76 |
+protected. The component encryption keys and integrity values are
|
|
|
a41c76 |
+stored in the PV header.
|
|
|
a41c76 |
+The PV header is wrapped with a public key belonging to a specific
|
|
|
a41c76 |
+system (in fact it can be wrapped with multiple such keys). The
|
|
|
a41c76 |
+matching private key is only accessible by trusted hardware and
|
|
|
a41c76 |
+firmware in that specific system.
|
|
|
a41c76 |
+Consequently, such a secure guest boot image can only be run on the
|
|
|
a41c76 |
+systems it has been prepared for. Its contents can't be decrypted
|
|
|
a41c76 |
+without access to the private key and it can't be modified as
|
|
|
a41c76 |
+it is integrity protected.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Host Requirements
|
|
|
a41c76 |
+=================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+IBM Secure Execution for Linux has some hardware and firmware
|
|
|
a41c76 |
+requirements. The system hardware must be an IBM z15 (or newer),
|
|
|
a41c76 |
+or an IBM LinuxONE III (or newer).
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+It is also necessary that the IBM Secure Execution feature is
|
|
|
a41c76 |
+enabled for that system. With libvirt >= 6.5.0 you can run
|
|
|
a41c76 |
+``libvirt-host--validate`` or otherwise check for facility '158', e.g.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ $ grep facilities /proc/cpuinfo | grep 158
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+The kernel must include the protected virtualization support
|
|
|
a41c76 |
+which can be verified by checking for the presence of directory
|
|
|
a41c76 |
+``/sys/firmware/uv``. It will only be present when both the
|
|
|
a41c76 |
+hardware and the kernel support are available.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Finally, the host operating system must donate some memory to
|
|
|
a41c76 |
+the ultravisor needed to store memory security information.
|
|
|
a41c76 |
+This is achieved by specifying the following kernel command
|
|
|
a41c76 |
+line parameter to the host boot configuration
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ prot_virt=1
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Guest Requirements
|
|
|
a41c76 |
+==================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Guest Boot
|
|
|
a41c76 |
+----------
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+To start a guest in protected virtualization secure mode, the
|
|
|
a41c76 |
+boot image must have been prepared first with the program
|
|
|
a41c76 |
+``genprotimg`` using the correct public key for this host.
|
|
|
a41c76 |
+``genprotimg`` is part of the package ``s390-tools``, or
|
|
|
a41c76 |
+``s390-utils``, depending on the Linux distribution being used.
|
|
|
a41c76 |
+It can also be found at
|
|
|
a41c76 |
+`<https://github.com/ibm-s390-tools/s390-tools/tree/master/genprotimg>`_
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+The guests have to be configured to use the host CPU model, which
|
|
|
a41c76 |
+must contain the ``unpack`` facility indicating ultravisor guest support.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+With the following command it's possible to check whether the host
|
|
|
a41c76 |
+CPU model satisfies the requirement
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ $ virsh domcapabilities | grep unpack
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+which should return
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <feature policy='require' name='unpack'/>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Note that on hosts with libvirt < 6.5.0 if the check fails despite
|
|
|
a41c76 |
+the host system actually supporting protected virtualization guests,
|
|
|
a41c76 |
+this can be caused by a stale libvirt capabilities cache.
|
|
|
a41c76 |
+To recover, run the following commands
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ $ systemctl stop libvirtd
|
|
|
a41c76 |
+ $ rm /var/cache/libvirt/qemu/capabilities/*.xml
|
|
|
a41c76 |
+ $ systemctl start libvirtd
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Guest I/O
|
|
|
a41c76 |
+---------
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Protected virtualization guests support I/O using virtio devices.
|
|
|
a41c76 |
+As the virtio data structures of secure guests are not accessible
|
|
|
a41c76 |
+by the host, it is necessary to use shared memory ('bounce buffers').
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+To enable virtio devices to use shared buffers, it is necessary
|
|
|
a41c76 |
+to configure them with platform_iommu enabled. This can done by adding
|
|
|
a41c76 |
+``iommu='on'`` to the driver element of a virtio device definition in the
|
|
|
a41c76 |
+guest's XML, e.g.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <interface type='network'>
|
|
|
a41c76 |
+ <source network='default'/>
|
|
|
a41c76 |
+ <model type='virtio'/>
|
|
|
a41c76 |
+ <driver name='vhost' iommu='on'/>
|
|
|
a41c76 |
+ </interface>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+It is mandatory to define all virtio bus devices in this way to
|
|
|
a41c76 |
+prevent the host from attempting to access protected memory.
|
|
|
a41c76 |
+Ballooning will not work and is fenced by QEMU. It should be
|
|
|
a41c76 |
+disabled by specifying
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <memballoon model='none'/>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Finally, the guest Linux must be instructed to allocate I/O
|
|
|
a41c76 |
+buffers using memory shared between host and guest using SWIOTLB.
|
|
|
a41c76 |
+This is done by adding ``swiotlb=nnn`` to the guest's kernel command
|
|
|
a41c76 |
+line string, where ``nnn`` stands for the number of statically
|
|
|
a41c76 |
+allocated 2K entries. A commonly used value for swiotlb is 262144.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Example guest definition
|
|
|
a41c76 |
+========================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Minimal domain XML for a protected virtualization guest, essentially
|
|
|
a41c76 |
+it's mostly about the ``iommu`` property
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <domain type='kvm'>
|
|
|
a41c76 |
+ <name>protected</name>
|
|
|
a41c76 |
+ <memory unit='KiB'>2048000</memory>
|
|
|
a41c76 |
+ <currentMemory unit='KiB'>2048000</currentMemory>
|
|
|
a41c76 |
+ <vcpu>1</vcpu>
|
|
|
a41c76 |
+ <os>
|
|
|
a41c76 |
+ <type arch='s390x'>hvm</type>
|
|
|
a41c76 |
+ </os>
|
|
|
a41c76 |
+ <cpu mode='host-model'/>
|
|
|
a41c76 |
+ <devices>
|
|
|
a41c76 |
+ <disk type='file' device='disk'>
|
|
|
a41c76 |
+ <driver name='qemu' type='qcow2' cache='none' io='native' iommu='on'>
|
|
|
a41c76 |
+ <source file='/var/lib/libvirt/images/protected.qcow2'/>
|
|
|
a41c76 |
+ <target dev='vda' bus='virtio'/>
|
|
|
a41c76 |
+ </disk>
|
|
|
a41c76 |
+ <interface type='network'>
|
|
|
a41c76 |
+ <driver iommu='on'/>
|
|
|
a41c76 |
+ <source network='default'/>
|
|
|
a41c76 |
+ <model type='virtio'/>
|
|
|
a41c76 |
+ </interface>
|
|
|
a41c76 |
+ <console type='pty'/>
|
|
|
a41c76 |
+ <memballoon model='none'/>
|
|
|
a41c76 |
+ </devices>
|
|
|
a41c76 |
+ </domain>
|
|
|
a41c76 |
--
|
|
|
a41c76 |
2.27.0
|
|
|
a41c76 |
|