[v2] specs: Describe the TPM support in QEMU

Commit Message

Stefan Berger July 11, 2017, 2:31 p.m. UTC

This patch adds a description of the current TPM support in QEMU
to the specs.

Several public specs are referenced via their landing page on the
trustedcomputinggroup.org website.

Signed-off-by: Stefan Berger <[e-mail]>

---

v1->v2:
  - fixed typos
  - added command line for starting an x86_64 VM with TPM passthrough device
  - added command lines for checks inside the VM
---
 docs/specs/tpm.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 docs/specs/tpm.txt

Comments

Laszlo Ersek July 11, 2017, 7:36 p.m. UTC | #1

On 07/11/17 16:31, Stefan Berger wrote:
> This patch adds a description of the current TPM support in QEMU
> to the specs.
> 
> Several public specs are referenced via their landing page on the
> trustedcomputinggroup.org website.
> 
> Signed-off-by: Stefan Berger <[e-mail]>
> 
> ---
> 
> v1->v2:
>   - fixed typos
>   - added command line for starting an x86_64 VM with TPM passthrough device
>   - added command lines for checks inside the VM
> ---
>  docs/specs/tpm.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 124 insertions(+)
>  create mode 100644 docs/specs/tpm.txt

Awesome, thank you very much!

I think I noticed one typo in new text:

> +#> dmesg | grep TCPA
> +[    0.000000] ACPI: TCP 0x0000000003FFD191C 000032 (v02 BOCHS  \
> +    BXPCTCPA 0000001 BXPC 00000001)

I think the prefix here should be "ACPI: TCPA"; the letter "A" probably
fell victim to wrapping the line nicely.

Not sure which maintainer will pick up the patch, but I think they can
fix up this typo on their end (assuming no other reviewer asks for v3).

Reviewed-by: Laszlo Ersek <[e-mail]>

Thank you again, Stefan!
Laszlo

Stefan Berger July 11, 2017, 8:48 p.m. UTC | #2

On 07/11/2017 03:36 PM, Laszlo Ersek wrote:
> On 07/11/17 16:31, Stefan Berger wrote:
>> This patch adds a description of the current TPM support in QEMU
>> to the specs.
>>
>> Several public specs are referenced via their landing page on the
>> trustedcomputinggroup.org website.
>>
>> Signed-off-by: Stefan Berger <[e-mail]>
>>
>> ---
>>
>> v1->v2:
>>    - fixed typos
>>    - added command line for starting an x86_64 VM with TPM passthrough device
>>    - added command lines for checks inside the VM
>> ---
>>   docs/specs/tpm.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 124 insertions(+)
>>   create mode 100644 docs/specs/tpm.txt
> Awesome, thank you very much!
>
> I think I noticed one typo in new text:
>
>> +#> dmesg | grep TCPA
>> +[    0.000000] ACPI: TCP 0x0000000003FFD191C 000032 (v02 BOCHS  \
>> +    BXPCTCPA 0000001 BXPC 00000001)
> I think the prefix here should be "ACPI: TCPA"; the letter "A" probably
> fell victim to wrapping the line nicely.
My bad. I copied from the VM by typing it, which is error prone. :-)

    Stefan

Javier Martinez Canillas Aug. 16, 2017, 8:33 a.m. UTC | #3

On 07/11/2017 09:36 PM, Laszlo Ersek wrote:
> On 07/11/17 16:31, Stefan Berger wrote:
>> This patch adds a description of the current TPM support in QEMU
>> to the specs.
>>
>> Several public specs are referenced via their landing page on the
>> trustedcomputinggroup.org website.
>>
>> Signed-off-by: Stefan Berger <[e-mail]>
>>
>> ---
>>
>> v1->v2:
>>   - fixed typos
>>   - added command line for starting an x86_64 VM with TPM passthrough device
>>   - added command lines for checks inside the VM
>> ---
>>  docs/specs/tpm.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 124 insertions(+)
>>  create mode 100644 docs/specs/tpm.txt
> 
> Awesome, thank you very much!
> 
> I think I noticed one typo in new text:
> 
>> +#> dmesg | grep TCPA
>> +[    0.000000] ACPI: TCP 0x0000000003FFD191C 000032 (v02 BOCHS  \
>> +    BXPCTCPA 0000001 BXPC 00000001)
> 
> I think the prefix here should be "ACPI: TCPA"; the letter "A" probably
> fell victim to wrapping the line nicely.
> 
> Not sure which maintainer will pick up the patch, but I think they can
> fix up this typo on their end (assuming no other reviewer asks for v3).
> 
> Reviewed-by: Laszlo Ersek <[e-mail]>
> 

