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

Commit Message

Christian Borntraeger Feb. 3, 2020, 1:19 p.m. UTC

From: Janosch Frank <[e-mail]>

Description of changes that are necessary to move a KVM VM into
Protected Virtualization mode.

Signed-off-by: Janosch Frank <[e-mail]>
---
 Documentation/virt/kvm/s390-pv-boot.rst | 64 +++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 Documentation/virt/kvm/s390-pv-boot.rst

Comments

Cornelia Huck Feb. 3, 2020, 4:13 p.m. UTC | #1

On Mon,  3 Feb 2020 08:19:49 -0500
Christian Borntraeger <[e-mail]> wrote:

> From: Janosch Frank <[e-mail]>
> 
> 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
sense to make the two documents link to each other...

> 
> Signed-off-by: Janosch Frank <[e-mail]>
> ---
>  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/ ?

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

> +instruct it to secure its memory, decrypt the components and verify

Too many it and its here... maybe use the abbreviations instead?

> +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/ ?

> +
> +Subcode 8: Set an IPL Information Block of type 5.

"type 5" == information block for PVMs? Better spell that out.

> +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/ ?

> +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" ?

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

s/in a/in/

> +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, ..." ?

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

Christian Borntraeger Feb. 4, 2020, 8:13 a.m. UTC | #2

On 03.02.20 17:13, Cornelia Huck wrote:
> On Mon,  3 Feb 2020 08:19:49 -0500
> Christian Borntraeger <[e-mail]> wrote:
> 
>> From: Janosch Frank <[e-mail]>
>>
>> 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 <[e-mail]>
>> ---
>>  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.

Cornelia Huck Feb. 4, 2020, 9:35 a.m. UTC | #3

On Tue, 4 Feb 2020 09:13:06 +0100
Christian Borntraeger <[e-mail]> wrote:

> On 03.02.20 17:13, Cornelia Huck wrote:
> > On Mon,  3 Feb 2020 08:19:49 -0500
> > Christian Borntraeger <[e-mail]> wrote:
> >   
> >> From: Janosch Frank <[e-mail]>
> >>
> >> 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.

Sounds good.

> 
> >   
> >>
> >> Signed-off-by: Janosch Frank <[e-mail]>
> >> ---
> >>  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....

ok

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

I would stick with "protected virtual machines" as well; especially as
the kernel parameter is called "prot_virt", and people might wonder
why you're talking about SELinux :)

(...)

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

ok

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

Sounds good.

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

I'll look forward to the s390 tools part for details on key handling,
then :)

Patch

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
+=========================
+
+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.
+
+Based on this data, KVM will make the PV known to the Ultravisor and
+instruct it to secure its memory, decrypt the components and verify
+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:
+
+Subcode 8: Set an IPL Information Block of type 5.
+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
+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.
+
+
+When running in a protected mode some subcodes will result in
+exceptions or return error codes.
+
+Subcodes 4 and 7 will result in specification exceptions.
+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.