0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======================================
0004 s390 (IBM Z) Boot/IPL of Protected VMs
0005 ======================================
0006
0007 Summary
0008 -------
0009 The memory of Protected Virtual Machines (PVMs) is not accessible to
0010 I/O or the hypervisor. In those cases where the hypervisor needs to
0011 access the memory of a PVM, that memory must be made accessible.
0012 Memory made accessible to the hypervisor will be encrypted. See
0013 Documentation/virt/kvm/s390/s390-pv.rst for details."
0014
0015 On IPL (boot) a small plaintext bootloader is started, which provides
0016 information about the encrypted components and necessary metadata to
0017 KVM to decrypt the protected virtual machine.
0018
0019 Based on this data, KVM will make the protected virtual machine known
0020 to the Ultravisor (UV) and instruct it to secure the memory of the
0021 PVM, decrypt the components and verify the data and address list
0022 hashes, to ensure integrity. Afterwards KVM can run the PVM via the
0023 SIE instruction which the UV will intercept and execute on KVM's
0024 behalf.
0025
0026 As the guest image is just like an opaque kernel image that does the
0027 switch into PV mode itself, the user can load encrypted guest
0028 executables and data via every available method (network, dasd, scsi,
0029 direct kernel, ...) without the need to change the boot process.
0030
0031
0032 Diag308
0033 -------
0034 This diagnose instruction is the basic mechanism to handle IPL and
0035 related operations for virtual machines. The VM can set and retrieve
0036 IPL information blocks, that specify the IPL method/devices and
0037 request VM memory and subsystem resets, as well as IPLs.
0038
0039 For PVMs this concept has been extended with new subcodes:
0040
0041 Subcode 8: Set an IPL Information Block of type 5 (information block
0042 for PVMs)
0043 Subcode 9: Store the saved block in guest memory
0044 Subcode 10: Move into Protected Virtualization mode
0045
0046 The new PV load-device-specific-parameters field specifies all data
0047 that is necessary to move into PV mode.
0048
0049 * PV Header origin
0050 * PV Header length
0051 * List of Components composed of
0052 * AES-XTS Tweak prefix
0053 * Origin
0054 * Size
0055
0056 The PV header contains the keys and hashes, which the UV will use to
0057 decrypt and verify the PV, as well as control flags and a start PSW.
0058
0059 The components are for instance an encrypted kernel, kernel parameters
0060 and initrd. The components are decrypted by the UV.
0061
0062 After the initial import of the encrypted data, all defined pages will
0063 contain the guest content. All non-specified pages will start out as
0064 zero pages on first access.
0065
0066
0067 When running in protected virtualization mode, some subcodes will result in
0068 exceptions or return error codes.
0069
0070 Subcodes 4 and 7, which specify operations that do not clear the guest
0071 memory, will result in specification exceptions. This is because the
0072 UV will clear all memory when a secure VM is removed, and therefore
0073 non-clearing IPL subcodes are not allowed.
0074
0075 Subcodes 8, 9, 10 will result in specification exceptions.
0076 Re-IPL into a protected mode is only possible via a detour into non
0077 protected mode.
0078
0079 Keys
0080 ----
0081 Every CEC will have a unique public key to enable tooling to build
0082 encrypted images.
0083 See `s390-tools <https://github.com/ibm-s390-linux/s390-tools/>`_
0084 for the tooling.
