Add vtpm documentation

See the files included in this patch for details

Signed-off-by: Matthew Fioravante <matthew.fioravante@jhuapl.edu>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>

2 files changed, 150 insertions, 0 deletions

diff --git a/stubdom/vtpm/README b/stubdom/vtpm/README
new file mode 100644
index 0000000000..11bdacbdf0
--- /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.
+
+
+------------------------------
+OPERATION
+------------------------------
+
+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
+------------------------------
+
+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.
+
+------------------------------
+REFERENCES
+------------------------------
+
+Berlios TPM Emulator:
+http://tpm-emulator.berlios.de/
diff --git a/stubdom/vtpmmgr/README b/stubdom/vtpmmgr/README
new file mode 100644
index 0000000000..09f3958007
--- /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.
+
+
+------------------------------
+OPERATION
+------------------------------
+
+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
+------------------------------
+
+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)