It seems this patch was never picked.

Best regards,

Laszlo Ersek Aug. 16, 2017, 9:03 a.m. UTC | #4

On 08/16/17 10:33, Javier Martinez Canillas wrote:
> On 07/11/2017 09:36 PM, Laszlo Ersek wrote:
>> On 07/11/17 16:31, Stefan Berger wrote:
>>> This patch adds a description of the current TPM support in QEMU
>>> to the specs.
>>>
>>> Several public specs are referenced via their landing page on the
>>> trustedcomputinggroup.org website.
>>>
>>> Signed-off-by: Stefan Berger <[e-mail]>
>>>
>>> ---
>>>
>>> v1->v2:
>>>   - fixed typos
>>>   - added command line for starting an x86_64 VM with TPM passthrough device
>>>   - added command lines for checks inside the VM
>>> ---
>>>  docs/specs/tpm.txt | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>  1 file changed, 124 insertions(+)
>>>  create mode 100644 docs/specs/tpm.txt
>>
>> Awesome, thank you very much!
>>
>> I think I noticed one typo in new text:
>>
>>> +#> dmesg | grep TCPA
>>> +[    0.000000] ACPI: TCP 0x0000000003FFD191C 000032 (v02 BOCHS  \
>>> +    BXPCTCPA 0000001 BXPC 00000001)
>>
>> I think the prefix here should be "ACPI: TCPA"; the letter "A" probably
>> fell victim to wrapping the line nicely.
>>
>> Not sure which maintainer will pick up the patch, but I think they can
>> fix up this typo on their end (assuming no other reviewer asks for v3).
>>
>> Reviewed-by: Laszlo Ersek <[e-mail]>
>>
> 
> It seems this patch was never picked.

Michael, can you pick this up please? (Asking you just based on the
output of "scripts/get_maintainer.pl -f docs/specs".)

This is a documentation-only patch (about existing code), so it can't
regress anything. It's been on the list for more than one month, so I
think it should be fine for 2.10.

Otherwise, should Stefan repost it when 2.11 is open (or whatever
version number will come next)?

Thanks,
Laszlo

Patch

