docs/specs/tpm.rst

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