On 11.02.20 13:23, Thomas Huth wrote: > On 07/02/2020 12.39, Christian Borntraeger wrote: >> From: Janosch Frank <frankja@xxxxxxxxxxxxx> >> >> Add documentation about protected KVM guests and description of changes >> that are necessary to move a KVM VM into Protected Virtualization mode. >> >> Signed-off-by: Janosch Frank <frankja@xxxxxxxxxxxxx> >> [borntraeger@xxxxxxxxxx: fixing and conversion to rst] >> Signed-off-by: Christian Borntraeger <borntraeger@xxxxxxxxxx> >> --- > [...] >> diff --git a/Documentation/virt/kvm/s390-pv-boot.rst b/Documentation/virt/kvm/s390-pv-boot.rst >> new file mode 100644 >> index 000000000000..47814e53369a >> --- /dev/null >> +++ b/Documentation/virt/kvm/s390-pv-boot.rst >> @@ -0,0 +1,79 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> + >> +====================================== >> +s390 (IBM Z) Boot/IPL of Protected VMs >> +====================================== >> + >> +Summary >> +------- >> +Protected Virtual Machines (PVM) are not accessible by I/O or the >> +hypervisor. When the hypervisor wants to access the memory of PVMs >> +the memory needs to be made accessible. When doing so, the memory will >> +be encrypted. See :doc:`s390-pv` for details. >> + >> +On IPL a small plaintext bootloader is started which provides >> +information about the encrypted components and necessary metadata to >> +KVM to decrypt the protected virtual machine. >> + >> +Based on this data, KVM will make the protected virtual machine known >> +to the Ultravisor(UV) and instruct it to secure the memory of the PVM, >> +decrypt the components and verify the data and address list hashes, to >> +ensure integrity. Afterwards KVM can run the PVM via the SIE >> +instruction which the UV will intercept and execute on KVM's behalf. >> + >> +The switch into PV mode lets us load encrypted guest executables and > > Maybe rather: "After the switch into PV mode, the guest can load ..." ? No its not after the switch. By doing the switch the guest image can be loaded fro anywhere because it is just like a kernel. So I will do: As the guest image is just like an opaque kernel image that does the switch into PV mode itself, the user can load encrypted guest executables and data via every available method (network, dasd, scsi, direct kernel, ...) without the need to change the boot process. > >> +data via every available method (network, dasd, scsi, direct kernel, >> +...) without the need to change the boot process. >> + >> + >> +Diag308 >> +------- >> +This diagnose instruction is the basis for VM IPL. The VM can set and >> +retrieve IPL information blocks, that specify the IPL method/devices >> +and request VM memory and subsystem resets, as well as IPLs. >> + >> +For PVs this concept has been extended with new subcodes: >> + >> +Subcode 8: Set an IPL Information Block of type 5 (information block >> +for PVMs) >> +Subcode 9: Store the saved block in guest memory >> +Subcode 10: Move into Protected Virtualization mode >> + >> +The new PV load-device-specific-parameters field specifies all data, > > remove the comma? ack. > >> +that is necessary to move into PV mode. >> + >> +* PV Header origin >> +* PV Header length >> +* List of Components composed of >> + * AES-XTS Tweak prefix >> + * Origin >> + * Size >> + >> +The PV header contains the keys and hashes, which the UV will use to >> +decrypt and verify the PV, as well as control flags and a start PSW. >> + >> +The components are for instance an encrypted kernel, kernel cmd and > > s/kernel cmd/kernel parameters/ ? ack > >> +initrd. The components are decrypted by the UV. >> + >> +All non-decrypted data of the guest before it switches to protected >> +virtualization mode are zero on first access of the PV. > > Before it switches to protected virtualization mode, all non-decrypted > data of the guest are ... ? No, this is about the data after the initial import. What about After the initial import of the encrypted data all defined pages will contain the guest content. All non-specified pages will start out as zero pages on first access. > >> + >> +When running in protected mode some subcodes will result in exceptions >> +or return error codes. >> + >> +Subcodes 4 and 7 will result in specification exceptions as they would >> +not clear out the guest memory. >> +When removing a secure VM, the UV will clear all memory, so we can't >> +have non-clearing IPL subcodes. >> + >> +Subcodes 8, 9, 10 will result in specification exceptions. >> +Re-IPL into a protected mode is only possible via a detour into non >> +protected mode. >> + >> +Keys >> +---- >> +Every CEC will have a unique public key to enable tooling to build >> +encrypted images. >> +See `s390-tools <https://github.com/ibm-s390-tools/s390-tools/>`_ >> +for the tooling. >> diff --git a/Documentation/virt/kvm/s390-pv.rst b/Documentation/virt/kvm/s390-pv.rst >> new file mode 100644 >> index 000000000000..dbe9110dfd1e >> --- /dev/null >> +++ b/Documentation/virt/kvm/s390-pv.rst >> @@ -0,0 +1,116 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> + >> +========================================= >> +s390 (IBM Z) Ultravisor and Protected VMs >> +========================================= >> + >> +Summary >> +------- >> +Protected virtual machines (PVM) are KVM VMs, where KVM can't access >> +the VM's state like guest memory and guest registers anymore. Instead, >> +the PVMs are mostly managed by a new entity called Ultravisor >> +(UV). The UV provides an API that can be used by PVMs and KVM to >> +request management actions. >> + >> +Each guest starts in the non-protected mode and then may make a >> +request to transition into protected mode. On transition, KVM >> +registers the guest and its VCPUs with the Ultravisor and prepares >> +everything for running it. >> + >> +The Ultravisor will secure and decrypt the guest's boot memory >> +(i.e. kernel/initrd). It will safeguard state changes like VCPU >> +starts/stops and injected interrupts while the guest is running. >> + >> +As access to the guest's state, such as the SIE state description, is >> +normally needed to be able to run a VM, some changes have been made in >> +SIE behavior. A new format 4 state description has been introduced, > > s/in SIE behavior/in the behavior of the SIE instruction/ ? ack >
