similarity index 54%
rename from docs/misc/vtpmmgr.txt
rename to docs/man/vtpmmgr.pod.7
@@ -1,22 +1,30 @@
-================================================================================
-Authors:
- Daniel De Graaf <dgdegra@tycho.nsa.gov>
- Quan Xu <quan.xu@intel.com>
-================================================================================
+=head1 Authors
+
+=over 4
+
+=item Daniel De Graaf <dgdegra@tycho.nsa.gov>
+
+=item Quan Xu <quan.xu@intel.com>
+
+=back
This document describes the operation and command line interface of
-vtpmmgr-stubdom. See docs/misc/vtpm.txt for details on the vTPM subsystem as a
+vtpmmgr-stubdom. See L<vtpm(7)> for details on the vTPM subsystem as a
whole.
-================================================================================
-Overview
-================================================================================
+=head1 Overview
The TPM Manager has three primary functions:
-1. Securely store the encryption keys for vTPMs
-2. Provide a single controlled path of access to the physical TPM
-3. Provide evidence (via TPM Quotes) of the current configuration
+=over 4
+
+=item 1. Securely store the encryption keys for vTPMs
+
+=item 2. Provide a single controlled path of access to the physical TPM
+
+=item 3. Provide evidence (via TPM Quotes) of the current configuration
+
+=back
When combined with a platform that provides a trusted method for creating
domains, the TPM Manager provides assurance that the private keys in a vTPM are
@@ -26,9 +34,7 @@ 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.
-================================================================================
-Boot Configurations and TPM Groups
-================================================================================
+=head1 Boot Configurations and TPM Groups
The TPM Manager's data is secured by using the physical TPM's seal operation,
which allows data to be bound to specific PCRs. These PCRs are populated in the
@@ -52,9 +58,7 @@ has its own AIK in the physical TPM for quotes of the hardware TPM state; when
used with a conforming Privacy CA, this allows each group on the system to form
the basis of a distinct identity.
-================================================================================
-Initial Provisioning
-================================================================================
+=head1 Initial Provisioning
When the TPM Manager first boots up, it will create a stub vTPM group along with
entries for any vTPMs that communicate with it. This stub group must be
@@ -73,51 +77,87 @@ group is created, a signed list of boot measurements can be installed. The
initial group controls the ability to boot the system as a whole, and cannot be
deleted once provisioned.
-================================================================================
-Command Line Arguments
-================================================================================
+=head1 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"
+ extra="foo=bar baz"
Valid arguments:
-owner_auth=<AUTHSPEC>
-srk_auth=<AUTHSPEC>
- Set the owner and SRK authdata for the TPM. If not specified, the
- default is 160 zero bits (the well-known auth value). Valid values of
- <AUTHSPEC> are:
- well-known Use the well known auth (default)
- hash:<HASH> Use the given 40-character ASCII hex string
- text:<STR> Use sha1 hash of <STR>.
-
-tpmdriver=<DRIVER>
- Choose the driver used for communication with the hardware TPM. Values
- other than tpm_tis should only be used for testing.
-
- The possible values of <DRIVER> are:
- tpm_tis Direct communication with a hardware TPM 1.2. The
- domain must have access to TPM IO memory. (default)
- tpmfront Use the Xen tpmfront interface to talk to another
- domain which provides access to the TPM.
+=over 4
+
+=item owner_auth=<AUTHSPEC>
+
+=item srk_auth=<AUTHSPEC>
+
+Set the owner and SRK authdata for the TPM. If not specified, the
+default is 160 zero bits (the well-known auth value). Valid values of
+<AUTHSPEC> are:
+
+=over 4
+
+=item well-known
+
+Use the well known auth (default)
+
+=item hash:<HASH>
+
+Use the given 40-character ASCII hex string
+
+=item text:<STR>
+
+Use sha1 hash of <STR>.
+
+=back
+
+=item tpmdriver=<DRIVER>
+
+Choose the driver used for communication with the hardware TPM. Values
+other than tpm_tis should only be used for testing.
+
+The possible values of <DRIVER> are:
+
+=over 4
+
+=item tpm_tis
+
+Direct communication with a hardware TPM 1.2. The
+domain must have access to TPM IO memory. (default)
+
+=item tpmfront
+
+Use the Xen tpmfront interface to talk to another
+domain which provides access to the TPM.
+
+=back
+
+=back
The following options only apply to the tpm_tis driver:
-tpmiomem=<ADDR>: The base address of the hardware memory pages of the TPM.
- The default is 0xfed40000, as defined by the TCG's PC Client spec.
+=over 4
+
+=item tpmiomem=<ADDR>
-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 disables
- interrupts and uses polling (default 0).
+The base address of the hardware memory pages of the TPM.
+The default is 0xfed40000, as defined by the TCG's PC Client spec.
-tpmlocality=<LOC>: Attempt to use locality <LOC> of the hardware TPM.
- For full functionality of the TPM Manager, this should be set to "2".
+=item tpmirq=<IRQ>
-================================================================================
-Platform Security Assumptions
-================================================================================
+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 disables
+interrupts and uses polling (default 0).
+
+=item tpmlocality=<LOC>
+
+Attempt to use locality <LOC> of the hardware TPM.
+For full functionality of the TPM Manager, this should be set to "2".
+
+=back
+
+=head1 Platform Security Assumptions
While the TPM Manager has the ability to check the hash of the vTPM requesting a
key, there is currently no trusted method to inform the TPM Manager of the hash
@@ -143,9 +183,7 @@ unexpected busy errors from the TPM driver. The ability to access locality 2 of
the TPM should be enforced using IO memory labeling in the XSM policy; the
physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver.
-================================================================================
-Appendix: unsecured migration process for vtpmmgr domain upgrade
-================================================================================
+=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade
There is no direct upgrade supported from previous versions of the vtpmmgr
domain due to changes in the on-disk format and the method used to seal data.
@@ -156,34 +194,40 @@ If adding migration support to the vTPM is not desired, a simpler migration
domain usable only for local migration can be constructed. The migration process
would look like the following:
-1. Start the old vtpmmgr
-2. Start the vTPM migration domain
-3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
-4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
-5. Start the new vtpmmgr, possibly shutting down the old one first
-6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
-7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
+=over 4
+
+=item 1. Start the old vtpmmgr
+
+=item 2. Start the vTPM migration domain
+
+=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
+
+=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
+
+=item 5. Start the new vtpmmgr, possibly shutting down the old one first
+
+=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
+
+=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
+
+=back
This requires the migration domain to be added to the list of valid vTPM kernel
hashes. In the current version of the vtpmmgr domain, this is the hash of the
XSM label, not the kernel.
-================================================================================
-Appendix B: vtpmmgr on TPM 2.0
-================================================================================
+=head1 Appendix B: vtpmmgr on TPM 2.0
-Manager disk image setup:
--------------------------
+=head2 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
is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
but can support more than 20,000 vTPMs.
- dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
+ dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
-Manager config file:
---------------------
+=head2 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
@@ -194,9 +238,9 @@ locality) that start at physical address 0xfed40000. By default, the TPM manager
uses locality 0 (so only the page at 0xfed40 is needed).
Add:
-..
+
extra="tpm2=1"
-..
+
extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
1.x. for example:
@@ -208,8 +252,7 @@ extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
extra="tpm2=1"
-Key Hierarchy
-------------------------------
+=head2 Key Hierarchy
+------------------+
| vTPM's secrets | ...
@@ -238,81 +281,99 @@ that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with
TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later
series of patch.
-DESIGN OVERVIEW
-------------------------------
+=head2 Design Overview
The architecture of vTPM subsystem on TPM 2.0 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/tpm2_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM 2.0 |
-+------------------+
-
- * 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/tpm2_tis: Mini-os TPM version 2.0 TPM Interface Specification (TIS)
- driver. This driver used by vtpmmgr-stubdom to talk directly
- to the hardware TPM 2.0. Communication is facilitated by mapping
- hardware memory pages into vtpmmgr-stubdom.
-
- * Hardware TPM 2.0: The physical TPM 2.0 that is soldered onto the motherboard.
-
----------------------
+ +------------------+
+ | 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/tpm2_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM 2.0 |
+ +------------------+
+
+=over 4
+
+=item Linux DomU
+
+The Linux based guest that wants to use a vTPM. There many be
+more than one of these.
+
+=item xen-tpmfront.ko
+
+Linux kernel virtual TPM frontend driver. This driver
+provides vTPM access to a para-virtualized Linux based DomU.
+
+=item 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.
+
+=item 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.
+
+=item 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.
+
+=item 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.
+
+=item mini-os/tpm2_tis
+
+Mini-os TPM version 2.0 TPM Interface Specification (TIS)
+driver. This driver used by vtpmmgr-stubdom to talk directly
+to the hardware TPM 2.0. Communication is facilitated by mapping
+hardware memory pages into vtpmmgr-stubdom.
+
+=item Hardware TPM 2.0
+
+The physical TPM 2.0 that is soldered onto the motherboard.
+
+=back
+
Noted:
functionality for a virtual guest operating system (a DomU) is still TPM 1.2.
vtpmmgr.txt is referenced in a man page, convert it to a man page. Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> --- docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} | 351 ++++++++++++++++----------- 1 file changed, 206 insertions(+), 145 deletions(-) rename docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} (54%)