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