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.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_backend.h``
 203  - ``include/sysemu/tpm_backend_int.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  - ``hw/tpm/tpm_passthrough.c``
 236  - ``hw/tpm/tpm_util.c``
 237  - ``hw/tpm/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:
 254
 255 .. code-block:: console
 256
 257   # dmesg | grep -i tpm
 258   [    0.711310] tpm_tis 00:06: 1.2 TPM (device=id 0x1, rev-id 1)
 259
 260   # dmesg | grep TCPA
 261   [    0.000000] ACPI: TCPA 0x0000000003FFD191C 000032 (v02 BOCHS  \
 262       BXPCTCPA 0000001 BXPC 00000001)
 263
 264   # ls -l /dev/tpm*
 265   crw-------. 1 root root 10, 224 Jul 11 10:11 /dev/tpm0
 266
 267   # find /sys/devices/ | grep pcrs$ | xargs cat
 268   PCR-00: 35 4E 3B CE 23 9F 38 59 ...
 269   ...
 270   PCR-23: 00 00 00 00 00 00 00 00 ...
 271
 272 The QEMU TPM emulator device
 273 ----------------------------
 274
 275 The TPM emulator device uses an external TPM emulator called 'swtpm'
 276 for sending TPM commands to and receiving responses from. The swtpm
 277 program must have been started before trying to access it through the
 278 TPM emulator with QEMU.
 279
 280 The TPM emulator implements a command channel for transferring TPM
 281 commands and responses as well as a control channel over which control
 282 commands can be sent. (see the `SWTPM protocol`_ specification)
 283
 284 The control channel serves the purpose of resetting, initializing, and
 285 migrating the TPM state, among other things.
 286
 287 The swtpm program behaves like a hardware TPM and therefore needs to
 288 be initialized by the firmware running inside the QEMU virtual
 289 machine.  One necessary step for initializing the device is to send
 290 the TPM_Startup command to it. SeaBIOS, for example, has been
 291 instrumented to initialize a TPM 1.2 or TPM 2 device using this
 292 command.
 293
 294 QEMU files related to the TPM emulator device:
 295  - ``hw/tpm/tpm_emulator.c``
 296  - ``hw/tpm/tpm_util.c``
 297  - ``hw/tpm/tpm_util.h``
 298
 299 The following commands start the swtpm with a UnixIO control channel over
 300 a socket interface. They do not need to be run as root.
 301
 302 .. code-block:: console
 303
 304   mkdir /tmp/mytpm1
 305   swtpm socket --tpmstate dir=/tmp/mytpm1 \
 306     --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \
 307     --log level=20
 308
 309 Command line to start QEMU with the TPM emulator device communicating
 310 with the swtpm (x86):
 311
 312 .. code-block:: console
 313
 314   qemu-system-x86_64 -display sdl -accel kvm \
 315     -m 1024 -boot d -bios bios-256k.bin -boot menu=on \
 316     -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \
 317     -tpmdev emulator,id=tpm0,chardev=chrtpm \
 318     -device tpm-tis,tpmdev=tpm0 test.img
 319
 320 In case a pSeries machine is emulated, use the following command line:
 321
 322 .. code-block:: console
 323
 324   qemu-system-ppc64 -display sdl -machine pseries,accel=kvm \
 325     -m 1024 -bios slof.bin -boot menu=on \
 326     -nodefaults -device VGA -device pci-ohci -device usb-kbd \
 327     -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \
 328     -tpmdev emulator,id=tpm0,chardev=chrtpm \
 329     -device tpm-spapr,tpmdev=tpm0 \
 330     -device spapr-vscsi,id=scsi0,reg=0x00002000 \
 331     -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x3,drive=drive-virtio-disk0,id=virtio-disk0 \
 332     -drive file=test.img,format=raw,if=none,id=drive-virtio-disk0
 333
 334 In case an Arm virt machine is emulated, use the following command line:
 335
 336 .. code-block:: console
 337
 338   qemu-system-aarch64 -machine virt,gic-version=3,accel=kvm \
 339     -cpu host -m 4G \
 340     -nographic -no-acpi \
 341     -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \
 342     -tpmdev emulator,id=tpm0,chardev=chrtpm \
 343     -device tpm-tis-device,tpmdev=tpm0 \
 344     -device virtio-blk-pci,drive=drv0 \
 345     -drive format=qcow2,file=hda.qcow2,if=none,id=drv0 \
 346     -drive if=pflash,format=raw,file=flash0.img,readonly \
 347     -drive if=pflash,format=raw,file=flash1.img
 348
 349   On Arm, ACPI boot with TPM is not yet supported.
 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.711310] tpm_tis 00:06: 1.2 TPM (device=id 0x1, rev-id 1)
 371
 372   # dmesg | grep TCPA
 373   [    0.000000] ACPI: TCPA 0x0000000003FFD191C 000032 (v02 BOCHS  \
 374       BXPCTCPA 0000001 BXPC 00000001)
 375
 376   # ls -l /dev/tpm*
 377   crw-------. 1 root root 10, 224 Jul 11 10:11 /dev/tpm0
 378
 379   # find /sys/devices/ | grep pcrs$ | xargs cat
 380   PCR-00: 35 4E 3B CE 23 9F 38 59 ...
 381   ...
 382   PCR-23: 00 00 00 00 00 00 00 00 ...
 383
 384 Migration with the TPM emulator
 385 ===============================
 386
 387 The TPM emulator supports the following types of virtual machine
 388 migration:
 389
 390 - VM save / restore (migration into a file)
 391 - Network migration
 392 - Snapshotting (migration into storage like QoW2 or QED)
 393
 394 The following command sequences can be used to test VM save / restore.
 395
 396 In a 1st terminal start an instance of a swtpm using the following command:
 397
 398 .. code-block:: console
 399
 400   mkdir /tmp/mytpm1
 401   swtpm socket --tpmstate dir=/tmp/mytpm1 \
 402     --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \
 403     --log level=20 --tpm2
 404
 405 In a 2nd terminal start the VM:
 406
 407 .. code-block:: console
 408
 409   qemu-system-x86_64 -display sdl -accel kvm \
 410     -m 1024 -boot d -bios bios-256k.bin -boot menu=on \
 411     -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \
 412     -tpmdev emulator,id=tpm0,chardev=chrtpm \
 413     -device tpm-tis,tpmdev=tpm0 \
 414     -monitor stdio \
 415     test.img
 416
 417 Verify that the attached TPM is working as expected using applications
 418 inside the VM.
 419
 420 To store the state of the VM use the following command in the QEMU
 421 monitor in the 2nd terminal:
 422
 423 .. code-block:: console
 424
 425   (qemu) migrate "exec:cat > testvm.bin"
 426   (qemu) quit
 427
 428 At this point a file called ``testvm.bin`` should exists and the swtpm
 429 and QEMU processes should have ended.
 430
 431 To test 'VM restore' you have to start the swtpm with the same
 432 parameters as before. If previously a TPM 2 [--tpm2] was saved, --tpm2
 433 must now be passed again on the command line.
 434
 435 In the 1st terminal restart the swtpm with the same command line as
 436 before:
 437
 438 .. code-block:: console
 439
 440   swtpm socket --tpmstate dir=/tmp/mytpm1 \
 441     --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \
 442     --log level=20 --tpm2
 443
 444 In the 2nd terminal restore the state of the VM using the additional
 445 '-incoming' option.
 446
 447 .. code-block:: console
 448
 449   qemu-system-x86_64 -display sdl -accel kvm \
 450     -m 1024 -boot d -bios bios-256k.bin -boot menu=on \
 451     -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \
 452     -tpmdev emulator,id=tpm0,chardev=chrtpm \
 453     -device tpm-tis,tpmdev=tpm0 \
 454     -incoming "exec:cat < testvm.bin" \
 455     test.img
 456
 457 Troubleshooting migration
 458 -------------------------
 459
 460 There are several reasons why migration may fail. In case of problems,
 461 please ensure that the command lines adhere to the following rules
 462 and, if possible, that identical versions of QEMU and swtpm are used
 463 at all times.
 464
 465 VM save and restore:
 466
 467  - QEMU command line parameters should be identical apart from the
 468    '-incoming' option on VM restore
 469
 470  - swtpm command line parameters should be identical
 471
 472 VM migration to 'localhost':
 473
 474  - QEMU command line parameters should be identical apart from the
 475    '-incoming' option on the destination side
 476
 477  - swtpm command line parameters should point to two different
 478    directories on the source and destination swtpm (--tpmstate dir=...)
 479    (especially if different versions of libtpms were to be used on the
 480    same machine).
 481
 482 VM migration across the network:
 483
 484  - QEMU command line parameters should be identical apart from the
 485    '-incoming' option on the destination side
 486
 487  - swtpm command line parameters should be identical
 488
 489 VM Snapshotting:
 490  - QEMU command line parameters should be identical
 491
 492  - swtpm command line parameters should be identical
 493
 494
 495 Besides that, migration failure reasons on the swtpm level may include
 496 the following:
 497
 498  - the versions of the swtpm on the source and destination sides are
 499    incompatible
 500
 501    - downgrading of TPM state may not be supported
 502
 503    - the source and destination libtpms were compiled with different
 504      compile-time options and the destination side refuses to accept the
 505      state
 506
 507  - different migration keys are used on the source and destination side
 508    and the destination side cannot decrypt the migrated state
 509    (swtpm ... --migration-key ... )
 510
 511
 512 .. _TIS specification:
 513    https://trustedcomputinggroup.org/pc-client-work-group-pc-client-specific-tpm-interface-specification-tis/
 514
 515 .. _CRB specification:
 516    https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/
 517
 518
 519 .. _ACPI specification:
 520    https://trustedcomputinggroup.org/tcg-acpi-specification/
 521
 522 .. _PPI specification:
 523    https://trustedcomputinggroup.org/resource/tcg-physical-presence-interface-specification/
 524
 525 .. _SWTPM protocol:
 526    https://github.com/stefanberger/swtpm/blob/master/man/man3/swtpm_ioctls.pod