Message ID | 10ccd85a95b302c7a7465190fcb0dcbe534133cb.1720004383.git.roy.hopkins@suse.com (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
Series | Introduce support for IGVM files | expand |
On Wed, Jul 03, 2024 at 12:05:49PM +0100, Roy Hopkins wrote: > IGVM support has been implemented for Confidential Guests that support > AMD SEV and AMD SEV-ES. Add some documentation that gives some > background on the IGVM format and how to use it to configure a > confidential guest. > > Signed-off-by: Roy Hopkins <roy.hopkins@suse.com> > --- > docs/system/i386/amd-memory-encryption.rst | 2 + > docs/system/igvm.rst | 173 +++++++++++++++++++++ > docs/system/index.rst | 1 + > 3 files changed, 176 insertions(+) > create mode 100644 docs/system/igvm.rst Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> With regards, Daniel
On Wed, Jul 03, 2024 at 12:05:49PM GMT, Roy Hopkins wrote: >IGVM support has been implemented for Confidential Guests that support >AMD SEV and AMD SEV-ES. Add some documentation that gives some >background on the IGVM format and how to use it to configure a >confidential guest. > >Signed-off-by: Roy Hopkins <roy.hopkins@suse.com> >--- > docs/system/i386/amd-memory-encryption.rst | 2 + > docs/system/igvm.rst | 173 +++++++++++++++++++++ > docs/system/index.rst | 1 + > 3 files changed, 176 insertions(+) > create mode 100644 docs/system/igvm.rst > >diff --git a/docs/system/i386/amd-memory-encryption.rst b/docs/system/i386/amd-memory-encryption.rst >index 748f5094ba..6c23f3535f 100644 >--- a/docs/system/i386/amd-memory-encryption.rst >+++ b/docs/system/i386/amd-memory-encryption.rst >@@ -1,3 +1,5 @@ >+.. _amd-sev: >+ > AMD Secure Encrypted Virtualization (SEV) > ========================================= > >diff --git a/docs/system/igvm.rst b/docs/system/igvm.rst >new file mode 100644 >index 0000000000..36146a81df >--- /dev/null >+++ b/docs/system/igvm.rst >@@ -0,0 +1,173 @@ >+Independent Guest Virtual Machine (IGVM) support >+================================================ >+ >+IGVM files are designed to encapsulate all the information required to launch a >+virtual machine on any given virtualization stack in a deterministic way. This >+allows the cryptographic measurement of initial guest state for Confidential >+Guests to be calculated when the IGVM file is built, allowing a relying party to >+verify the initial state of a guest via a remote attestation. >+ >+Although IGVM files are designed with Confidential Computing in mind, they can >+also be used to configure non-confidential guests. Multiple platforms can be >+defined by a single IGVM file, allowing a single IGVM file to configure a >+virtual machine that can run on, for example, TDX, SEV and non-confidential >+hosts. >+ >+QEMU supports IGVM files through the user-creatable ``igvm-cfg`` object. This >+object is used to define the filename of the IGVM file to process. A reference >+to the object is added to the ``-machine`` to configure the virtual machine >+to use the IGVM file for configuration. >+ >+Confidential platform support is provided through the use of >+the ``ConfidentialGuestSupport`` object. If the virtual machine provides an >+instance of this object then this is used by the IGVM loader to configure the >+isolation properties of the directives within the file. >+ >+Further Information on IGVM >+--------------------------- >+ >+Information about the IGVM format, including links to the format specification >+and documentation for the Rust and C libraries can be found at the project >+repository: >+ >+https://github.com/microsoft/igvm >+ >+ >+Supported Platforms >+------------------- >+ >+Currently, IGVM files can be provided for Confidential Guests on host systems >+that support AMD SEV, SEV-ES and SEV-SNP with KVM. IGVM files can also be >+provided for non-confidential guests. >+ >+ >+Limitations when using IGVM with AMD SEV, SEV-ES and SEV-SNP >+------------------------------------------------------------ >+ >+IGVM files configure the initial state of the guest using a set of directives. >+Not every directive is supported by every Confidential Guest type. For example, >+AMD SEV does not support encrypted save state regions, therefore setting the >+initial CPU state using IGVM for SEV is not possible. When an IGVM file contains >+directives that are not supported for the active platform, an error is generated >+and the guest launch is aborted. >+ >+The table below describes the list of directives that are supported for SEV, >+SEV-ES, SEV-SNP and non-confidential platforms. >+ >+.. list-table:: SEV, SEV-ES, SEV-SNP & non-confidential Supported Directives >+ :widths: 35 65 >+ :header-rows: 1 >+ >+ * - IGVM directive >+ - Notes >+ * - IGVM_VHT_PAGE_DATA >+ - ``NORMAL`` zero, measured and unmeasured page types are supported. Other >+ page types result in an error. >+ * - IGVM_VHT_PARAMETER_AREA >+ - >+ * - IGVM_VHT_PARAMETER_INSERT >+ - >+ * - IGVM_VHT_VP_COUNT_PARAMETER >+ - The guest parameter page is populated with the CPU count. >+ * - IGVM_VHT_ENVIRONMENT_INFO_PARAMETER >+ - The ``memory_is_shared`` parameter is set to 1 in the guest parameter >+ page. >+ >+.. list-table:: Additional SEV, SEV-ES & SEV_SNP Supported Directives >+ :widths: 25 75 >+ :header-rows: 1 >+ >+ * - IGVM directive >+ - Notes >+ * - IGVM_VHT_MEMORY_MAP >+ - The memory map page is populated using entries from the E820 table. >+ * - IGVM_VHT_REQUIRED_MEMORY >+ - >+ >+.. list-table:: Additional SEV-ES & SEV-SNP Supported Directives >+ :widths: 25 75 >+ :header-rows: 1 >+ >+ * - IGVM directive >+ - Notes >+ * - IGVM_VHT_VP_CONTEXT >+ - Setting of the initial CPU state for the boot CPU and additional CPUs is >+ supported with limitations on the fields that can be provided in the >+ VMSA. See below for details on which fields are supported. >+ >+Initial CPU state with VMSA >+--------------------------- >+ >+The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES >+and SEV-SNP. The state data is provided as a VMSA structure as defined in Table >+B-4 in the AMD64 Architecture Programmer's Manual, Volume 2 [1]. >+ >+The IGVM VMSA is translated to CPU state in QEMU which is then synchronized >+by KVM to the guest VMSA during the launch process where it contributes to the >+launch measurement. See :ref:`amd-sev` for details on the launch process and >+guest launch measurement. >+ >+It is important that no information is lost or changed when translating the >+VMSA provided by the IGVM file into the VSMA that is used to launch the guest. >+Therefore, QEMU restricts the VMSA fields that can be provided in the IGVM >+VMSA structure to the following registers: >+ >+RAX, RCX, RDX, RBX, RBP, RSI, RDI, R8-R15, RSP, RIP, CS, DS, ES, FS, GS, SS, >+CR0, CR3, CR4, XCR0, EFER, PAT, GDT, IDT, LDTR, TR, DR6, DR7, RFLAGS, X87_FCW, >+MXCSR. >+ >+When processing the IGVM file, QEMU will check if any fields other than the >+above are non-zero and generate an error if this is the case. >+ >+KVM uses a hardcoded GPA of 0xFFFFFFFFF000 for the VMSA. When an IGVM file >+defines initial CPU state, the GPA for each VMSA must match this hardcoded >+value. >+ >+Firmware Images with IGVM >+------------------------- >+ >+When an IGVM filename is specified for a Confidential Guest Support object it >+overrides the default handling of system firmware: the firmware image, such as >+an OVMF binary should be contained as a payload of the IGVM file and not >+provided as a flash drive or via the ``-bios`` parameter. The default QEMU >+firmware is not automatically populated into the guest memory space. >+ >+If an IGVM file is provided along with either the ``-bios`` parameter or pflash >+devices then an error is displayed and the guest startup is aborted. >+ >+Running a guest configured using IGVM >+------------------------------------- >+ >+To run a guest configured with IGVM you firstly need to generate an IGVM file >+that contains a guest configuration compatible with the platform you are >+targeting. >+ >+The ``buildigvm`` tool [2] is an example of a tool that can be used to generate >+IGVM files for non-confidential X86 platforms as well as for SEV, SEV-ES and >+SEV-SNP confidential platforms. >+ >+Example using this tool to generate an IGVM file for AMD SEV-SNP:: >+ >+ buildigvm --firmware /path/to/OVMF.fd --output sev-snp.igvm \ >+ --cpucount 4 sev-snp >+ >+To run a guest configured with the generated IGVM you need to add an >+``igvm-cfg`` object and refer to it from the ``-machine`` parameter: >+ >+Example (for AMD SEV):: >+ >+ qemu-system-x86_64 \ >+ <other parameters> \ >+ -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \ >+ -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \ >+ -object igvm-cfg,id=igvm0,file=/path/to/sev-snp.igvm >+ >+References >+---------- >+ >+[1] AMD64 Architecture Programmer's Manual, Volume 2: System Programming >+ Rev 3.41 >+ https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf >+ >+[2] ``buildigvm`` - A tool to build example IGVM files containing OVMF firmware >+ https://github.com/roy-hopkins/buildigvm Should we also put a reference to the tool we have in Coconut SVSM? BTW, this patch LGTM: Reviewed-by: Stefano Garzarella <sgarzare@redhat.com> >\ No newline at end of file >diff --git a/docs/system/index.rst b/docs/system/index.rst >index c21065e519..6235dfab87 100644 >--- a/docs/system/index.rst >+++ b/docs/system/index.rst >@@ -38,4 +38,5 @@ or Hypervisor.Framework. > security > multi-process > confidential-guest-support >+ igvm > vm-templating >-- >2.43.0 >
diff --git a/docs/system/i386/amd-memory-encryption.rst b/docs/system/i386/amd-memory-encryption.rst index 748f5094ba..6c23f3535f 100644 --- a/docs/system/i386/amd-memory-encryption.rst +++ b/docs/system/i386/amd-memory-encryption.rst @@ -1,3 +1,5 @@ +.. _amd-sev: + AMD Secure Encrypted Virtualization (SEV) ========================================= diff --git a/docs/system/igvm.rst b/docs/system/igvm.rst new file mode 100644 index 0000000000..36146a81df --- /dev/null +++ b/docs/system/igvm.rst @@ -0,0 +1,173 @@ +Independent Guest Virtual Machine (IGVM) support +================================================ + +IGVM files are designed to encapsulate all the information required to launch a +virtual machine on any given virtualization stack in a deterministic way. This +allows the cryptographic measurement of initial guest state for Confidential +Guests to be calculated when the IGVM file is built, allowing a relying party to +verify the initial state of a guest via a remote attestation. + +Although IGVM files are designed with Confidential Computing in mind, they can +also be used to configure non-confidential guests. Multiple platforms can be +defined by a single IGVM file, allowing a single IGVM file to configure a +virtual machine that can run on, for example, TDX, SEV and non-confidential +hosts. + +QEMU supports IGVM files through the user-creatable ``igvm-cfg`` object. This +object is used to define the filename of the IGVM file to process. A reference +to the object is added to the ``-machine`` to configure the virtual machine +to use the IGVM file for configuration. + +Confidential platform support is provided through the use of +the ``ConfidentialGuestSupport`` object. If the virtual machine provides an +instance of this object then this is used by the IGVM loader to configure the +isolation properties of the directives within the file. + +Further Information on IGVM +--------------------------- + +Information about the IGVM format, including links to the format specification +and documentation for the Rust and C libraries can be found at the project +repository: + +https://github.com/microsoft/igvm + + +Supported Platforms +------------------- + +Currently, IGVM files can be provided for Confidential Guests on host systems +that support AMD SEV, SEV-ES and SEV-SNP with KVM. IGVM files can also be +provided for non-confidential guests. + + +Limitations when using IGVM with AMD SEV, SEV-ES and SEV-SNP +------------------------------------------------------------ + +IGVM files configure the initial state of the guest using a set of directives. +Not every directive is supported by every Confidential Guest type. For example, +AMD SEV does not support encrypted save state regions, therefore setting the +initial CPU state using IGVM for SEV is not possible. When an IGVM file contains +directives that are not supported for the active platform, an error is generated +and the guest launch is aborted. + +The table below describes the list of directives that are supported for SEV, +SEV-ES, SEV-SNP and non-confidential platforms. + +.. list-table:: SEV, SEV-ES, SEV-SNP & non-confidential Supported Directives + :widths: 35 65 + :header-rows: 1 + + * - IGVM directive + - Notes + * - IGVM_VHT_PAGE_DATA + - ``NORMAL`` zero, measured and unmeasured page types are supported. Other + page types result in an error. + * - IGVM_VHT_PARAMETER_AREA + - + * - IGVM_VHT_PARAMETER_INSERT + - + * - IGVM_VHT_VP_COUNT_PARAMETER + - The guest parameter page is populated with the CPU count. + * - IGVM_VHT_ENVIRONMENT_INFO_PARAMETER + - The ``memory_is_shared`` parameter is set to 1 in the guest parameter + page. + +.. list-table:: Additional SEV, SEV-ES & SEV_SNP Supported Directives + :widths: 25 75 + :header-rows: 1 + + * - IGVM directive + - Notes + * - IGVM_VHT_MEMORY_MAP + - The memory map page is populated using entries from the E820 table. + * - IGVM_VHT_REQUIRED_MEMORY + - + +.. list-table:: Additional SEV-ES & SEV-SNP Supported Directives + :widths: 25 75 + :header-rows: 1 + + * - IGVM directive + - Notes + * - IGVM_VHT_VP_CONTEXT + - Setting of the initial CPU state for the boot CPU and additional CPUs is + supported with limitations on the fields that can be provided in the + VMSA. See below for details on which fields are supported. + +Initial CPU state with VMSA +--------------------------- + +The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES +and SEV-SNP. The state data is provided as a VMSA structure as defined in Table +B-4 in the AMD64 Architecture Programmer's Manual, Volume 2 [1]. + +The IGVM VMSA is translated to CPU state in QEMU which is then synchronized +by KVM to the guest VMSA during the launch process where it contributes to the +launch measurement. See :ref:`amd-sev` for details on the launch process and +guest launch measurement. + +It is important that no information is lost or changed when translating the +VMSA provided by the IGVM file into the VSMA that is used to launch the guest. +Therefore, QEMU restricts the VMSA fields that can be provided in the IGVM +VMSA structure to the following registers: + +RAX, RCX, RDX, RBX, RBP, RSI, RDI, R8-R15, RSP, RIP, CS, DS, ES, FS, GS, SS, +CR0, CR3, CR4, XCR0, EFER, PAT, GDT, IDT, LDTR, TR, DR6, DR7, RFLAGS, X87_FCW, +MXCSR. + +When processing the IGVM file, QEMU will check if any fields other than the +above are non-zero and generate an error if this is the case. + +KVM uses a hardcoded GPA of 0xFFFFFFFFF000 for the VMSA. When an IGVM file +defines initial CPU state, the GPA for each VMSA must match this hardcoded +value. + +Firmware Images with IGVM +------------------------- + +When an IGVM filename is specified for a Confidential Guest Support object it +overrides the default handling of system firmware: the firmware image, such as +an OVMF binary should be contained as a payload of the IGVM file and not +provided as a flash drive or via the ``-bios`` parameter. The default QEMU +firmware is not automatically populated into the guest memory space. + +If an IGVM file is provided along with either the ``-bios`` parameter or pflash +devices then an error is displayed and the guest startup is aborted. + +Running a guest configured using IGVM +------------------------------------- + +To run a guest configured with IGVM you firstly need to generate an IGVM file +that contains a guest configuration compatible with the platform you are +targeting. + +The ``buildigvm`` tool [2] is an example of a tool that can be used to generate +IGVM files for non-confidential X86 platforms as well as for SEV, SEV-ES and +SEV-SNP confidential platforms. + +Example using this tool to generate an IGVM file for AMD SEV-SNP:: + + buildigvm --firmware /path/to/OVMF.fd --output sev-snp.igvm \ + --cpucount 4 sev-snp + +To run a guest configured with the generated IGVM you need to add an +``igvm-cfg`` object and refer to it from the ``-machine`` parameter: + +Example (for AMD SEV):: + + qemu-system-x86_64 \ + <other parameters> \ + -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \ + -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \ + -object igvm-cfg,id=igvm0,file=/path/to/sev-snp.igvm + +References +---------- + +[1] AMD64 Architecture Programmer's Manual, Volume 2: System Programming + Rev 3.41 + https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf + +[2] ``buildigvm`` - A tool to build example IGVM files containing OVMF firmware + https://github.com/roy-hopkins/buildigvm \ No newline at end of file diff --git a/docs/system/index.rst b/docs/system/index.rst index c21065e519..6235dfab87 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -38,4 +38,5 @@ or Hypervisor.Framework. security multi-process confidential-guest-support + igvm vm-templating
IGVM support has been implemented for Confidential Guests that support AMD SEV and AMD SEV-ES. Add some documentation that gives some background on the IGVM format and how to use it to configure a confidential guest. Signed-off-by: Roy Hopkins <roy.hopkins@suse.com> --- docs/system/i386/amd-memory-encryption.rst | 2 + docs/system/igvm.rst | 173 +++++++++++++++++++++ docs/system/index.rst | 1 + 3 files changed, 176 insertions(+) create mode 100644 docs/system/igvm.rst