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