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 concepts.

------------------------------
INTRODUCTION
------------------------------
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.
 
------------------------------
DESIGN OVERVIEW
------------------------------

The architecture of vTPM is described below:

+------------------+
|    Linux DomU    | ...
|       |  ^       |
|       v  |       |
|   xen-tpmfront   |
+------------------+
        |  ^
        v  |
+------------------+
| mini-os/tpmback  |
|       |  ^       |
|       v  |       |
|  vtpm-stubdom    | ...
|       |  ^       |
|       v  |       |
| mini-os/tpmfront |
+------------------+
        |  ^
        v  |
+------------------+
| mini-os/tpmback  |
|       |  ^       |
|       v  |       |
| vtpmmgr-stubdom  |
|       |  ^       |
|       v  |       |
| mini-os/tpm_tis  |
+------------------+
        |  ^
        v  |
+------------------+
|   Hardware TPM   |
+------------------+
 * Linux DomU: The Linux based guest that wants to use a vTPM. There many be
               more than one of these.

 * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
                    provides vTPM access to a para-virtualized Linux based DomU.

 * mini-os/tpmback: 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
                    vtpm-stubdom.

 * vtpm-stubdom: 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/tpmfront: 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
                     its own.

 * vtpmmgr-stubdom: 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_tis: 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 vtpmmgr-stubdom.

 * Hardware TPM: The physical TPM that is soldered onto the motherboard.

------------------------------
INSTALLATION
------------------------------

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

Compiling the XEN tree:
-----------------------

Compile and install the XEN tree as usual. Be sure to build and install
the stubdom tree.

Compiling the LINUX dom0 kernel:
--------------------------------

The Linux dom0 kernel should not try accessing the TPM while the vTPM
Manager domain is accessing it; the simplest way to accomplish this is
to ensure the kernel is compiled without a driver for the TPM, or avoid
loading the driver by blacklisting the module.

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

------------------------------
VTPM MANAGER SETUP
------------------------------

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 does not need
to be large. 8 to 16 Mb should be sufficient.

# dd if=/dev/zero of=/var/vtpmmgr-stubdom.img bs=16M count=1

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. An
example configuration looks like the following.

kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
memory=16
disk=["file:/var/vtpmmgr-stubdom.img,hda,w"]
name="vtpmmgr"
iomem=["fed40,5"]

The iomem line tells xl to allow access to all of the TPM IO memory
pages, which are 5 pages (one per locality) that start at 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.

Starting and stopping the manager:
----------------------------------

The vTPM manager should be started at boot, you may wish to
create an init script to do this.

# xl create -c vtpmmgr-stubdom.cfg

Once initialization is complete you should see the following:
INFO[VTPM]: Waiting for commands from vTPM's:

To shutdown the manager you must destroy it. To avoid data corruption,
only destroy the manager when you see the above "Waiting for commands"
message. This ensures the disk is in a consistent state.

# xl destroy vtpmmgr-stubdom

------------------------------
VTPM AND LINUX PVM SETUP
------------------------------

In the following examples we will assume we have Linux
guest named "domu" with its associated configuration
located at /home/user/domu. It's vtpm will be named
domu-vtpm.

vTPM disk image setup:
----------------------

The vTPM requires a disk image to store its persistent
data. The image does not require a filesystem. The image
does not need to be large. 8 Mb should be sufficient.

# dd if=/dev/zero of=/home/user/domu/vtpm.img bs=8M count=1

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. An example configuration is given:

kernel="/usr/lib/xen/boot/vtpm-stubdom.gz"
memory=8
disk=["file:/home/user/domu/vtpm.img,hda,w"]
name="domu-vtpm"
vtpm=["backend=vtpmmgr,uuid=ac0a5b9e-cbe2-4c07-b43b-1d69e46fb839"]

The vtpm= line sets up the tpm frontend driver. The backend must set
to vtpmmgr. You are required to generate a uuid for this vtpm.
You can use the uuidgen unix program or some other method to create a
uuid. The uuid uniquely identifies this vtpm to manager.

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).

Launching and shut down:
------------------------

To launch a Linux guest with a vTPM we first have to start the vTPM domain.

# xl create -c /home/user/domu/vtpm.cfg

After initialization is complete, you should see the following:
Info: Waiting for frontend domain to connect..

Next, launch the Linux guest

# xl create -c /home/user/domu/domu.cfg

If xen-tpmfront was compiled as a module, be sure to load 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

If you have trousers and tpm_tools installed on the guest, you can test the
vtpm.

On guest:
# tcsd (if tcsd is not running already)
# tpm_version

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.

------------------------------
INTEGRATION WITH PV-GRUB
------------------------------

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.

------------------------------
MORE INFORMATION
------------------------------

See stubdom/vtpmmgr/README for more details about how
the manager domain works, how to use it, and its command line
parameters.

See stubdom/vtpm/README for more specifics about how vtpm-stubdom
operates and the command line options it accepts.