tpm.rst (20427B)
1 =============== 2 QEMU TPM Device 3 =============== 4 5 Guest-side hardware interface 6 ============================= 7 8 TIS interface 9 ------------- 10 11 The QEMU TPM emulation implements a TPM TIS hardware interface 12 following the Trusted Computing Group's specification "TCG PC Client 13 Specific TPM Interface Specification (TIS)", Specification Version 14 1.3, 21 March 2013. (see the `TIS specification`_, or a later version 15 of it). 16 17 The TIS interface makes a memory mapped IO region in the area 18 0xfed40000-0xfed44fff available to the guest operating system. 19 20 QEMU files related to TPM TIS interface: 21 - ``hw/tpm/tpm_tis_common.c`` 22 - ``hw/tpm/tpm_tis_isa.c`` 23 - ``hw/tpm/tpm_tis_sysbus.c`` 24 - ``hw/tpm/tpm_tis.h`` 25 26 Both an ISA device and a sysbus device are available. The former is 27 used with pc/q35 machine while the latter can be instantiated in the 28 Arm virt machine. 29 30 CRB interface 31 ------------- 32 33 QEMU also implements a TPM CRB interface following the Trusted 34 Computing Group's specification "TCG PC Client Platform TPM Profile 35 (PTP) Specification", Family "2.0", Level 00 Revision 01.03 v22, May 36 22, 2017. (see the `CRB specification`_, or a later version of it) 37 38 The CRB interface makes a memory mapped IO region in the area 39 0xfed40000-0xfed40fff (1 locality) available to the guest 40 operating system. 41 42 QEMU files related to TPM CRB interface: 43 - ``hw/tpm/tpm_crb.c`` 44 45 SPAPR interface 46 --------------- 47 48 pSeries (ppc64) machines offer a tpm-spapr device model. 49 50 QEMU files related to the SPAPR interface: 51 - ``hw/tpm/tpm_spapr.c`` 52 53 fw_cfg interface 54 ================ 55 56 The bios/firmware may read the ``"etc/tpm/config"`` fw_cfg entry for 57 configuring the guest appropriately. 58 59 The entry of 6 bytes has the following content, in little-endian: 60 61 .. code-block:: c 62 63 #define TPM_VERSION_UNSPEC 0 64 #define TPM_VERSION_1_2 1 65 #define TPM_VERSION_2_0 2 66 67 #define TPM_PPI_VERSION_NONE 0 68 #define TPM_PPI_VERSION_1_30 1 69 70 struct FwCfgTPMConfig { 71 uint32_t tpmppi_address; /* PPI memory location */ 72 uint8_t tpm_version; /* TPM version */ 73 uint8_t tpmppi_version; /* PPI version */ 74 }; 75 76 ACPI interface 77 ============== 78 79 The TPM device is defined with ACPI ID "PNP0C31". QEMU builds a SSDT 80 and passes it into the guest through the fw_cfg device. The device 81 description contains the base address of the TIS interface 0xfed40000 82 and the size of the MMIO area (0x5000). In case a TPM2 is used by 83 QEMU, a TPM2 ACPI table is also provided. The device is described to 84 be used in polling mode rather than interrupt mode primarily because 85 no unused IRQ could be found. 86 87 To support measurement logs to be written by the firmware, 88 e.g. SeaBIOS, a TCPA table is implemented. This table provides a 64kb 89 buffer where the firmware can write its log into. For TPM 2 only a 90 more recent version of the TPM2 table provides support for 91 measurements logs and a TCPA table does not need to be created. 92 93 The TCPA and TPM2 ACPI tables follow the Trusted Computing Group 94 specification "TCG ACPI Specification" Family "1.2" and "2.0", Level 95 00 Revision 00.37. (see the `ACPI specification`_, or a later version 96 of it) 97 98 ACPI PPI Interface 99 ------------------ 100 101 QEMU supports the Physical Presence Interface (PPI) for TPM 1.2 and 102 TPM 2. This interface requires ACPI and firmware support. (see the 103 `PPI specification`_) 104 105 PPI enables a system administrator (root) to request a modification to 106 the TPM upon reboot. The PPI specification defines the operation 107 requests and the actions the firmware has to take. The system 108 administrator passes the operation request number to the firmware 109 through an ACPI interface which writes this number to a memory 110 location that the firmware knows. Upon reboot, the firmware finds the 111 number and sends commands to the TPM. The firmware writes the TPM 112 result code and the operation request number to a memory location that 113 ACPI can read from and pass the result on to the administrator. 114 115 The PPI specification defines a set of mandatory and optional 116 operations for the firmware to implement. The ACPI interface also 117 allows an administrator to list the supported operations. In QEMU the 118 ACPI code is generated by QEMU, yet the firmware needs to implement 119 support on a per-operations basis, and different firmwares may support 120 a different subset. Therefore, QEMU introduces the virtual memory 121 device for PPI where the firmware can indicate which operations it 122 supports and ACPI can enable the ones that are supported and disable 123 all others. This interface lies in main memory and has the following 124 layout: 125 126 +-------------+--------+--------+-------------------------------------------+ 127 | Field | Length | Offset | Description | 128 +=============+========+========+===========================================+ 129 | ``func`` | 0x100 | 0x000 | Firmware sets values for each supported | 130 | | | | operation. See defined values below. | 131 +-------------+--------+--------+-------------------------------------------+ 132 | ``ppin`` | 0x1 | 0x100 | SMI interrupt to use. Set by firmware. | 133 | | | | Not supported. | 134 +-------------+--------+--------+-------------------------------------------+ 135 | ``ppip`` | 0x4 | 0x101 | ACPI function index to pass to SMM code. | 136 | | | | Set by ACPI. Not supported. | 137 +-------------+--------+--------+-------------------------------------------+ 138 | ``pprp`` | 0x4 | 0x105 | Result of last executed operation. Set by | 139 | | | | firmware. See function index 5 for values.| 140 +-------------+--------+--------+-------------------------------------------+ 141 | ``pprq`` | 0x4 | 0x109 | Operation request number to execute. See | 142 | | | | 'Physical Presence Interface Operation | 143 | | | | Summary' tables in specs. Set by ACPI. | 144 +-------------+--------+--------+-------------------------------------------+ 145 | ``pprm`` | 0x4 | 0x10d | Operation request optional parameter. | 146 | | | | Values depend on operation. Set by ACPI. | 147 +-------------+--------+--------+-------------------------------------------+ 148 | ``lppr`` | 0x4 | 0x111 | Last executed operation request number. | 149 | | | | Copied from pprq field by firmware. | 150 +-------------+--------+--------+-------------------------------------------+ 151 | ``fret`` | 0x4 | 0x115 | Result code from SMM function. | 152 | | | | Not supported. | 153 +-------------+--------+--------+-------------------------------------------+ 154 | ``res1`` | 0x40 | 0x119 | Reserved for future use | 155 +-------------+--------+--------+-------------------------------------------+ 156 |``next_step``| 0x1 | 0x159 | Operation to execute after reboot by | 157 | | | | firmware. Used by firmware. | 158 +-------------+--------+--------+-------------------------------------------+ 159 | ``movv`` | 0x1 | 0x15a | Memory overwrite variable | 160 +-------------+--------+--------+-------------------------------------------+ 161 162 The following values are supported for the ``func`` field. They 163 correspond to the values used by ACPI function index 8. 164 165 +----------+-------------------------------------------------------------+ 166 | Value | Description | 167 +==========+=============================================================+ 168 | 0 | Operation is not implemented. | 169 +----------+-------------------------------------------------------------+ 170 | 1 | Operation is only accessible through firmware. | 171 +----------+-------------------------------------------------------------+ 172 | 2 | Operation is blocked for OS by firmware configuration. | 173 +----------+-------------------------------------------------------------+ 174 | 3 | Operation is allowed and physically present user required. | 175 +----------+-------------------------------------------------------------+ 176 | 4 | Operation is allowed and physically present user is not | 177 | | required. | 178 +----------+-------------------------------------------------------------+ 179 180 The location of the table is given by the fw_cfg ``tpmppi_address`` 181 field. The PPI memory region size is 0x400 (``TPM_PPI_ADDR_SIZE``) to 182 leave enough room for future updates. 183 184 QEMU files related to TPM ACPI tables: 185 - ``hw/i386/acpi-build.c`` 186 - ``include/hw/acpi/tpm.h`` 187 188 TPM backend devices 189 =================== 190 191 The TPM implementation is split into two parts, frontend and 192 backend. The frontend part is the hardware interface, such as the TPM 193 TIS interface described earlier, and the other part is the TPM backend 194 interface. The backend interfaces implement the interaction with a TPM 195 device, which may be a physical or an emulated device. The split 196 between the front- and backend devices allows a frontend to be 197 connected with any available backend. This enables the TIS interface 198 to be used with the passthrough backend or the swtpm backend. 199 200 QEMU files related to TPM backends: 201 - ``backends/tpm.c`` 202 - ``include/sysemu/tpm.h`` 203 - ``include/sysemu/tpm_backend.h`` 204 205 The QEMU TPM passthrough device 206 ------------------------------- 207 208 In case QEMU is run on Linux as the host operating system it is 209 possible to make the hardware TPM device available to a single QEMU 210 guest. In this case the user must make sure that no other program is 211 using the device, e.g., /dev/tpm0, before trying to start QEMU with 212 it. 213 214 The passthrough driver uses the host's TPM device for sending TPM 215 commands and receiving responses from. Besides that it accesses the 216 TPM device's sysfs entry for support of command cancellation. Since 217 none of the state of a hardware TPM can be migrated between hosts, 218 virtual machine migration is disabled when the TPM passthrough driver 219 is used. 220 221 Since the host's TPM device will already be initialized by the host's 222 firmware, certain commands, e.g. ``TPM_Startup()``, sent by the 223 virtual firmware for device initialization, will fail. In this case 224 the firmware should not use the TPM. 225 226 Sharing the device with the host is generally not a recommended usage 227 scenario for a TPM device. The primary reason for this is that two 228 operating systems can then access the device's single set of 229 resources, such as platform configuration registers 230 (PCRs). Applications or kernel security subsystems, such as the Linux 231 Integrity Measurement Architecture (IMA), are not expecting to share 232 PCRs. 233 234 QEMU files related to the TPM passthrough device: 235 - ``backends/tpm/tpm_passthrough.c`` 236 - ``backends/tpm/tpm_util.c`` 237 - ``include/sysemu/tpm_util.h`` 238 239 240 Command line to start QEMU with the TPM passthrough device using the host's 241 hardware TPM ``/dev/tpm0``: 242 243 .. code-block:: console 244 245 qemu-system-x86_64 -display sdl -accel kvm \ 246 -m 1024 -boot d -bios bios-256k.bin -boot menu=on \ 247 -tpmdev passthrough,id=tpm0,path=/dev/tpm0 \ 248 -device tpm-tis,tpmdev=tpm0 test.img 249 250 251 The following commands should result in similar output inside the VM 252 with a Linux kernel that either has the TPM TIS driver built-in or 253 available as a module (assuming a TPM 2 is passed through): 254 255 .. code-block:: console 256 257 # dmesg | grep -i tpm 258 [ 0.012560] ACPI: TPM2 0x000000000BFFD1900 00004C (v04 BOCHS \ 259 BXPC 0000001 BXPC 00000001) 260 261 # ls -l /dev/tpm* 262 crw-rw----. 1 tss root 10, 224 Sep 6 12:36 /dev/tpm0 263 crw-rw----. 1 tss rss 253, 65536 Sep 6 12:36 /dev/tpmrm0 264 265 Starting with Linux 5.12 there are PCR entries for TPM 2 in sysfs: 266 # find /sys/devices/ -type f | grep pcr-sha 267 ... 268 /sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/1 269 ... 270 /sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/9 271 ... 272 273 The QEMU TPM emulator device 274 ---------------------------- 275 276 The TPM emulator device uses an external TPM emulator called 'swtpm' 277 for sending TPM commands to and receiving responses from. The swtpm 278 program must have been started before trying to access it through the 279 TPM emulator with QEMU. 280 281 The TPM emulator implements a command channel for transferring TPM 282 commands and responses as well as a control channel over which control 283 commands can be sent. (see the `SWTPM protocol`_ specification) 284 285 The control channel serves the purpose of resetting, initializing, and 286 migrating the TPM state, among other things. 287 288 The swtpm program behaves like a hardware TPM and therefore needs to 289 be initialized by the firmware running inside the QEMU virtual 290 machine. One necessary step for initializing the device is to send 291 the TPM_Startup command to it. SeaBIOS, for example, has been 292 instrumented to initialize a TPM 1.2 or TPM 2 device using this 293 command. 294 295 QEMU files related to the TPM emulator device: 296 - ``backends/tpm/tpm_emulator.c`` 297 - ``backends/tpm/tpm_util.c`` 298 - ``include/sysemu/tpm_util.h`` 299 300 The following commands start the swtpm with a UnixIO control channel over 301 a socket interface. They do not need to be run as root. 302 303 .. code-block:: console 304 305 mkdir /tmp/mytpm1 306 swtpm socket --tpmstate dir=/tmp/mytpm1 \ 307 --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \ 308 --tpm2 \ 309 --log level=20 310 311 Command line to start QEMU with the TPM emulator device communicating 312 with the swtpm (x86): 313 314 .. code-block:: console 315 316 qemu-system-x86_64 -display sdl -accel kvm \ 317 -m 1024 -boot d -bios bios-256k.bin -boot menu=on \ 318 -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ 319 -tpmdev emulator,id=tpm0,chardev=chrtpm \ 320 -device tpm-tis,tpmdev=tpm0 test.img 321 322 In case a pSeries machine is emulated, use the following command line: 323 324 .. code-block:: console 325 326 qemu-system-ppc64 -display sdl -machine pseries,accel=kvm \ 327 -m 1024 -bios slof.bin -boot menu=on \ 328 -nodefaults -device VGA -device pci-ohci -device usb-kbd \ 329 -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ 330 -tpmdev emulator,id=tpm0,chardev=chrtpm \ 331 -device tpm-spapr,tpmdev=tpm0 \ 332 -device spapr-vscsi,id=scsi0,reg=0x00002000 \ 333 -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x3,drive=drive-virtio-disk0,id=virtio-disk0 \ 334 -drive file=test.img,format=raw,if=none,id=drive-virtio-disk0 335 336 In case an Arm virt machine is emulated, use the following command line: 337 338 .. code-block:: console 339 340 qemu-system-aarch64 -machine virt,gic-version=3,accel=kvm \ 341 -cpu host -m 4G \ 342 -nographic -no-acpi \ 343 -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ 344 -tpmdev emulator,id=tpm0,chardev=chrtpm \ 345 -device tpm-tis-device,tpmdev=tpm0 \ 346 -device virtio-blk-pci,drive=drv0 \ 347 -drive format=qcow2,file=hda.qcow2,if=none,id=drv0 \ 348 -drive if=pflash,format=raw,file=flash0.img,readonly=on \ 349 -drive if=pflash,format=raw,file=flash1.img 350 351 In case SeaBIOS is used as firmware, it should show the TPM menu item 352 after entering the menu with 'ESC'. 353 354 .. code-block:: console 355 356 Select boot device: 357 1. DVD/CD [ata1-0: QEMU DVD-ROM ATAPI-4 DVD/CD] 358 [...] 359 5. Legacy option rom 360 361 t. TPM Configuration 362 363 The following commands should result in similar output inside the VM 364 with a Linux kernel that either has the TPM TIS driver built-in or 365 available as a module: 366 367 .. code-block:: console 368 369 # dmesg | grep -i tpm 370 [ 0.012560] ACPI: TPM2 0x000000000BFFD1900 00004C (v04 BOCHS \ 371 BXPC 0000001 BXPC 00000001) 372 373 # ls -l /dev/tpm* 374 crw-rw----. 1 tss root 10, 224 Sep 6 12:36 /dev/tpm0 375 crw-rw----. 1 tss rss 253, 65536 Sep 6 12:36 /dev/tpmrm0 376 377 Starting with Linux 5.12 there are PCR entries for TPM 2 in sysfs: 378 # find /sys/devices/ -type f | grep pcr-sha 379 ... 380 /sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/1 381 ... 382 /sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/9 383 ... 384 385 Migration with the TPM emulator 386 =============================== 387 388 The TPM emulator supports the following types of virtual machine 389 migration: 390 391 - VM save / restore (migration into a file) 392 - Network migration 393 - Snapshotting (migration into storage like QoW2 or QED) 394 395 The following command sequences can be used to test VM save / restore. 396 397 In a 1st terminal start an instance of a swtpm using the following command: 398 399 .. code-block:: console 400 401 mkdir /tmp/mytpm1 402 swtpm socket --tpmstate dir=/tmp/mytpm1 \ 403 --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \ 404 --tpm2 \ 405 --log level=20 406 407 In a 2nd terminal start the VM: 408 409 .. code-block:: console 410 411 qemu-system-x86_64 -display sdl -accel kvm \ 412 -m 1024 -boot d -bios bios-256k.bin -boot menu=on \ 413 -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ 414 -tpmdev emulator,id=tpm0,chardev=chrtpm \ 415 -device tpm-tis,tpmdev=tpm0 \ 416 -monitor stdio \ 417 test.img 418 419 Verify that the attached TPM is working as expected using applications 420 inside the VM. 421 422 To store the state of the VM use the following command in the QEMU 423 monitor in the 2nd terminal: 424 425 .. code-block:: console 426 427 (qemu) migrate "exec:cat > testvm.bin" 428 (qemu) quit 429 430 At this point a file called ``testvm.bin`` should exists and the swtpm 431 and QEMU processes should have ended. 432 433 To test 'VM restore' you have to start the swtpm with the same 434 parameters as before. If previously a TPM 2 [--tpm2] was saved, --tpm2 435 must now be passed again on the command line. 436 437 In the 1st terminal restart the swtpm with the same command line as 438 before: 439 440 .. code-block:: console 441 442 swtpm socket --tpmstate dir=/tmp/mytpm1 \ 443 --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \ 444 --log level=20 --tpm2 445 446 In the 2nd terminal restore the state of the VM using the additional 447 '-incoming' option. 448 449 .. code-block:: console 450 451 qemu-system-x86_64 -display sdl -accel kvm \ 452 -m 1024 -boot d -bios bios-256k.bin -boot menu=on \ 453 -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ 454 -tpmdev emulator,id=tpm0,chardev=chrtpm \ 455 -device tpm-tis,tpmdev=tpm0 \ 456 -incoming "exec:cat < testvm.bin" \ 457 test.img 458 459 Troubleshooting migration 460 ------------------------- 461 462 There are several reasons why migration may fail. In case of problems, 463 please ensure that the command lines adhere to the following rules 464 and, if possible, that identical versions of QEMU and swtpm are used 465 at all times. 466 467 VM save and restore: 468 469 - QEMU command line parameters should be identical apart from the 470 '-incoming' option on VM restore 471 472 - swtpm command line parameters should be identical 473 474 VM migration to 'localhost': 475 476 - QEMU command line parameters should be identical apart from the 477 '-incoming' option on the destination side 478 479 - swtpm command line parameters should point to two different 480 directories on the source and destination swtpm (--tpmstate dir=...) 481 (especially if different versions of libtpms were to be used on the 482 same machine). 483 484 VM migration across the network: 485 486 - QEMU command line parameters should be identical apart from the 487 '-incoming' option on the destination side 488 489 - swtpm command line parameters should be identical 490 491 VM Snapshotting: 492 - QEMU command line parameters should be identical 493 494 - swtpm command line parameters should be identical 495 496 497 Besides that, migration failure reasons on the swtpm level may include 498 the following: 499 500 - the versions of the swtpm on the source and destination sides are 501 incompatible 502 503 - downgrading of TPM state may not be supported 504 505 - the source and destination libtpms were compiled with different 506 compile-time options and the destination side refuses to accept the 507 state 508 509 - different migration keys are used on the source and destination side 510 and the destination side cannot decrypt the migrated state 511 (swtpm ... --migration-key ... ) 512 513 514 .. _TIS specification: 515 https://trustedcomputinggroup.org/pc-client-work-group-pc-client-specific-tpm-interface-specification-tis/ 516 517 .. _CRB specification: 518 https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/ 519 520 521 .. _ACPI specification: 522 https://trustedcomputinggroup.org/tcg-acpi-specification/ 523 524 .. _PPI specification: 525 https://trustedcomputinggroup.org/resource/tcg-physical-presence-interface-specification/ 526 527 .. _SWTPM protocol: 528 https://github.com/stefanberger/swtpm/blob/master/man/man3/swtpm_ioctls.pod