mirror of
https://github.com/xen-project/xen.git
synced 2026-10-29 18:50:05 +01:00
docs: convert vtpmmgr into a pod man page
vtpmmgr.txt is referenced in a man page, convert it to a man page. The man page is named xen-vtpmmgr to avoid any conflict with other potential vtpm docs. Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> Acked-by: Wei Liu <wei.liu2@citrix.com>
This commit is contained in:
Cédric Bosdonnat authored and 
Wei Liu committed
1 parent
1854013b01
commit
dff45b6bbf
1 file changed
+195
-134
@@ -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<xen-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>.
|
||||
=over 4
|
||||
|
||||
tpmdriver=<DRIVER>
|
||||
Choose the driver used for communication with the hardware TPM. Values
|
||||
other than tpm_tis should only be used for testing.
|
||||
=item owner_auth=<AUTHSPEC>
|
||||
|
||||
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.
|
||||
=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
|
||||
|
||||
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).
|
||||
=item tpmiomem=<ADDR>
|
||||
|
||||
tpmlocality=<LOC>: Attempt to use locality <LOC> of the hardware TPM.
|
||||
For full functionality of the TPM Manager, this should be set to "2".
|
||||
The base address of the hardware memory pages of the TPM.
|
||||
The default is 0xfed40000, as defined by the TCG's PC Client spec.
|
||||
|
||||
================================================================================
|
||||
Platform Security Assumptions
|
||||
================================================================================
|
||||
=item 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).
|
||||
|
||||
=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 | ...
|
||||
| | ^ |
|
||||
| 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.
|
||||
=over 4
|
||||
|
||||
* xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
|
||||
provides vTPM access to a para-virtualized Linux based DomU.
|
||||
=item Linux 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.
|
||||
The Linux based guest that wants to use a vTPM. There many be
|
||||
more than one of these.
|
||||
|
||||
* 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 xen-tpmfront.ko
|
||||
|
||||
* 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.
|
||||
Linux kernel virtual TPM frontend driver. This driver
|
||||
provides vTPM access to a para-virtualized Linux based DomU.
|
||||
|
||||
* 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/tpmback
|
||||
|
||||
* 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.
|
||||
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.
|
||||
|
||||
* Hardware TPM 2.0: The physical TPM 2.0 that is soldered onto the motherboard.
|
||||
=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.
|
||||