| 1 | Independent Guest Virtual Machine (IGVM) support |
| 2 | ================================================ |
| 3 | |
| 4 | IGVM files are designed to encapsulate all the information required to launch a |
| 5 | virtual machine on any given virtualization stack in a deterministic way. This |
| 6 | allows the cryptographic measurement of initial guest state for Confidential |
| 7 | Guests to be calculated when the IGVM file is built, allowing a relying party to |
| 8 | verify the initial state of a guest via a remote attestation. |
| 9 | |
| 10 | Although IGVM files are designed with Confidential Computing in mind, they can |
| 11 | also be used to configure non-confidential guests. Multiple platforms can be |
| 12 | defined by a single IGVM file, allowing a single IGVM file to configure a |
| 13 | virtual machine that can run on, for example, TDX, SEV and non-confidential |
| 14 | hosts. |
| 15 | |
| 16 | QEMU supports IGVM files through the user-creatable ``igvm-cfg`` object. This |
| 17 | object is used to define the filename of the IGVM file to process. A reference |
| 18 | to the object is added to the ``-machine`` to configure the virtual machine |
| 19 | to use the IGVM file for configuration. |
| 20 | |
| 21 | Confidential platform support is provided through the use of |
| 22 | the ``ConfidentialGuestSupport`` object. If the virtual machine provides an |
| 23 | instance of this object then this is used by the IGVM loader to configure the |
| 24 | isolation properties of the directives within the file. |
| 25 | |
| 26 | Further Information on IGVM |
| 27 | --------------------------- |
| 28 | |
| 29 | Information about the IGVM format, including links to the format specification |
| 30 | and documentation for the Rust and C libraries can be found at the project |
| 31 | repository: |
| 32 | |
| 33 | https://github.com/microsoft/igvm |
| 34 | |
| 35 | |
| 36 | Supported Platforms |
| 37 | ------------------- |
| 38 | |
| 39 | Currently, IGVM files can be provided for Confidential Guests on host systems |
| 40 | that support AMD SEV, SEV-ES and SEV-SNP with KVM. IGVM files can also be |
| 41 | provided for non-confidential guests. |
| 42 | |
| 43 | |
| 44 | Limitations when using IGVM with AMD SEV, SEV-ES and SEV-SNP |
| 45 | ------------------------------------------------------------ |
| 46 | |
| 47 | IGVM files configure the initial state of the guest using a set of directives. |
| 48 | Not every directive is supported by every Confidential Guest type. For example, |
| 49 | AMD SEV does not support encrypted save state regions, therefore setting the |
| 50 | initial CPU state using IGVM for SEV is not possible. When an IGVM file contains |
| 51 | directives that are not supported for the active platform, an error is generated |
| 52 | and the guest launch is aborted. |
| 53 | |
| 54 | The table below describes the list of directives that are supported for SEV, |
| 55 | SEV-ES, SEV-SNP and non-confidential platforms. |
| 56 | |
| 57 | .. list-table:: SEV, SEV-ES, SEV-SNP & non-confidential Supported Directives |
| 58 | :widths: 35 65 |
| 59 | :header-rows: 1 |
| 60 | |
| 61 | * - IGVM directive |
| 62 | - Notes |
| 63 | * - IGVM_VHT_PAGE_DATA |
| 64 | - ``NORMAL`` zero, measured and unmeasured page types are supported. Other |
| 65 | page types result in an error. |
| 66 | * - IGVM_VHT_PARAMETER_AREA |
| 67 | - |
| 68 | * - IGVM_VHT_PARAMETER_INSERT |
| 69 | - |
| 70 | * - IGVM_VHT_VP_COUNT_PARAMETER |
| 71 | - The guest parameter page is populated with the CPU count. |
| 72 | * - IGVM_VHT_ENVIRONMENT_INFO_PARAMETER |
| 73 | - The ``memory_is_shared`` parameter is set to 1 in the guest parameter |
| 74 | page. |
| 75 | |
| 76 | .. list-table:: Additional SEV, SEV-ES & SEV_SNP Supported Directives |
| 77 | :widths: 25 75 |
| 78 | :header-rows: 1 |
| 79 | |
| 80 | * - IGVM directive |
| 81 | - Notes |
| 82 | * - IGVM_VHT_MEMORY_MAP |
| 83 | - The memory map page is populated using entries from the E820 table. |
| 84 | * - IGVM_VHT_REQUIRED_MEMORY |
| 85 | - Ensures memory is available in the guest at the specified range. |
| 86 | |
| 87 | .. list-table:: Additional SEV-ES & SEV-SNP Supported Directives |
| 88 | :widths: 25 75 |
| 89 | :header-rows: 1 |
| 90 | |
| 91 | * - IGVM directive |
| 92 | - Notes |
| 93 | * - IGVM_VHT_VP_CONTEXT |
| 94 | - Setting of the initial CPU state for the boot CPU and additional CPUs is |
| 95 | supported with limitations on the fields that can be provided in the |
| 96 | VMSA. See below for details on which fields are supported. |
| 97 | |
| 98 | Initial CPU state with VMSA |
| 99 | --------------------------- |
| 100 | |
| 101 | The initial state of guest CPUs can be defined in the IGVM file for AMD SEV-ES |
| 102 | and SEV-SNP. The state data is provided as a VMSA structure as defined in Table |
| 103 | B-4 in the AMD64 Architecture Programmer's Manual, Volume 2 [1]. |
| 104 | |
| 105 | The IGVM VMSA is translated to CPU state in QEMU which is then synchronized |
| 106 | by KVM to the guest VMSA during the launch process where it contributes to the |
| 107 | launch measurement. See :ref:`amd-sev` for details on the launch process and |
| 108 | guest launch measurement. |
| 109 | |
| 110 | It is important that no information is lost or changed when translating the |
| 111 | VMSA provided by the IGVM file into the VSMA that is used to launch the guest. |
| 112 | Therefore, QEMU restricts the VMSA fields that can be provided in the IGVM |
| 113 | VMSA structure to the following registers: |
| 114 | |
| 115 | RAX, RCX, RDX, RBX, RBP, RSI, RDI, R8-R15, RSP, RIP, CS, DS, ES, FS, GS, SS, |
| 116 | CR0, CR3, CR4, XCR0, EFER, PAT, GDT, IDT, LDTR, TR, DR6, DR7, RFLAGS, X87_FCW, |
| 117 | MXCSR. |
| 118 | |
| 119 | When processing the IGVM file, QEMU will check if any fields other than the |
| 120 | above are non-zero and generate an error if this is the case. |
| 121 | |
| 122 | KVM uses a hardcoded GPA of 0xFFFFFFFFF000 for the VMSA. When an IGVM file |
| 123 | defines initial CPU state, the GPA for each VMSA must match this hardcoded |
| 124 | value. |
| 125 | |
| 126 | Firmware Images with IGVM |
| 127 | ------------------------- |
| 128 | |
| 129 | When an IGVM filename is specified for a Confidential Guest Support object it |
| 130 | overrides the default handling of system firmware: the firmware image, such as |
| 131 | an OVMF binary should be contained as a payload of the IGVM file and not |
| 132 | provided as a flash drive or via the ``-bios`` parameter. The default QEMU |
| 133 | firmware is not automatically populated into the guest memory space. |
| 134 | |
| 135 | If an IGVM file is provided along with either the ``-bios`` parameter or pflash |
| 136 | devices then an error is displayed and the guest startup is aborted. |
| 137 | |
| 138 | Running a guest configured using IGVM |
| 139 | ------------------------------------- |
| 140 | |
| 141 | To run a guest configured with IGVM you firstly need to generate an IGVM file |
| 142 | that contains a guest configuration compatible with the platform you are |
| 143 | targeting. |
| 144 | |
| 145 | The ``buildigvm`` tool [2] is an example of a tool that can be used to generate |
| 146 | IGVM files for non-confidential X86 platforms as well as for SEV, SEV-ES and |
| 147 | SEV-SNP confidential platforms. |
| 148 | |
| 149 | Example using this tool to generate an IGVM file for AMD SEV-SNP:: |
| 150 | |
| 151 | buildigvm --firmware /path/to/OVMF.fd --output sev-snp.igvm \ |
| 152 | --cpucount 4 sev-snp |
| 153 | |
| 154 | To run a guest configured with the generated IGVM you need to add an |
| 155 | ``igvm-cfg`` object and refer to it from the ``-machine`` parameter: |
| 156 | |
| 157 | Example (for AMD SEV):: |
| 158 | |
| 159 | qemu-system-x86_64 \ |
| 160 | <other parameters> \ |
| 161 | -machine ...,confidential-guest-support=sev0,igvm-cfg=igvm0 \ |
| 162 | -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \ |
| 163 | -object igvm-cfg,id=igvm0,file=/path/to/sev-snp.igvm |
| 164 | |
| 165 | References |
| 166 | ---------- |
| 167 | |
| 168 | [1] AMD64 Architecture Programmer's Manual, Volume 2: System Programming |
| 169 | Rev 3.43 |
| 170 | https://docs.amd.com/v/u/en-US/24593_3.43 |
| 171 | |
| 172 | [2] ``buildigvm`` - A tool to build example IGVM files containing OVMF firmware |
| 173 | https://gitlab.com/qemu-project/buildigvm |