diff mbox series

[v2] docs: Add measurement calculation details to amd-memory-encryption.txt

Message ID 20211220104224.143961-1-dovmurik@linux.ibm.com
State New
Headers show
Series [v2] docs: Add measurement calculation details to amd-memory-encryption.txt | expand

Commit Message

Dov Murik Dec. 20, 2021, 10:42 a.m. UTC 
Add a section explaining how the Guest Owner should calculate the
expected guest launch measurement for SEV and SEV-ES.

Also update the name and link to the SEV API Spec document.

Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
Suggested-by: Daniel P. Berrangé <berrange@redhat.com>

---

v2:
- Explain that firmware must be built without NVRAM store.
---
 docs/amd-memory-encryption.txt | 52 +++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 4 deletions(-)


base-commit: 212a33d3b0c65ae2583bb1d06cb140cd0890894c

Comments

Daniel P. Berrangé Jan. 4, 2022, 6 p.m. UTC | #1 
On Mon, Dec 20, 2021 at 10:42:24AM +0000, Dov Murik wrote:
> Add a section explaining how the Guest Owner should calculate the
> expected guest launch measurement for SEV and SEV-ES.
> 
> Also update the name and link to the SEV API Spec document.
> 
> Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
> Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
> 
> ---
> 
> v2:
> - Explain that firmware must be built without NVRAM store.
> ---
>  docs/amd-memory-encryption.txt | 52 +++++++++++++++++++++++++++++++---
>  1 file changed, 48 insertions(+), 4 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
Dov Murik Feb. 15, 2022, 6:52 a.m. UTC | #2 
On 04/01/2022 20:00, Daniel P. Berrangé wrote:
> On Mon, Dec 20, 2021 at 10:42:24AM +0000, Dov Murik wrote:
>> Add a section explaining how the Guest Owner should calculate the
>> expected guest launch measurement for SEV and SEV-ES.
>>
>> Also update the name and link to the SEV API Spec document.
>>
>> Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
>> Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
>>
>> ---
>>
>> v2:
>> - Explain that firmware must be built without NVRAM store.
>> ---
>>  docs/amd-memory-encryption.txt | 52 +++++++++++++++++++++++++++++++---
>>  1 file changed, 48 insertions(+), 4 deletions(-)
> 
> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> 

Paolo,

Can you please add this to your queue?

Original patch v2:
https://lore.kernel.org/qemu-devel/20211220104224.143961-1-dovmurik@linux.ibm.com/

Thanks,
Dov
Daniel P. Berrangé Feb. 16, 2022, 7:01 p.m. UTC | #3 
On Tue, Feb 15, 2022 at 08:52:21AM +0200, Dov Murik wrote:
> 
> 
> On 04/01/2022 20:00, Daniel P. Berrangé wrote:
> > On Mon, Dec 20, 2021 at 10:42:24AM +0000, Dov Murik wrote:
> >> Add a section explaining how the Guest Owner should calculate the
> >> expected guest launch measurement for SEV and SEV-ES.
> >>
> >> Also update the name and link to the SEV API Spec document.
> >>
> >> Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
> >> Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
> >>
> >> ---
> >>
> >> v2:
> >> - Explain that firmware must be built without NVRAM store.
> >> ---
> >>  docs/amd-memory-encryption.txt | 52 +++++++++++++++++++++++++++++++---
> >>  1 file changed, 48 insertions(+), 4 deletions(-)
> > 
> > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> > 
> 
> Paolo,
> 
> Can you please add this to your queue?
> 
> Original patch v2:
> https://lore.kernel.org/qemu-devel/20211220104224.143961-1-dovmurik@linux.ibm.com/

Could you re-send this patch. The file has been moved, which git
tracked fine, but its also converted to rst format, and so needs
some content tweaks for linking to the external URLs properly.

Regards,
Daniel
diff mbox series

Patch

diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt
index ffca382b5f..fcb712ee90 100644
--- a/docs/amd-memory-encryption.txt
+++ b/docs/amd-memory-encryption.txt
@@ -43,7 +43,7 @@  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 a running SEV guest.
-See KM Spec section 3 and 6.2 for more details.
+See SEV API Spec [1] section 3 and 6.2 for more details.
 
 The guest policy can be provided via the 'policy' property (see below)
 
@@ -88,7 +88,7 @@  expects.
 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
+See SEV API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
 complete flow chart.
 
 To launch a SEV guest
@@ -113,6 +113,47 @@  a SEV-ES guest:
  - Requires in-kernel irqchip - the burden is placed on the hypervisor to
    manage booting APs.
 
+Calculating expected guest launch measurement
+---------------------------------------------
+In order to verify the guest launch measurement, The Guest Owner must compute
+it in the exact same way as it is calculated by the AMD-SP.  SEV API Spec [1]
+section 6.5.1 describes the AMD-SP operations:
+
+    GCTX.LD is finalized, producing the hash digest of all plaintext data
+    imported into the guest.
+
+    The launch measurement is calculated as:
+
+    HMAC(0x04 || API_MAJOR || API_MINOR || BUILD || GCTX.POLICY || GCTX.LD || MNONCE; GCTX.TIK)
+
+    where "||" represents concatenation.
+
+The values of API_MAJOR, API_MINOR, BUILD, and GCTX.POLICY can be obtained
+from the 'query-sev' qmp command.
+
+The value of MNONCE is part of the response of 'query-sev-launch-measure': it
+is the last 16 bytes of the base64-decoded data field (see SEV API Spec [1]
+section 6.5.2 Table 52: LAUNCH_MEASURE Measurement Buffer).
+
+The value of GCTX.LD is SHA256(firmware_blob || kernel_hashes_blob || vmsas_blob),
+where:
+
+* firmware_blob is the content of the entire firmware flash file (for example,
+  OVMF.fd).  Note that you must build a stateless firmware file which doesn't
+  use an NVRAM store, because the NVRAM area is not measured, and therefore it
+  is not secure to use a firmware which uses state from an NVRAM store.
+* if kernel is used, and kernel-hashes=on, then kernel_hashes_blob is the
+  content of PaddedSevHashTable (including the zero padding), which itself
+  includes the hashes of kernel, initrd, and cmdline that are passed to the
+  guest.  The PaddedSevHashTable struct is defined in target/i386/sev.c .
+* if SEV-ES is enabled (policy & 0x4 != 0), vmsas_blob is the concatenation of
+  all VMSAs of the guest vcpus.  Each VMSA is 4096 bytes long; its content is
+  defined inside Linux kernel code as struct vmcb_save_area, or in AMD APM
+  Volume 2 [2] Table B-2: VMCB Layout, State Save Area.
+
+If kernel hashes are not used, or SEV-ES is disabled, use empty blobs for
+kernel_hashes_blob and vmsas_blob as needed.
+
 Debugging
 -----------
 Since the memory contents of a SEV guest are encrypted, hypervisor access to
@@ -134,8 +175,11 @@  References
 AMD Memory Encryption whitepaper:
 https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
 
-Secure Encrypted Virtualization Key Management:
-[1] http://developer.amd.com/wordpress/media/2017/11/55766_SEV-KM-API_Specification.pdf
+Secure Encrypted Virtualization API:
+[1] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
+
+AMD64 Architecture Programmer's Manual Volume 2: System Programming
+[2] https://www.amd.com/system/files/TechDocs/24593.pdf
 
 KVM Forum slides:
 http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf