Documentation/virt/kvm/s390-pv-boot.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 s390 (IBM Z) Boot/IPL of Protected VMs
   5 ======================================
   6
   7 Summary
   8 -------
   9 The memory of Protected Virtual Machines (PVMs) is not accessible to
  10 I/O or the hypervisor. In those cases where the hypervisor needs to
  11 access the memory of a PVM, that memory must be made accessible.
  12 Memory made accessible to the hypervisor will be encrypted. See
  13 Documentation/virt/kvm/s390-pv.rst for details."
  14
  15 On IPL (boot) a small plaintext bootloader is started, which provides
  16 information about the encrypted components and necessary metadata to
  17 KVM to decrypt the protected virtual machine.
  18
  19 Based on this data, KVM will make the protected virtual machine known
  20 to the Ultravisor (UV) and instruct it to secure the memory of the
  21 PVM, decrypt the components and verify the data and address list
  22 hashes, to ensure integrity. Afterwards KVM can run the PVM via the
  23 SIE instruction which the UV will intercept and execute on KVM's
  24 behalf.
  25
  26 As the guest image is just like an opaque kernel image that does the
  27 switch into PV mode itself, the user can load encrypted guest
  28 executables and data via every available method (network, dasd, scsi,
  29 direct kernel, ...) without the need to change the boot process.
  30
  31
  32 Diag308
  33 -------
  34 This diagnose instruction is the basic mechanism to handle IPL and
  35 related operations for virtual machines. The VM can set and retrieve
  36 IPL information blocks, that specify the IPL method/devices and
  37 request VM memory and subsystem resets, as well as IPLs.
  38
  39 For PVMs this concept has been extended with new subcodes:
  40
  41 Subcode 8: Set an IPL Information Block of type 5 (information block
  42 for PVMs)
  43 Subcode 9: Store the saved block in guest memory
  44 Subcode 10: Move into Protected Virtualization mode
  45
  46 The new PV load-device-specific-parameters field specifies all data
  47 that is necessary to move into PV mode.
  48
  49 * PV Header origin
  50 * PV Header length
  51 * List of Components composed of
  52    * AES-XTS Tweak prefix
  53    * Origin
  54    * Size
  55
  56 The PV header contains the keys and hashes, which the UV will use to
  57 decrypt and verify the PV, as well as control flags and a start PSW.
  58
  59 The components are for instance an encrypted kernel, kernel parameters
  60 and initrd. The components are decrypted by the UV.
  61
  62 After the initial import of the encrypted data, all defined pages will
  63 contain the guest content. All non-specified pages will start out as
  64 zero pages on first access.
  65
  66
  67 When running in protected virtualization mode, some subcodes will result in
  68 exceptions or return error codes.
  69
  70 Subcodes 4 and 7, which specify operations that do not clear the guest
  71 memory, will result in specification exceptions. This is because the
  72 UV will clear all memory when a secure VM is removed, and therefore
  73 non-clearing IPL subcodes are not allowed.
  74
  75 Subcodes 8, 9, 10 will result in specification exceptions.
  76 Re-IPL into a protected mode is only possible via a detour into non
  77 protected mode.
  78
  79 Keys
  80 ----
  81 Every CEC will have a unique public key to enable tooling to build
  82 encrypted images.
  83 See  `s390-tools <https://github.com/ibm-s390-linux/s390-tools/>`_
  84 for the tooling.