On 04/23/21 22:08, Tom Lendacky wrote:
> From: Tom Lendacky <thomas.lenda...@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.lenda...@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 <ler...@redhat.com>
