Re: [RFCv2 29/37] DOCUMENTATION: protvirt: Diag 308 IPL

[Christian Borntraeger <borntraeger@de.ibm.com>]

On 03.02.20 17:13, Cornelia Huck wrote:
> On Mon,  3 Feb 2020 08:19:49 -0500
> Christian Borntraeger <borntraeger@de.ibm.com> wrote:
> 
>> From: Janosch Frank <frankja@linux.ibm.com>
>>
>> Description of changes that are necessary to move a KVM VM into
>> Protected Virtualization mode.
> 
> Maybe move this up to the top of the series, so that new reviewers can
> get a quick idea about the architecture as a whole? It might also make
Will do. 
> sense to make the two documents link to each other...
I added both files to the kvm index file and changed the title
to contain s390. I also added a link to the base doc.

> 
>>
>> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
>> ---
>>  Documentation/virt/kvm/s390-pv-boot.rst | 64 +++++++++++++++++++++++++
>>  1 file changed, 64 insertions(+)
>>  create mode 100644 Documentation/virt/kvm/s390-pv-boot.rst
>>
>> diff --git a/Documentation/virt/kvm/s390-pv-boot.rst b/Documentation/virt/kvm/s390-pv-boot.rst
>> new file mode 100644
>> index 000000000000..431cd5d7f686
>> --- /dev/null
>> +++ b/Documentation/virt/kvm/s390-pv-boot.rst
>> @@ -0,0 +1,64 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +=========================
>> +Boot/IPL of Protected VMs
>> +=========================
> 
> ...especially as the reader will have no idea what a "Protected VM" is,
> unless they have read the other document before.

> 
> 
>> +
>> +Summary
>> +-------
>> +Protected VMs are encrypted while not running. On IPL a small
>> +plaintext bootloader is started which provides information about the
>> +encrypted components and necessary metadata to KVM to decrypt it.
> 
> s/it/the PVM/ ?

ack

This section looks now:

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

> 
>> +
>> +Based on this data, KVM will make the PV known to the Ultravisor and
> 
> I think the other document uses 'PVM'... probably better to keep that
> consistent.

The feature name might change to secure execution (SE). I will need to
go over this again. But I think we can continue to name the virtual
machines protected virtual machines as this is more a description than
a brand name.


> 
>> +instruct it to secure its memory, decrypt the components and verify
> 
> Too many it and its here... maybe use the abbreviations instead?

fixed

> 
>> +the data and address list hashes, to ensure integrity. Afterwards KVM
>> +can run the PV via SIE which the UV will intercept and execute on
>> +KVM's behalf.
>> +
>> +The switch into PV mode lets us load encrypted guest executables and
>> +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 continued with new subcodes:
> 
> s/continued/extended/ ?

yes.

> 
>> +
>> +Subcode 8: Set an IPL Information Block of type 5.
> 
> "type 5" == information block for PVMs? Better spell that out.

ack

> 
>> +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,
>> +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 command line/ ?

ack

> 
>> +initrd. The components are decrypted by the UV.
>> +
>> +All non-decrypted data of the non-PV guest instance are zero on first
>> +access of the PV.
> 
> "non-PV guest" == "the guest before it switches to protected
> virtualization mode" ?

ack
> 
>> +
>> +
>> +When running in a protected mode some subcodes will result in
> 
> s/in a/in/

ack
> 
>> +exceptions or return error codes.
>> +
>> +Subcodes 4 and 7 will result in specification exceptions.
> 
> "Subcodes 4 and 7, which would not clear the guest memory, ..." ?

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.
> 
> In general, this looks like a good overview about how the guest can
> move into protected virt mode.
> 
> Some information I'm missing in this doc: Where do the keys come from?
> I assume from the machine... is there one key per CEC? Can keys be
> transferred? Can an image be introspected to find out if it is possible
> to run it on a given system?
> 
> (Not sure if there is a better resting place for that kind of
> information.)

There will be tooling as part of the s390-tools. I will add 

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

The s390 tools part is not yet upstream but it will be soon.