From f6b1421f292b57483d3fb8fddf8a6abcef14150c Mon Sep 17 00:00:00 2001 From: Matthew Fioravante Date: Fri, 18 Jan 2013 10:55:45 +0000 Subject: Add vtpm documentation See the files included in this patch for details Signed-off-by: Matthew Fioravante Acked-by: Ian Campbell Committed-by: Ian Campbell --- stubdom/vtpm/README | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++ stubdom/vtpmmgr/README | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 stubdom/vtpm/README create mode 100644 stubdom/vtpmmgr/README (limited to 'stubdom') 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=: Controls the amount of logging printed to the console. + The possible values for 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=: Initialize the virtual Platform Configuration Registers + (PCRs) with PCR values from the hardware TPM. Each pcr specified by + 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 are: + all: copy all pcrs + none: copy no pcrs (default) + : copy pcr n + : 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=: Set the owner auth of the TPM. The default + is the well known owner auth of all ones. + +srk_auth=: Set the SRK auth for the TPM. The default is + the well known srk auth of all zeroes. + The possible values of are: + well-known: Use the well known auth (default) + random: Randomly generate an auth + hash: : Use the given 40 character ASCII hex string + text: : Use sha1 hash of . + +tpmdriver=: 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 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=: The base address of the hardware memory pages of the + TPM (default 0xfed40000). + +tpmirq=: 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=: Attempt to use locality of the hardware TPM. + (default 0) -- cgit v1.2.3