xref: /openbmc/qemu/docs/specs/tpm.rst (revision 05caa062)
1.. _tpm-device:
2
3===============
4QEMU TPM Device
5===============
6
7Guest-side hardware interface
8=============================
9
10TIS interface
11-------------
12
13The QEMU TPM emulation implements a TPM TIS hardware interface
14following the Trusted Computing Group's specification "TCG PC Client
15Specific TPM Interface Specification (TIS)", Specification Version
161.3, 21 March 2013. (see the `TIS specification`_, or a later version
17of it).
18
19The TIS interface makes a memory mapped IO region in the area
200xfed40000-0xfed44fff available to the guest operating system.
21
22QEMU 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
29Both an ISA device and a sysbus device are available. The former is
30used with pc/q35 machine while the latter can be instantiated in the
31Arm virt machine.
32
33An I2C device support is also provided which can be instantiated in the Arm
34based emulation machines. This device only supports the TPM 2 protocol.
35
36CRB interface
37-------------
38
39QEMU also implements a TPM CRB interface following the Trusted
40Computing Group's specification "TCG PC Client Platform TPM Profile
41(PTP) Specification", Family "2.0", Level 00 Revision 01.03 v22, May
4222, 2017. (see the `CRB specification`_, or a later version of it)
43
44The CRB interface makes a memory mapped IO region in the area
450xfed40000-0xfed40fff (1 locality) available to the guest
46operating system.
47
48QEMU files related to TPM CRB interface:
49 - ``hw/tpm/tpm_crb.c``
50
51SPAPR interface
52---------------
53
54pSeries (ppc64) machines offer a tpm-spapr device model.
55
56QEMU files related to the SPAPR interface:
57 - ``hw/tpm/tpm_spapr.c``
58
59fw_cfg interface
60================
61
62The bios/firmware may read the ``"etc/tpm/config"`` fw_cfg entry for
63configuring the guest appropriately.
64
65The 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
82ACPI interface
83==============
84
85The TPM device is defined with ACPI ID "PNP0C31". QEMU builds a SSDT
86and passes it into the guest through the fw_cfg device. The device
87description contains the base address of the TIS interface 0xfed40000
88and the size of the MMIO area (0x5000). In case a TPM2 is used by
89QEMU, a TPM2 ACPI table is also provided.  The device is described to
90be used in polling mode rather than interrupt mode primarily because
91no unused IRQ could be found.
92
93To support measurement logs to be written by the firmware,
94e.g. SeaBIOS, a TCPA table is implemented. This table provides a 64kb
95buffer where the firmware can write its log into. For TPM 2 only a
96more recent version of the TPM2 table provides support for
97measurements logs and a TCPA table does not need to be created.
98
99The TCPA and TPM2 ACPI tables follow the Trusted Computing Group
100specification "TCG ACPI Specification" Family "1.2" and "2.0", Level
10100 Revision 00.37. (see the `ACPI specification`_, or a later version
102of it)
103
104ACPI PPI Interface
105------------------
106
107QEMU supports the Physical Presence Interface (PPI) for TPM 1.2 and
108TPM 2. This interface requires ACPI and firmware support. (see the
109`PPI specification`_)
110
111PPI enables a system administrator (root) to request a modification to
112the TPM upon reboot. The PPI specification defines the operation
113requests and the actions the firmware has to take. The system
114administrator passes the operation request number to the firmware
115through an ACPI interface which writes this number to a memory
116location that the firmware knows. Upon reboot, the firmware finds the
117number and sends commands to the TPM. The firmware writes the TPM
118result code and the operation request number to a memory location that
119ACPI can read from and pass the result on to the administrator.
120
121The PPI specification defines a set of mandatory and optional
122operations for the firmware to implement. The ACPI interface also
123allows an administrator to list the supported operations. In QEMU the
124ACPI code is generated by QEMU, yet the firmware needs to implement
125support on a per-operations basis, and different firmwares may support
126a different subset. Therefore, QEMU introduces the virtual memory
127device for PPI where the firmware can indicate which operations it
128supports and ACPI can enable the ones that are supported and disable
129all others. This interface lies in main memory and has the following
130layout:
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
168The following values are supported for the ``func`` field. They
169correspond 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
186The location of the table is given by the fw_cfg ``tpmppi_address``
187field.  The PPI memory region size is 0x400 (``TPM_PPI_ADDR_SIZE``) to
188leave enough room for future updates.
189
190QEMU files related to TPM ACPI tables:
191 - ``hw/i386/acpi-build.c``
192 - ``include/hw/acpi/tpm.h``
193
194TPM backend devices
195===================
196
197The TPM implementation is split into two parts, frontend and
198backend. The frontend part is the hardware interface, such as the TPM
199TIS interface described earlier, and the other part is the TPM backend
200interface. The backend interfaces implement the interaction with a TPM
201device, which may be a physical or an emulated device. The split
202between the front- and backend devices allows a frontend to be
203connected with any available backend. This enables the TIS interface
204to be used with the passthrough backend or the swtpm backend.
205
206QEMU files related to TPM backends:
207 - ``backends/tpm.c``
208 - ``include/sysemu/tpm.h``
209 - ``include/sysemu/tpm_backend.h``
210
211The QEMU TPM passthrough device
212-------------------------------
213
214In case QEMU is run on Linux as the host operating system it is
215possible to make the hardware TPM device available to a single QEMU
216guest. In this case the user must make sure that no other program is
217using the device, e.g., /dev/tpm0, before trying to start QEMU with
218it.
219
220The passthrough driver uses the host's TPM device for sending TPM
221commands and receiving responses from. Besides that it accesses the
222TPM device's sysfs entry for support of command cancellation. Since
223none of the state of a hardware TPM can be migrated between hosts,
224virtual machine migration is disabled when the TPM passthrough driver
225is used.
226
227Since the host's TPM device will already be initialized by the host's
228firmware, certain commands, e.g. ``TPM_Startup()``, sent by the
229virtual firmware for device initialization, will fail. In this case
230the firmware should not use the TPM.
231
232Sharing the device with the host is generally not a recommended usage
233scenario for a TPM device. The primary reason for this is that two
234operating systems can then access the device's single set of
235resources, such as platform configuration registers
236(PCRs). Applications or kernel security subsystems, such as the Linux
237Integrity Measurement Architecture (IMA), are not expecting to share
238PCRs.
239
240QEMU 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
246Command line to start QEMU with the TPM passthrough device using the host's
247hardware 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
257The following commands should result in similar output inside the VM
258with a Linux kernel that either has the TPM TIS driver built-in or
259available 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
279The QEMU TPM emulator device
280----------------------------
281
282The TPM emulator device uses an external TPM emulator called 'swtpm'
283for sending TPM commands to and receiving responses from. The swtpm
284program must have been started before trying to access it through the
285TPM emulator with QEMU.
286
287The TPM emulator implements a command channel for transferring TPM
288commands and responses as well as a control channel over which control
289commands can be sent. (see the `SWTPM protocol`_ specification)
290
291The control channel serves the purpose of resetting, initializing, and
292migrating the TPM state, among other things.
293
294The swtpm program behaves like a hardware TPM and therefore needs to
295be initialized by the firmware running inside the QEMU virtual
296machine.  One necessary step for initializing the device is to send
297the TPM_Startup command to it. SeaBIOS, for example, has been
298instrumented to initialize a TPM 1.2 or TPM 2 device using this
299command.
300
301QEMU 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
306The following commands start the swtpm with a UnixIO control channel over
307a 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
317Command line to start QEMU with the TPM emulator device communicating
318with 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
328In 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,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
342In 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
357In case a ast2600-evb bmc machine is emulated and you want to use a TPM device
358attached 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
374In case SeaBIOS is used as firmware, it should show the TPM menu item
375after 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
386The following commands should result in similar output inside the VM
387with a Linux kernel that either has the TPM TIS driver built-in or
388available 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
408Migration with the TPM emulator
409===============================
410
411The TPM emulator supports the following types of virtual machine
412migration:
413
414- VM save / restore (migration into a file)
415- Network migration
416- Snapshotting (migration into storage like QoW2 or QED)
417
418The following command sequences can be used to test VM save / restore.
419
420In 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
430In 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
442Verify that the attached TPM is working as expected using applications
443inside the VM.
444
445To store the state of the VM use the following command in the QEMU
446monitor in the 2nd terminal:
447
448.. code-block:: console
449
450  (qemu) migrate "exec:cat > testvm.bin"
451  (qemu) quit
452
453At this point a file called ``testvm.bin`` should exists and the swtpm
454and QEMU processes should have ended.
455
456To test 'VM restore' you have to start the swtpm with the same
457parameters as before. If previously a TPM 2 [--tpm2] was saved, --tpm2
458must now be passed again on the command line.
459
460In the 1st terminal restart the swtpm with the same command line as
461before:
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
469In 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
482Troubleshooting migration
483-------------------------
484
485There are several reasons why migration may fail. In case of problems,
486please ensure that the command lines adhere to the following rules
487and, if possible, that identical versions of QEMU and swtpm are used
488at all times.
489
490VM 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
497VM 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
507VM 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
514VM Snapshotting:
515 - QEMU command line parameters should be identical
516
517 - swtpm command line parameters should be identical
518
519
520Besides that, migration failure reasons on the swtpm level may include
521the 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
552