diff --git a/docs/specs/tpm.txt b/docs/specs/tpm.txt
new file mode 100644
index 0000000..1e968a2
--- /dev/null
+++ b/docs/specs/tpm.txt
@@ -0,0 +1,124 @@ 
+
+QEMU TPM Device
+===============
+
+= Guest-side Hardware Interface =
+
+The QEMU TPM emulation implements a TPM TIS hardware interface following
+the Trusted Computing Group's specification "TCG PC Client Specific TPM
+Interface Specification (TIS)", Specifcation Version 1.3, 21 March 2013.
+This specification, or a later version of it, can be accessed from the
+following URL:
+
+https://trustedcomputinggroup.org/pc-client-work-group-pc-client-specific-tpm-interface-specification-tis/
+
+The TIS interface makes a memory mapped IO region in the area 0xfed40000 -
+0xfed44fff available to the guest operating system.
+
+
+QEMU files related to TPM TIS interface:
+ - hw/tpm/tpm_tis.c
+ - hw/tpm/tpm_tis.h
+
+
+= ACPI Interface =
+
+The TPM device is defined with ACPI ID "PNP0C31". QEMU builds a SSDT and passes
+it into the guest through the fw_cfg device. The device description contains
+the base address of the TIS interface 0xfed40000 and the size of the MMIO area
+(0x5000). In case a TPM2 is used by QEMU, a TPM2 ACPI table is also provided.
+The device is described to be used in polling mode rather than interrupt mode
+primarily because no unused IRQ could be found.
+
+To support measurement logs to be written by the firmware, e.g. SeaBIOS, a TCPA
+table is implemented. This table provides a 64kb buffer where the firmware can
+write its log into. For TPM 2 only a more recent version of the TPM2 table
+provides support for measurements logs and a TCPA table does not need to be
+created.
+
+The TCPA and TPM2 ACPI tables follow the Trusted Computing Group specification
+"TCG ACPI Specification" Family "1.2" and "2.0", Level 00 Revision 00.37. This
+specification, or a later version of it, can be accessed from the following
+URL:
+
+https://trustedcomputinggroup.org/tcg-acpi-specification/
+
+
+QEMU files related to TPM ACPI tables:
+ - hw/i386/acpi-build.c
+ - include/hw/acpi/tpm.h
+
+
+= TPM backend devices =
+
+The TPM implementation is split into two parts, frontend and backend. The
+frontend part is the hardware interface, such as the TPM TIS interface described
+earlier, and the other part is the TPM backend interface. The backend interfaces
+implement the interaction with a TPM device, which may be a physical or an
+emulated device. The split between the front- and backend devices allows a
+frontend to be connected with any available backend. This enables the TIS
+interface to be used with the passthrough backend or the (future) swtpm backend.
+
+
+QEMU files related to TPM backends:
+ - backends/tpm.c
+ - include/sysemu/tpm_backend.h
+ - include/sysemu/tpm_backend_int.h
+
+
+== The QEMU TPM passthrough device ==
+
+In case QEMU is run on Linux as the host operating system it is possible to
+make the hardware TPM device available to a single QEMU guest. In this case the
+user must make sure that no other program is using the device, e.g., /dev/tpm0,
+before trying to start QEMU with it.
+
+The passthrough driver uses the host's TPM device for sending TPM commands
+and receiving responses from. Besides that it accesses the TPM device's sysfs
+entry for support of command cancellation. Since none of the state of a hardware
+TPM can be migrated between hosts, virtual machine migration is disabled when
+the TPM passthrough driver is used.
+
+Since the host's TPM device will already be initialized by the host's firmware,
+certain commands, e.g. TPM_Startup(), sent by the virtual firmware for device
+initialization, will fail. In this case the firmware should not use the TPM.
+
+Sharing the device with the host is generally not a recommended usage scenario
+for a TPM device. The primary reason for this is that two operating systems can
+then access the device's single set of resources, such as platform configuration
+registers (PCRs). Applications or kernel security subsystems, such as the
+Linux Integrity Measurement Architecture (IMA), are not expecting to share PCRs.
+
+
+QEMU files related to the TPM passthrough device:
+ - hw/tpm/tpm_passthrough.c
+ - hw/tpm/tpm_util.c
+ - hw/tpm/tpm_util.h
+
+
+Command line to start QEMU with the TPM passthrough device using the host's
+hardware TPM /dev/tpm0:
+
+qemu-system-x86_64 -display sdl -enable-kvm \
+  -m 1024 -boot d -bios bios-256k.bin -boot menu=on \
+  -tpmdev passthrough,id=tpm0,path=/dev/tpm0 \
+  -device tpm-tis,tpmdev=tpm0 test.img
+
+The following command should result in similar output inside the VM with a
+Linux kernel that either has the TPM TIS driver built-in or available as a
+module:
+
+#> dmesg | grep -i tpm
+[    0.711310] tpm_tis 00:06: 1.2 TPM (device=id 0x1, rev-id 1)
+
+#> dmesg | grep TCPA
+[    0.000000] ACPI: TCP 0x0000000003FFD191C 000032 (v02 BOCHS  \
+    BXPCTCPA 0000001 BXPC 00000001)
+
+#> ls -l /dev/tpm*
+crw-------. 1 root root 10, 224 Jul 11 10:11 /dev/tpm0
+
+#> find /sys/devices/ | grep pcrs$ | xargs cat
+PCR-00: 35 4E 3B CE 23 9F 38 59 ...
+...
+PCR-23: 00 00 00 00 00 00 00 00 ...