| 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/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. |