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