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

[Laszlo Ersek]

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>