Prerequisites:¶

You must have an x86 machine with a TPM on the motherboard. The only extra software requirement for compiling vTPM is cmake. You must use libxl to manage domains with vTPMs; 'xm' is deprecated and does not support vTPMs.

Compiling the Xen tree:¶

Compile and install the Xen tree as usual; be sure that the vTPM domains are enabled when you run configure.

Compiling the LINUX dom0 kernel:¶

Because the TPM manager uses direct access to the physical TPM, it may interfere with access to the TPM by dom0. The simplest solution for this is to prevent dom0 from accessing the physical TPM by compiling the kernel without a driver or blacklisting the module. If dom0 needs a TPM but does not need to use it during the boot process (i.e. it is not using IMA), a virtual TPM can be attached to dom0 after the system is booted.

Access to the physical TPM may be required in order to manage the NVRAM or to perform other advanced operations where the vTPM is insufficient. In order to prevent interference, the TPM Manager and dom0 should use different values for the TPM's locality; since Linux always uses locality 0, using locality 2 for the TPM Manager is recommended. If both Linux and the TPM Manager attempt to access the TPM at the same time, the TPM device will return a busy status; some applications will consider this a fatal error instead of retrying the command at a later time. If a vTPM gets an error when loading its key, it will currently generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).

Compiling the LINUX domU kernel:¶

The domU kernel used by domains with vtpms must include the xen-tpmfront.ko driver. It can be built directly into the kernel or as a module; however, some features such as IMA require the TPM to be built in to the kernel.

    CONFIG_TCG_TPM=y
    CONFIG_TCG_XEN=y

Manager disk image setup:¶

The vTPM Manager requires a disk image to store its encrypted data. The image does not require a filesystem and can live anywhere on the host disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image but can support more than 20,000 vTPMs.

Manager config file:¶

The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen virtual machine and requires a config file. The manager requires a disk image for storage and permission to access the hardware memory pages for the TPM. The disk must be presented as "hda", and the TPM memory pages are passed using the iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per locality) that start at physical address 0xfed40000. By default, the TPM manager uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on the domain's command line. For full functionality in deep quotes, using locality 2 is required to manipulate PCR 20-22.

Starting and stopping the manager:¶

The vTPM manager should be started at boot; you may wish to create an init script to do this. If a domain builder is used, the TPM Manager should be started by the domain builder to minimize the trusted computing base for the vTPM manager's secrets.

Once initialization is complete you should see the following:

    INFO[VTPM]: Waiting for commands from vTPM's:

The TPM Manager does not respond to shutdown requests; use the destroy command to shut it down.

vTPM disk image setup:¶

The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM, etc). The image does not require a filesystem. The image does not need to be large; 2 Mb should be sufficient.

vTPM config file:¶

The vTPM domain requires a configuration file like any other domain. The vTPM requires a disk image for storage and a TPM frontend driver to communicate with the manager. You are required to generate a uuid for this vtpm, which is specified on the "vtpm=" line that describes its connection to the vTPM Manager. The uuidgen application may be used to generate a uuid, or one from the output of the "manage-vtpmmgr.pl vtpm-add" command may be used to create a vTPM belonging to a specific group.

If you wish to clear the vTPM data you can either recreate the disk image or change the uuid.

Linux Guest config file:¶

The Linux guest config file needs to be modified to include the Linux tpmfront driver. Add the following line:

    vtpm=["backend=domu-vtpm"]

Currently only Linux guests are supported (PV or HVM with PV drivers).

While attaching a vTPM after a guest is booted (using xl vtpm-attach) is supported, the attached vTPM will not have a record of the boot of the attached guest. Furthermore, if the vTPM has been freshly created, a malicious guest could then extend any values into PCRs, potentially forging its boot configuration. Attaching a vTPM to a running domain should only be used for trusted domains or when measurements have already been sent to the vTPM from another source.

Using the vTPM in the guest:¶

If xen-tpmfront was compiled as a module, it must be loaded it in the guest.

    # modprobe xen-tpmfront

After the Linux domain boots and the xen-tpmfront driver is loaded, you should see the following on the vtpm console:

    Info: VTPM attached to Frontend X/Y

You can quickly test the vTPM by using the sysfs interface:

    # cat /sys/devices/vtpm-0/pubek
    # cat /sys/devices/vtpm-0/pcrs

If you have trousers and tpm_tools installed on the guest, the tpm_version command should return the following:

The version command should return the following:

    TPM 1.2 Version Info:
    Chip Version:        1.2.0.7
    Spec Level:          2
    Errata Revision:     1
    TPM Vendor ID:       ETHZ
    TPM Version:         01010000
    Manufacturer Info:   4554485a

You should also see the command being sent to the vtpm console as well as the vtpm saving its state. You should see the vtpm key being encrypted and stored on the vtpmmgr console.

You may wish to write a script to start your vtpm and guest together and to destroy the vtpm when the guest shuts down.

List of Arguments:¶

loglevel=<LOG>

Controls the amount of logging printed to the console. The possible values for <LOG> are:

clear

Start the Berlios emulator in "clear" mode. (default)

save

Start the Berlios emulator in "save" mode.

deactivated

Start the Berlios emulator in "deactivated" mode. See the Berlios TPM emulator documentation for details about the startup mode. For all normal use, always use clear which is the default. You should not need to specify any of these.

maintcmds=<1|0>

Enable to disable the TPM maintenance commands. These commands are used by tpm manufacturers and thus open a security hole. They are disabled by default.

hwinitpcr=<PCRSPEC>

Initialize the virtual Platform Configuration Registers (PCRs) with PCR values from the hardware TPM. Each pcr specified by <PCRSPEC> will be initialized with the value of that same PCR in TPM once at startup. By default all PCRs are zero initialized. Possible values of <PCRSPEC> are: