README

   1 SWTPM - Software TPM Emulator
   2       David Safford safford@us.ibm.com
   3       Stefan Berger stefanb@us.ibm.com
   4
   5 The SWTPM package provides TPM emulators with different front-end interfaces
   6 to libtpms. TPM emulators provide socket interfaces (TCP/IP) and the Linux
   7 CUSE interface for the creation of multiple native /dev/vtpm* devices.
   8 Those can be the targets of multiple QEMU cuse-tpm instances.
   9
  10 The SWTPM package also provides several tools for using the CUSE TPM,
  11 creating certificates for a TPM, and simulating the manufacturing of
  12 a TPM by creating a TPM's EK and platform certificates etc. Please read
  13 the READMEs in the individual tool's directory under src/.
  14
  15
  16 TPM emulators:
  17 --------------
  18
  19 The primary goal of the CUSE TPM is to support running multiple QEMU guests,
  20 each having its own TPM emulator, without modifying QEMU, the kernel, or
  21 libtpms. The approach is to use the QEMU cuse-tpm driver, pointing it to
  22 /dev/vtpm? which is established as a CUSE frontend to libtpms.
  23
  24 The CUSE frontend supports ioctls on the /dev/vtpm? device file, for
  25 handling hardware specific features, such as hardware reset, hardware
  26 shutdown, setting locality, and getting the tpmEstablished bit and
  27 others. There is a getcapability ioctl to query which of these features
  28 are available on a given vtpm.
  29
  30 This has been tested on Fedora 20, as it has everything needed
  31 (cuse, QEMU with TPM passthrough driver, libtpms...) enabled by default.
  32 It is also known to work on RHEL-6.
  33
  34 Building:
  35         Please read INSTALL for how to build and install the package
  36
  37 Notes:  If you are running selinux in enforcing mode (the Fedora 20 default),
  38         then you will get many (6?) rounds of errors, and everytime you have to
  39         use the selinux troubleshooter to add policies to allow the vtpm
  40         server to run. You only have to do this for the first VM.
  41
  42         (If you are running ima-appraisal, you will need to sign the
  43         installed executables and libraries (/usr/bin/swtpm and
  44         /usr/bin/swtpm_cuse and /usr/lib/libswtpm_libtpms.so)
  45
  46 In the Guest:
  47         If you are running a fedora20 guest, then you can start out with:
  48                 yum install tpm-tools
  49                 systemctl start tcsd.service
  50                 tpm_createek
  51                 tpm_takeown -u -y -z
  52                 tpm_getpubek -u -z
  53
  54 -----------------------------------------------------------------------------
  55 Low level details on the executables:
  56
  57         On Fedora 20, CUSE is a module, so you may need to:
  58                 modprobe cuse
  59         For each desired vtpm, as root you simply:
  60                 export TPM_PATH=<directory to keep vtpm state files>
  61                 ./swtpm_cuse -M <major> -m <minor> -n <device name>
  62         The process runs as a background daemon.
  63
  64 Initialize a two vTPMs' initial state with an EK each:
  65
  66         # mkdir /tmp/myvtpm0
  67         # chown -R tss:root  /tmp/myvtpm0
  68         # swtpm_setup --tpm-state /tmp/myvtpm0  --createek
  69
  70         # mkdir /tmp/myvtpm1
  71         # chown -R tss:root  /tmp/myvtpm1
  72         # swtpm_setup --tpm-state /tmp/myvtpm0  --createek
  73
  74 Start the vTPM to use it with QEMU:
  75
  76         # export TPM_PATH=/tmp/myvtpm0
  77         # swtpm_cuse -n vtpm0
  78
  79         # export TPM_PATH=/tmp/myvtpm1
  80         # swtpm_cuse -n vtpm1
  81
  82 Running QEMU with the cuse-tpm:
  83
  84 There are two needed options for the passthrough -tpmdev and -device
  85 as shown in these examples. Note that the "path" parameter points to the
  86 native (/dev/vtpm0...) path, while the id and tpmdev are the guest's view.
  87
  88 [Note: for the following to work, QEMU needs to be patched with
  89        yet to be published patches]
  90
  91     $ qemu-system-x86_64 -display sdl -enable-kvm -cdrom cdrom.iso \
  92     -m 1024 -boot d -bios bios.bin -boot menu=on -tpmdev \
  93     cuse-tpm,id=tpm0,path=/dev/vtpm0 \
  94     -device tpm-tis,tpmdev=tpm0 test.img
  95
  96     $ qemu-system-x86_64 -display sdl -enable-kvm -cdrom cdrom.iso \
  97     -m 1024 -boot d -bios bios.bin -boot menu=on -tpmdev \
  98     cuse-tpm,id=tpm1,path=/dev/vtpm1 \
  99     -device tpm-tis,tpmdev=tpm1 test2.img
 100