xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem
Copyright (c) 2010-2012 United States Government, as represented by the
Secretary of Defense. All rights reserved. November 12 2012 Authors: Matthew
Fioravante (JHUAPL), Daniel De Graaf (NSA)
This document describes the virtual Trusted Platform Module (vTPM)
subsystem for Xen. The reader is assumed to have familiarity with building
and installing Xen, Linux, and a basic understanding of the TPM and vTPM
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (a DomU). This allows programs to interact with a TPM in a
virtual system the same way they interact with a TPM on the physical system.
Each guest gets its own unique, emulated, software TPM. However, each of the
vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, which
seals the secrets to the Physical TPM. If the process of creating each of
these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem
extends the chain of trust rooted in the hardware TPM to virtual machines in
Xen. Each major component of vTPM is implemented as a separate domain,
providing secure separation guaranteed by the hypervisor. The vTPM domains are
implemented in mini-os to reduce memory and processor overhead.
This mini-os vTPM subsystem was built on top of the previous vTPM
work done by IBM and Intel corporation.
The architecture of vTPM is described below:
| Linux DomU | ...
| | ^ |
| v | |
| xen-tpmfront |
| mini-os/tpmback |
| | ^ |
| v | |
| vtpm-stubdom | ...
| | ^ |
| v | |
| mini-os/tpmfront |
| mini-os/tpmback |
| | ^ |
| v | |
| vtpmmgr-stubdom |
| | ^ |
| v | |
| mini-os/tpm_tis |
| Hardware TPM |
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.
Compile and install the Xen tree as usual; be sure that the vTPM domains are
enabled when you run configure.
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.
- Linux DomU
- The Linux based guest that wants to use a vTPM. There many be more than
one of these.
- Linux kernel virtual TPM frontend driver. This driver provides vTPM access
to a para-virtualized Linux based DomU.
- Mini-os TPM backend driver. The Linux frontend driver connects to this
backend driver to facilitate communications between the Linux DomU and its
vTPM. This driver is also used by vtpmmgr-stubdom to communicate with
- A mini-os stub domain that implements a vTPM. There is a one to one
mapping between running vtpm-stubdom instances and logical vtpms on the
system. The vTPM Platform Configuration Registers (PCRs) are all
initialized to zero.
- Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom uses
this driver to communicate with vtpmmgr-stubdom. This driver could also be
used separately to implement a mini-os domain that wishes to use a vTPM of
- A mini-os domain that implements the vTPM manager. There is only one vTPM
manager and it should be running during the entire lifetime of the
machine. This domain regulates access to the physical TPM on the system
and secures the persistent state of each vTPM.
- Mini-os TPM version 1.2 TPM Interface Specification (TIS) driver. This
driver used by vtpmmgr-stubdom to talk directly to the hardware TPM.
Communication is facilitated by mapping hardware memory pages into
- Hardware TPM
- The physical TPM that is soldered onto the motherboard.
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).
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.
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.
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
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.
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.
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.
The Linux guest config file needs to be modified to include the Linux tpmfront
driver. Add the following line:
Currently only Linux guests are supported (PV or HVM with PV
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.
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: 188.8.131.52
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.
The vTPM currently starts up with all PCRs set to their default values (all
zeros for the lower 16). This means that any decisions about the
trustworthiness of the created domain must be made based on the environment
that created the vTPM and the domU; for example, a system that only constructs
images using a trusted configuration and guest kernel be able to provide
guarantees about the guests and any measurements done that kernel (such as the
IMA TCB log). Guests wishing to use a custom kernel in such a secure
environment are often started using the pv-grub bootloader as the kernel,
which then can load the untrusted kernel without needing to parse an untrusted
filesystem and kernel in dom0. If the pv-grub stub domain succeeds in
connecting to a vTPM, it will extend the hash of the kernel that it boots into
PCR #4, and will extend the command line and initrd into PCR #5 before booting
so that a domU booted in this way can attest to its early boot state.
See <xen-vtpmmgr(7)> for more details about how the manager domain
works, how to use it, and its command line parameters.
The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to
use. It is a small wrapper around the Berlios TPM emulator version 0.7.4.
Commands are passed from the linux guest via the mini-os TPM backend driver.
vTPM data is encrypted and stored via a disk image provided to the virtual
machine. The key used to encrypt the data along with a hash of the vTPM's data
is sent to the vTPM manager for secure storage and later retrieval. The vTPM
domain communicates with the manager using a mini-os tpm front/back device
Command line arguments are passed to the domain via the 'extra' parameter in the
VM config file. Each parameter is separated by white space. For example:
- Controls the amount of logging printed to the console. The possible values
for <LOG> are:
- info (default)
- Start the Berlios emulator in "clear" mode. (default)
- Start the Berlios emulator in "save" mode.
- 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.
- Enable to disable the TPM maintenance commands. These commands are used by
tpm manufacturers and thus open a security hole. They are disabled by
- 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>
- all: copy all pcrs
- none: copy no pcrs (default)
- <N>: copy pcr n
- <X-Y>: copy pcrs x to y (inclusive)
Berlios TPM Emulator: <https://github.com/PeterHuewe/tpm-emulator>
These can also be combined by comma separation, for example:
"hwinitpcrs=5,12-16" will copy pcrs 5, 12,
13, 14, 15, and 16.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.