Re: [PATCH] docs: Add SEV-ES documentation to amd-memory-encryption.txt

[Laszlo Ersek]

On 04/21/21 21:31, Tom Lendacky wrote:
> On 4/21/21 2:12 PM, Tom Lendacky wrote:
>> From: Tom Lendacky <thomas.lendacky@amd.com>
>>
>> Update the amd-memory-encryption.txt file with information about SEV-ES,
>> including how to launch an SEV-ES guest and some of the differences
>> between SEV and SEV-ES guests in regards to launching and measuring the
>> guest.
>>
> 
> Hmm, it occurs to me that I should also mention some of the launch
> restrictions between SEV and SEV-ES - such as not supporting SMM or reboot
> in SEV-ES because of the requirements to modify the guest register state.
> 
> I'll wait for feedback on this version and send out a v2 with the added
> information.

I have two comments on v1 (and thanks much for posting it):

(1) Please split the typo fixes off to an initial patch. I tried to read
your changes carefully and the typo fixes kept throwing me off.

(2) Since you are already doing great work on this :) , can you tack on
the patch for "docs/interop/firmware.json"?

It would mean just duplicating the @amd-sev enum constant as @amd-sev-es
(documentation paragraph and the actual enum definition).

The new (SEV-ES) content in v1 looks plausible to me, but minimally
Brijesh should review it more closely.

Thanks!
Laszlo

> 
> Thanks,
> Tom
> 
>> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
>> ---
>>  docs/amd-memory-encryption.txt | 45 ++++++++++++++++++++++++++++------
>>  1 file changed, 37 insertions(+), 8 deletions(-)
>>
>> diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt
>> index 145896aec7..795b990fab 100644
>> --- a/docs/amd-memory-encryption.txt
>> +++ b/docs/amd-memory-encryption.txt
>> @@ -12,18 +12,28 @@ 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
>>  includes commands for launching, snapshotting, migrating and debugging the
>> -encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP
>> +encrypted guest. Those SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
>>  ioctls.
>>  
>> +Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV
>> +support to additionally protect the guest register state. In order to allow 
>> a
>> +hypervisor to perform functions on behalf of a guest, there is architectural
>> +support for notifying a guest's operating system when certain types of 
>> VMEXITs
>> +are about to occur. This allows the guest to selectively share information 
>> with
>> +the hypervisor to satisfy the requested function.
>> +
>>  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,
>> +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
>>  successful launch.
>>  
>> +For an SEV-ES guest, the LAUNCH_UPDATE_VMSA command is also used to encrypt 
>> the
>> +guest register state, or VM save area (VMSA), for all of the guest vCPUs.
>> +
>>  LAUNCH_START is called first to create a cryptographic launch context within
>>  the firmware. To create this context, guest owner must provides guest 
>> policy,
>>  its public Diffie-Hellman key (PDH) and session parameters. These inputs
>> @@ -40,31 +50,42 @@ The guest policy can be provided via the 'policy' 
>> property (see below)
>>  # ${QEMU} \
>>     sev-guest,id=sev0,policy=0x1...\
>>  
>> +Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as an
>> +SEV-ES guest (see below)
>> +
>> +# ${QEMU} \
>> +   sev-guest,id=sev0,policy=0x5...\
>> +
>>  Guest owners 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
>> +'session-file' property (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
>> +LAUNCH_UPDATE_VMSA encrypts all the vCPU VMSAs for an SEV-ES guest using the
>> +cryptographic context created via the LAUNCH_START command. The command also
>> +calculates the measurement of the VMSAs as it encrypts them.
>> +
>> +LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory 
>> and,
>> +for an SEV-ES guest, encrypted VMSAs. This measurement is a signature of the
>> +memory contents and, for an SEV-ES guest, the VMSA contents, that can be 
>> sent
>> +to the guest owner as an attestation that the memory and VMSAs were 
>> 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 command finalizes the guest launch and destroys the 
>> cryptographic
>>  context.
>>  
>>  See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
>> @@ -76,6 +97,12 @@ To launch a SEV guest
>>      -machine ...,confidential-guest-support=sev0 \
>>      -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1
>>  
>> +To launch a SEV-ES guest
>> +
>> +# ${QEMU} \
>> +    -machine ...,confidential-guest-support=sev0 \
>> +    -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5
>> +
>>  Debugging
>>  -----------
>>  Since memory contents of SEV guest is encrypted hence hypervisor access to 
>> the
>> @@ -102,8 +129,10 @@ Secure Encrypted Virtualization Key Management:
>>  
>>  KVM Forum slides:
>>  
>> http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
>> +https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf
>>  
>>  AMD64 Architecture Programmer's Manual:
>>     http://support.amd.com/TechDocs/24593.pdf
>>     SME is section 7.10
>>     SEV is section 15.34
>> +   SEV-ES is section 15.35
>>
>