docs/specs/tpm.rst

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