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

[Tom Lendacky]

On 4/22/21 9:09 AM, Laszlo Ersek wrote:
> 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.

Ok, will do. Since I'm splitting it I'll go through it in a bit more
detail and there will be additional changes without any new information.

> 
> (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).

I'll give that a shot. Let me know if I got it right when you review it :)

Look for a follow-on three patch series.

Thanks,
Tom

> 
> 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:
>>>  
>>> https://nam11.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.linux-kvm.org%2Fimages%2F7%2F74%2F02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf&amp;data=04%7C01%7Cthomas.lendacky%40amd.com%7C6634432836a44cf1d8d008d9059841dc%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637546974656868321%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=WirOAt5yzLnftEm4Auroh5aKtlCQTdARYbucGeYIcpw%3D&amp;reserved=0
>>> +https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.linux-kvm.org%2Fimages%2F9%2F94%2FExtending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf&amp;data=04%7C01%7Cthomas.lendacky%40amd.com%7C6634432836a44cf1d8d008d9059841dc%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637546974656878322%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=5UeYN24AWUTrwetudnTaXCvP39IqY2OvUBts0ntnHNs%3D&amp;reserved=0
>>>  
>>>  AMD64 Architecture Programmer's Manual:
>>>     
>>> https://nam11.safelinks.protection.outlook.com/?url=http%3A%2F%2Fsupport.amd.com%2FTechDocs%2F24593.pdf&amp;data=04%7C01%7Cthomas.lendacky%40amd.com%7C6634432836a44cf1d8d008d9059841dc%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637546974656878322%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=MY2RjiXVN5Dr8yz7RkusdMgTKumiK71C9CBVEOoHQVk%3D&amp;reserved=0
>>>     SME is section 7.10
>>>     SEV is section 15.34
>>> +   SEV-ES is section 15.35
>>>
>>
>