[v2,1/3] doc: Fix some mistakes in the SEV documentation

From: Tom Lendacky <thomas.lendacky@amd.com>

Fix some spelling and grammar mistakes in the amd-memory-encryption.txt
file. No new information added.

Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
---
 docs/amd-memory-encryption.txt | 59 +++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 30 deletions(-)

On 04/23/21 22:08, Tom Lendacky wrote:
> From: Tom Lendacky <thomas.lendacky@amd.com>
> 
> Fix some spelling and grammar mistakes in the amd-memory-encryption.txt
> file. No new information added.
> 
> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
> ---
>  docs/amd-memory-encryption.txt | 59 +++++++++++++++++-----------------
>  1 file changed, 29 insertions(+), 30 deletions(-)
> 
> diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt
> index 145896aec7..ed85159ea7 100644
> --- a/docs/amd-memory-encryption.txt
> +++ b/docs/amd-memory-encryption.txt
> @@ -1,38 +1,38 @@
>  Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
>  
>  SEV is an extension to the AMD-V architecture which supports running encrypted
> -virtual machine (VMs) under the control of KVM. Encrypted VMs have their pages
> +virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
>  (code and data) secured such that only the guest itself has access to the
>  unencrypted version. Each encrypted VM is associated with a unique encryption
> -key; if its data is accessed to a different entity using a different key the
> +key; if its data is accessed by a different entity using a different key the
>  encrypted guests data will be incorrectly decrypted, leading to unintelligible
>  data.
>  
> -The key management of this feature is handled by separate processor known as
> -AMD secure processor (AMD-SP) which is present in AMD SOCs. Firmware running
> -inside the AMD-SP provide commands to support common VM lifecycle. This
> +Key management for this feature is handled by a separate processor known as the
> +AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
> +inside the AMD-SP provides commands to support a common VM lifecycle. This
>  includes commands for launching, snapshotting, migrating and debugging the
> -encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP
> +encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
>  ioctls.
>  
>  Launching
>  ---------
> -Boot images (such as bios) must be encrypted before guest can be booted.
> -MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images :LAUNCH_START,
> +Boot images (such as bios) must be encrypted before a guest can be booted. The
> +MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
>  LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
>  together generate a fresh memory encryption key for the VM, encrypt the boot
> -images and provide a measurement than can be used as an attestation of the
> +images and provide a measurement than can be used as an attestation of a
>  successful launch.
>  
>  LAUNCH_START is called first to create a cryptographic launch context within
> -the firmware. To create this context, guest owner must provides guest policy,
> +the firmware. To create this context, guest owner must provide a guest policy,
>  its public Diffie-Hellman key (PDH) and session parameters. These inputs
> -should be treated as binary blob and must be passed as-is to the SEV firmware.
> +should be treated as a binary blob and must be passed as-is to the SEV firmware.
>  
> -The guest policy is passed as plaintext and hypervisor may able to read it
> +The guest policy is passed as plaintext. A hypervisor may choose to read it,
>  but should not modify it (any modification of the policy bits will result
>  in bad measurement). The guest policy is a 4-byte data structure containing
> -several flags that restricts what can be done on running SEV guest.
> +several flags that restricts what can be done on a running SEV guest.
>  See KM Spec section 3 and 6.2 for more details.
>  
>  The guest policy can be provided via the 'policy' property (see below)
> @@ -40,31 +40,30 @@ The guest policy can be provided via the 'policy' property (see below)
>  # ${QEMU} \
>     sev-guest,id=sev0,policy=0x1...\
>  
> -Guest owners provided DH certificate and session parameters will be used to
> +The guest owner provided DH certificate and session parameters will be used to
>  establish a cryptographic session with the guest owner to negotiate keys used
>  for the attestation.
>  
> -The DH certificate and session blob can be provided via 'dh-cert-file' and
> -'session-file' property (see below
> +The DH certificate and session blob can be provided via the 'dh-cert-file' and
> +'session-file' properties (see below)
>  
>  # ${QEMU} \
>       sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
>  
>  LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
> -created via LAUNCH_START command. If required, this command can be called
> +created via the LAUNCH_START command. If required, this command can be called
>  multiple times to encrypt different memory regions. The command also calculates
>  the measurement of the memory contents as it encrypts.
>  
> -LAUNCH_MEASURE command can be used to retrieve the measurement of encrypted
> -memory. This measurement is a signature of the memory contents that can be
> -sent to the guest owner as an attestation that the memory was encrypted
> -correctly by the firmware. The guest owner may wait to provide the guest
> -confidential information until it can verify the attestation measurement.
> -Since the guest owner knows the initial contents of the guest at boot, the
> -attestation measurement can be verified by comparing it to what the guest owner
> -expects.
> +LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory.
> +This measurement is a signature of the memory contents that can be sent to the
> +guest owner as an attestation that the memory was encrypted correctly by the
> +firmware. The guest owner may wait to provide the guest confidential information
> +until it can verify the attestation measurement. Since the guest owner knows the
> +initial contents of the guest at boot, the attestation measurement can be
> +verified by comparing it to what the guest owner expects.
>  
> -LAUNCH_FINISH command finalizes the guest launch and destroy's the cryptographic
> +LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
>  context.
>  
>  See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
> @@ -78,10 +77,10 @@ To launch a SEV guest
>  
>  Debugging
>  -----------
> -Since memory contents of SEV guest is encrypted hence hypervisor access to the
> -guest memory will get a cipher text. If guest policy allows debugging, then
> -hypervisor can use DEBUG_DECRYPT and DEBUG_ENCRYPT commands access the guest
> -memory region for debug purposes.  This is not supported in QEMU yet.
> +Since the memory contents of a SEV guest are encrypted, hypervisor access to
> +the guest memory will return cipher text. If the guest policy allows debugging,
> +then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
> +the guest memory region for debug purposes.  This is not supported in QEMU yet.
>  
>  Snapshot/Restore
>  -----------------
> 

Reviewed-by: Laszlo Ersek <lersek@redhat.com>

Just a quick ping on this series...

Thanks,
Tom

On 4/23/21 3:08 PM, Tom Lendacky wrote:
> From: Tom Lendacky <thomas.lendacky@amd.com>
> 
> Fix some spelling and grammar mistakes in the amd-memory-encryption.txt
> file. No new information added.
> 
> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
> ---
>  docs/amd-memory-encryption.txt | 59 +++++++++++++++++-----------------
>  1 file changed, 29 insertions(+), 30 deletions(-)
> 
> diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt
> index 145896aec7..ed85159ea7 100644
> --- a/docs/amd-memory-encryption.txt
> +++ b/docs/amd-memory-encryption.txt
> @@ -1,38 +1,38 @@
>  Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
>  
>  SEV is an extension to the AMD-V architecture which supports running encrypted
> -virtual machine (VMs) under the control of KVM. Encrypted VMs have their pages
> +virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
>  (code and data) secured such that only the guest itself has access to the
>  unencrypted version. Each encrypted VM is associated with a unique encryption
> -key; if its data is accessed to a different entity using a different key the
> +key; if its data is accessed by a different entity using a different key the
>  encrypted guests data will be incorrectly decrypted, leading to unintelligible
>  data.
>  
> -The key management of this feature is handled by separate processor known as
> -AMD secure processor (AMD-SP) which is present in AMD SOCs. Firmware running
> -inside the AMD-SP provide commands to support common VM lifecycle. This
> +Key management for this feature is handled by a separate processor known as the
> +AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
> +inside the AMD-SP provides commands to support a common VM lifecycle. This
>  includes commands for launching, snapshotting, migrating and debugging the
> -encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP
> +encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
>  ioctls.
>  
>  Launching
>  ---------
> -Boot images (such as bios) must be encrypted before guest can be booted.
> -MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images :LAUNCH_START,
> +Boot images (such as bios) must be encrypted before a guest can be booted. The
> +MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
>  LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
>  together generate a fresh memory encryption key for the VM, encrypt the boot
> -images and provide a measurement than can be used as an attestation of the
> +images and provide a measurement than can be used as an attestation of a
>  successful launch.
>  
>  LAUNCH_START is called first to create a cryptographic launch context within
> -the firmware. To create this context, guest owner must provides guest policy,
> +the firmware. To create this context, guest owner must provide a guest policy,
>  its public Diffie-Hellman key (PDH) and session parameters. These inputs
> -should be treated as binary blob and must be passed as-is to the SEV firmware.
> +should be treated as a binary blob and must be passed as-is to the SEV firmware.
>  
> -The guest policy is passed as plaintext and hypervisor may able to read it
> +The guest policy is passed as plaintext. A hypervisor may choose to read it,
>  but should not modify it (any modification of the policy bits will result
>  in bad measurement). The guest policy is a 4-byte data structure containing
> -several flags that restricts what can be done on running SEV guest.
> +several flags that restricts what can be done on a running SEV guest.
>  See KM Spec section 3 and 6.2 for more details.
>  
>  The guest policy can be provided via the 'policy' property (see below)
> @@ -40,31 +40,30 @@ The guest policy can be provided via the 'policy' property (see below)
>  # ${QEMU} \
>     sev-guest,id=sev0,policy=0x1...\
>  
> -Guest owners provided DH certificate and session parameters will be used to
> +The guest owner provided DH certificate and session parameters will be used to
>  establish a cryptographic session with the guest owner to negotiate keys used
>  for the attestation.
>  
> -The DH certificate and session blob can be provided via 'dh-cert-file' and
> -'session-file' property (see below
> +The DH certificate and session blob can be provided via the 'dh-cert-file' and
> +'session-file' properties (see below)
>  
>  # ${QEMU} \
>       sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
>  
>  LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
> -created via LAUNCH_START command. If required, this command can be called
> +created via the LAUNCH_START command. If required, this command can be called
>  multiple times to encrypt different memory regions. The command also calculates
>  the measurement of the memory contents as it encrypts.
>  
> -LAUNCH_MEASURE command can be used to retrieve the measurement of encrypted
> -memory. This measurement is a signature of the memory contents that can be
> -sent to the guest owner as an attestation that the memory was encrypted
> -correctly by the firmware. The guest owner may wait to provide the guest
> -confidential information until it can verify the attestation measurement.
> -Since the guest owner knows the initial contents of the guest at boot, the
> -attestation measurement can be verified by comparing it to what the guest owner
> -expects.
> +LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory.
> +This measurement is a signature of the memory contents that can be sent to the
> +guest owner as an attestation that the memory was encrypted correctly by the
> +firmware. The guest owner may wait to provide the guest confidential information
> +until it can verify the attestation measurement. Since the guest owner knows the
> +initial contents of the guest at boot, the attestation measurement can be
> +verified by comparing it to what the guest owner expects.
>  
> -LAUNCH_FINISH command finalizes the guest launch and destroy's the cryptographic
> +LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
>  context.
>  
>  See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
> @@ -78,10 +77,10 @@ To launch a SEV guest
>  
>  Debugging
>  -----------
> -Since memory contents of SEV guest is encrypted hence hypervisor access to the
> -guest memory will get a cipher text. If guest policy allows debugging, then
> -hypervisor can use DEBUG_DECRYPT and DEBUG_ENCRYPT commands access the guest
> -memory region for debug purposes.  This is not supported in QEMU yet.
> +Since the memory contents of a SEV guest are encrypted, hypervisor access to
> +the guest memory will return cipher text. If the guest policy allows debugging,
> +then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
> +the guest memory region for debug purposes.  This is not supported in QEMU yet.
>  
>  Snapshot/Restore
>  -----------------
>

On 4/23/21 3:08 PM, Tom Lendacky wrote:
> From: Tom Lendacky <thomas.lendacky@amd.com>
> 
> Fix some spelling and grammar mistakes in the amd-memory-encryption.txt
> file. No new information added.
> 
> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>

For the series:

Reviewed-by: Connor Kuehl <ckuehl@redhat.com>

On 06/02/21 21:19, Tom Lendacky wrote:
> Just a quick ping on this series...

Right, I'm unsure who is supposed to merge this... Do you remember who
usually merges the SEV-related patch series (plural)?

Thanks
Laszlo

> 
> Thanks,
> Tom
> 
> On 4/23/21 3:08 PM, Tom Lendacky wrote:
>> From: Tom Lendacky <thomas.lendacky@amd.com>
>>
>> Fix some spelling and grammar mistakes in the amd-memory-encryption.txt
>> file. No new information added.
>>
>> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
>> ---
>>  docs/amd-memory-encryption.txt | 59 +++++++++++++++++-----------------
>>  1 file changed, 29 insertions(+), 30 deletions(-)
>>
>> diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt
>> index 145896aec7..ed85159ea7 100644
>> --- a/docs/amd-memory-encryption.txt
>> +++ b/docs/amd-memory-encryption.txt
>> @@ -1,38 +1,38 @@
>>  Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
>>  
>>  SEV is an extension to the AMD-V architecture which supports running encrypted
>> -virtual machine (VMs) under the control of KVM. Encrypted VMs have their pages
>> +virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
>>  (code and data) secured such that only the guest itself has access to the
>>  unencrypted version. Each encrypted VM is associated with a unique encryption
>> -key; if its data is accessed to a different entity using a different key the
>> +key; if its data is accessed by a different entity using a different key the
>>  encrypted guests data will be incorrectly decrypted, leading to unintelligible
>>  data.
>>  
>> -The key management of this feature is handled by separate processor known as
>> -AMD secure processor (AMD-SP) which is present in AMD SOCs. Firmware running
>> -inside the AMD-SP provide commands to support common VM lifecycle. This
>> +Key management for this feature is handled by a separate processor known as the
>> +AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
>> +inside the AMD-SP provides commands to support a common VM lifecycle. This
>>  includes commands for launching, snapshotting, migrating and debugging the
>> -encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP
>> +encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
>>  ioctls.
>>  
>>  Launching
>>  ---------
>> -Boot images (such as bios) must be encrypted before guest can be booted.
>> -MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images :LAUNCH_START,
>> +Boot images (such as bios) must be encrypted before a guest can be booted. The
>> +MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
>>  LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
>>  together generate a fresh memory encryption key for the VM, encrypt the boot
>> -images and provide a measurement than can be used as an attestation of the
>> +images and provide a measurement than can be used as an attestation of a
>>  successful launch.
>>  
>>  LAUNCH_START is called first to create a cryptographic launch context within
>> -the firmware. To create this context, guest owner must provides guest policy,
>> +the firmware. To create this context, guest owner must provide a guest policy,
>>  its public Diffie-Hellman key (PDH) and session parameters. These inputs
>> -should be treated as binary blob and must be passed as-is to the SEV firmware.
>> +should be treated as a binary blob and must be passed as-is to the SEV firmware.
>>  
>> -The guest policy is passed as plaintext and hypervisor may able to read it
>> +The guest policy is passed as plaintext. A hypervisor may choose to read it,
>>  but should not modify it (any modification of the policy bits will result
>>  in bad measurement). The guest policy is a 4-byte data structure containing
>> -several flags that restricts what can be done on running SEV guest.
>> +several flags that restricts what can be done on a running SEV guest.
>>  See KM Spec section 3 and 6.2 for more details.
>>  
>>  The guest policy can be provided via the 'policy' property (see below)
>> @@ -40,31 +40,30 @@ The guest policy can be provided via the 'policy' property (see below)
>>  # ${QEMU} \
>>     sev-guest,id=sev0,policy=0x1...\
>>  
>> -Guest owners provided DH certificate and session parameters will be used to
>> +The guest owner provided DH certificate and session parameters will be used to
>>  establish a cryptographic session with the guest owner to negotiate keys used
>>  for the attestation.
>>  
>> -The DH certificate and session blob can be provided via 'dh-cert-file' and
>> -'session-file' property (see below
>> +The DH certificate and session blob can be provided via the 'dh-cert-file' and
>> +'session-file' properties (see below)
>>  
>>  # ${QEMU} \
>>       sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
>>  
>>  LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
>> -created via LAUNCH_START command. If required, this command can be called
>> +created via the LAUNCH_START command. If required, this command can be called
>>  multiple times to encrypt different memory regions. The command also calculates
>>  the measurement of the memory contents as it encrypts.
>>  
>> -LAUNCH_MEASURE command can be used to retrieve the measurement of encrypted
>> -memory. This measurement is a signature of the memory contents that can be
>> -sent to the guest owner as an attestation that the memory was encrypted
>> -correctly by the firmware. The guest owner may wait to provide the guest
>> -confidential information until it can verify the attestation measurement.
>> -Since the guest owner knows the initial contents of the guest at boot, the
>> -attestation measurement can be verified by comparing it to what the guest owner
>> -expects.
>> +LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory.
>> +This measurement is a signature of the memory contents that can be sent to the
>> +guest owner as an attestation that the memory was encrypted correctly by the
>> +firmware. The guest owner may wait to provide the guest confidential information
>> +until it can verify the attestation measurement. Since the guest owner knows the
>> +initial contents of the guest at boot, the attestation measurement can be
>> +verified by comparing it to what the guest owner expects.
>>  
>> -LAUNCH_FINISH command finalizes the guest launch and destroy's the cryptographic
>> +LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
>>  context.
>>  
>>  See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
>> @@ -78,10 +77,10 @@ To launch a SEV guest
>>  
>>  Debugging
>>  -----------
>> -Since memory contents of SEV guest is encrypted hence hypervisor access to the
>> -guest memory will get a cipher text. If guest policy allows debugging, then
>> -hypervisor can use DEBUG_DECRYPT and DEBUG_ENCRYPT commands access the guest
>> -memory region for debug purposes.  This is not supported in QEMU yet.
>> +Since the memory contents of a SEV guest are encrypted, hypervisor access to
>> +the guest memory will return cipher text. If the guest policy allows debugging,
>> +then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
>> +the guest memory region for debug purposes.  This is not supported in QEMU yet.
>>  
>>  Snapshot/Restore
>>  -----------------
>>
>

On Thu, Jun 03, 2021 at 10:29:35AM +0200, Laszlo Ersek wrote:
> On 06/02/21 21:19, Tom Lendacky wrote:
> > Just a quick ping on this series...
> 
> Right, I'm unsure who is supposed to merge this... Do you remember who
> usually merges the SEV-related patch series (plural)?

I'm queueing this series by now, but we truly need somebody to
volunteer as maintainer of the SEV code.