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

[Laszlo Ersek <lersek@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
>>  -----------------
>>
>