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.