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