[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Xen-devel] [PATCH VTPM v9 4/8] Add vtpm documentation

See the files included in this patch for details

Signed-off-by: Matthew Fioravante <matthew.fioravante@xxxxxxxxxx>
Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
 docs/misc/vtpm.txt     |  357 ++++++++++++++++++++++++++++++++++--------------
 stubdom/vtpm/README    |   75 ++++++++++
 stubdom/vtpmmgr/README |   75 ++++++++++
 3 files changed, 401 insertions(+), 106 deletions(-)
 create mode 100644 stubdom/vtpm/README
 create mode 100644 stubdom/vtpmmgr/README

diff --git a/docs/misc/vtpm.txt b/docs/misc/vtpm.txt
index ad37fe8..fc6029a 100644
--- a/docs/misc/vtpm.txt
+++ b/docs/misc/vtpm.txt
@@ -1,152 +1,297 @@
-Copyright: IBM Corporation (C), Intel Corporation
-29 June 2006
-Authors: Stefan Berger <stefanb@xxxxxxxxxx> (IBM), 
-         Employees of Intel Corp
-This document gives a short introduction to the virtual TPM support
-in XEN and goes as far as connecting a user domain to a virtual TPM
-instance and doing a short test to verify success. It is assumed
-that the user is fairly familiar with compiling and installing XEN
-and Linux on a machine. 
+Copyright (c) 2010-2012 United States Government, as represented by
+the Secretary of Defense.  All rights reserved.
+November 12 2012
+Authors: Matthew Fioravante (JHUAPL),
+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.
+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.  Thus, 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.
-Production Prerequisites: An x86-based machine machine with a
-Linux-supported TPM on the motherboard (NSC, Atmel, Infineon, TPM V1.2).
-Development Prerequisites: An emulator for TESTING ONLY is provided
+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  |       |
+|   vtpmmgrdom     |
+|       |  ^       |
+|       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 
+ * 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 vtpmmgrdom 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
+                     vtpmmgrdom. This driver could also be used separately to
+                     implement a mini-os domain that wishes to use a vTPM of
+                     its own.
+ * vtpmmgrdom: 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 vtpmmgrdom to talk directly to
+                    the hardware TPM. Communication is facilitated by mapping
+                    hardware memory pages into vtpmmgrdom.
+ * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+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 the XEN tree as usual after the following lines set in the
-linux-2.6.??-xen/.config file:
+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 has no special prerequisites.
-CONFIG_TCG_TIS=m      (supported after 2.6.17-rc4)
-<possible other TPM drivers supported by Linux>
+Compiling the LINUX domU kernel:
-If the frontend driver needs to be compiled into the user domain
-kernel, then the following two lines should be changed.
+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.
+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/vtpmmgrdom.img bs=16M count=1
+Manager config file:
+The vTPM Manager domain (vtpmmgrdom) 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.
+The iomem line tells xl to allow access to the TPM
+IO memory pages, which are 5 pages that start at
+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 vtpmmgrdom.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 vtpmmgrdom
-You must also enable the virtual TPM to be built:
+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
-In Config.mk in the Xen root directory set the line
+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.
-and in
+# dd if=/dev/zero of=/home/user/domu/vtpm.img bs=8M count=1
-tools/vtpm/Rules.mk set the line
+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:
-Now build the Xen sources from Xen's root directory:
-make install
+The vtpm= line sets up the tpm frontend driver. The backend must set
+to vtpmmgrdom. 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.
-Also build the initial RAM disk if necessary.
+Linux Guest config file:
-Reboot the machine with the created Xen kernel.
+The Linux guest config file needs to be modified to include
+the Linux tpmfront driver. Add the following line:
-Note: If you do not want any TPM-related code compiled into your
-kernel or built as module then comment all the above lines like
-this example:
-# CONFIG_TCG_TPM is not set
+Currently only paravirtualized guests are supported.
-Modifying VM Configuration files:
+Launching and shut down:
-VM configuration files need to be adapted to make a TPM instance
-available to a user domain. The following VM configuration file is
-an example of how a user domain can be configured to have a TPM
-available. It works similar to making a network interface
-available to a domain.
+To launch a Linux guest with a vTPM we first have to start the vTPM domain.
-kernel = "/boot/vmlinuz-2.6.x"
-ramdisk = "/xen/initrd_domU/U1_ramdisk.img"
-memory = 32
-name = "TPMUserDomain0"
-vtpm = ['instance=1,backend=0']
-root = "/dev/ram0 console=tty ro"
-vif = ['backend=0']
+# xl create -c /home/user/domu/vtpm.cfg
-In the above configuration file the line 'vtpm = ...' provides
-information about the domain where the virtual TPM is running and
-where the TPM backend has been compiled into - this has to be 
-domain 0  at the moment - and which TPM instance the user domain
-is supposed to talk to. Note that each running VM must use a 
-different instance and that using instance 0 is NOT allowed. The
-instance parameter is taken as the desired instance number, but
-the actual instance number that is assigned to the virtual machine
-can be different. This is the case if for example that particular
-instance is already used by another virtual machine. The association
-of which TPM instance number is used by which virtual machine is
-kept in the file /var/vtpm/vtpm.db. Associations are maintained by
-a xend-internal vTPM UUID and vTPM instance number.
+After initialization is complete, you should see the following:
+Info: Waiting for frontend domain to connect..
-Note: If you do not want TPM functionality for your user domain simply
-leave out the 'vtpm' line in the configuration file.
+Next, launch the Linux guest
+# xl create -c /home/user/domu/domu.cfg
-Running the TPM:
+If xen-tpmfront was compiled as a module, be sure to load it
+in the guest.
-To run the vTPM, the device /dev/vtpm must be available.
-Verify that 'ls -l /dev/vtpm' shows the following output:
+# modprobe xen-tpmfront
-crw-------  1 root root 10, 225 Aug 11 06:58 /dev/vtpm
+After the Linux domain boots and the xen-tpmfront driver is loaded,
+you should see the following on the vtpm console:
-If it is not available, run the following command as 'root'.
-mknod /dev/vtpm c 10 225
+Info: VTPM attached to Frontend X/Y
-Make sure that the vTPM is running in domain 0. To do this run the
+If you have trousers and tpm_tools installed on the guest, you can test the
-modprobe tpmbk
+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:
+  Spec Level:          2
+  Errata Revision:     1
+  TPM Vendor ID:       ETHZ
+  TPM Version:         01010000
+  Manufacturer Info:   4554485a
-Start a user domain using the 'xm create' command. Once you are in the
-shell of the user domain, you should be able to do the following as
-user 'root':
+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 vtpmmgrdom console.
-Insert the TPM frontend into the kernel if it has been compiled as a
-kernel module.
+To shutdown the guest and its vtpm, you just have to shutdown the guest
+normally. As soon as the guest vm disconnects, the vtpm will shut itself
+down automatically.
-> modprobe tpm_xenu
+On guest:
+# shutdown -h now
-Check the status of the TPM
+You may wish to write a script to start your vtpm and guest together.
-> cd /sys/devices/xen/vtpm-0
-> ls
-[...]  cancel  caps   pcrs    pubek   [...]
-> cat pcrs
-PCR-00: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-01: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-02: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-03: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-04: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-05: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-06: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-07: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-PCR-08: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-At this point the user domain has been successfully connected to its
-virtual TPM instance.
+See stubdom/vtpmmgr/README for more details about how
+the manager domain works, how to use it, and its command line
-For further information please read the documentation in 
-tools/vtpm_manager/README and tools/vtpm/README
+See stubdom/vtpm/README for more specifics about how vtpm-stubdom
+operates and the command line options it accepts.
-Stefan Berger and Employees of the Intel Corp
diff --git a/stubdom/vtpm/README b/stubdom/vtpm/README
new file mode 100644
index 0000000..11bdacb
--- /dev/null
+++ b/stubdom/vtpm/README
@@ -0,0 +1,75 @@
+Copyright (c) 2010-2012 United States Government, as represented by
+the Secretary of Defense.  All rights reserved.
+November 12 2012
+Authors: Matthew Fioravante (JHUAPL),
+This document describes the operation and command line interface
+of vtpm-stubdom. See docs/misc/vtpm.txt for details on the
+vTPM subsystem as a whole.
+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 pair.
+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:
+extra="foo=bar baz"
+List of Arguments:
+loglevel=<LOG>: Controls the amount of logging printed to the console.
+       The possible values for <LOG> are:
+        error
+        info (default)
+        debug
+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.
+       Value values of <PCRSPEC> are:
+        all: copy all pcrs
+        none: copy no pcrs (default)
+        <N>: copy pcr n
+        <X-Y>: copy pcrs x to y (inclusive)
+       These can also be combined by comma separation, for example:
+        hwinitpcrs=5,12-16
+       will copy pcrs 5, 12, 13, 14, 15, and 16.
+Berlios TPM Emulator:
diff --git a/stubdom/vtpmmgr/README b/stubdom/vtpmmgr/README
new file mode 100644
index 0000000..09f3958
--- /dev/null
+++ b/stubdom/vtpmmgr/README
@@ -0,0 +1,75 @@
+Copyright (c) 2010-2012 United States Government, as represented by
+the Secretary of Defense.  All rights reserved.
+November 12 2012
+Authors: Matthew Fioravante (JHUAPL),
+This document describes the operation and command line interface
+of vtpmmgrdom. See docs/misc/vtpm.txt for details on the
+vTPM subsystem as a whole.
+The vtpmmgrdom implements a vTPM manager who has two major functions:
+ - Securely store encryption keys for each of the vTPMS
+ - Regulate access to the hardware TPM for the entire system
+The manager accepts commands from the vtpm-stubdom domains via the mini-os
+TPM backend driver. The vTPM manager communicates directly with hardware TPM
+using the mini-os tpm_tis driver.
+When the manager starts for the first time it will check if the TPM
+has an owner. If the TPM is unowned, it will attempt to take ownership
+with the supplied owner_auth (see below) and then create a TPM
+storage key which will be used to secure vTPM key data. Currently the
+manager only binds vTPM keys to the disk. In the future support
+for sealing to PCRs should be added.
+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:
+extra="foo=bar baz"
+List of Arguments:
+owner_auth=<AUTHSPEC>: Set the owner auth of the TPM. The default
+       is the well known owner auth of all ones.
+srk_auth=<AUTHSPEC>: Set the SRK auth for the TPM. The default is
+       the well known srk auth of all zeroes.
+       The possible values of <AUTHSPEC> are:
+        well-known: Use the well known auth (default)
+        random: Randomly generate an auth
+        hash: <HASH>: Use the given 40 character ASCII hex string
+        text: <STR>: Use sha1 hash of <STR>.
+tpmdriver=<DRIVER>: Which driver to use to talk to the hardware TPM.
+       Don't change this unless you know what you're doing.
+       The possible values of <DRIVER> are:
+        tpm_tis: Use the tpm_tis driver to talk directly to the TPM.
+               The domain must have access to TPM IO memory.  (default)
+        tpmfront: Use tpmfront to talk to the TPM. The domain must have
+               a tpmfront device setup to talk to another domain
+               which provides access to the TPM.
+The following options only apply to the tpm_tis driver:
+tpmiomem=<ADDR>: The base address of the hardware memory pages of the
+       TPM (default 0xfed40000).
+tpmirq=<IRQ>: The irq of the hardware TPM if using interrupts. A value of
+       "probe" can be set to probe for the irq. A value of 0
+       disabled interrupts and uses polling (default 0).
+tpmlocality=<LOC>: Attempt to use locality <LOC> of the hardware TPM.
+       (default 0)

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.