1xen-vtpmmgr(7)                        Xen                       xen-vtpmmgr(7)
2
3
4

NAME

6       xen-vtpmgr - Xen virtual TPM stubdomain
7

Authors

9       Daniel De Graaf <dgdegra@tycho.nsa.gov>
10       Quan Xu <quan.xu@intel.com>
11
12       This document describes the operation and command line interface of
13       vtpmmgr-stubdom. See xen-vtpm(7) for details on the vTPM subsystem as a
14       whole.
15

Overview

17       The TPM Manager has three primary functions:
18
19       1. Securely store the encryption keys for vTPMs
20       2. Provide a single controlled path of access to the physical TPM
21       3. Provide evidence (via TPM Quotes) of the current configuration
22
23       When combined with a platform that provides a trusted method for
24       creating domains, the TPM Manager provides assurance that the private
25       keys in a vTPM are only available in specific trusted configurations.
26
27       The manager accepts commands from the vtpm-stubdom domains via the
28       mini-os TPM backend driver. The vTPM manager communicates directly with
29       hardware TPM using the mini-os tpm_tis driver.
30

Boot Configurations and TPM Groups

32       The TPM Manager's data is secured by using the physical TPM's seal
33       operation, which allows data to be bound to specific PCRs. These PCRs
34       are populated in the physical TPM during the boot process, either by
35       the firmware/BIOS or by a dynamic launch environment such as TBOOT. In
36       order to provide assurance of the system's security, the PCRs used to
37       seal the TPM manager's data must contain measurements for domains used
38       to bootstrap the TPM Manager and vTPMs.
39
40       Because these measurements are based on hashes, they will change any
41       time that any component of the system is upgraded. Since it is not
42       possible to construct a list of all possible future good measurements,
43       the job of approving configurations is delegated to a third party,
44       referred to here as the system approval agent (SAA). The SAA is
45       identified by its public (RSA) signature key, which is used to sign
46       lists of valid configurations. A single TPM manager can support
47       multiple SAAs via the use of vTPM groups. Each group is associated with
48       a single SAA; this allows the creation of a multi-tenant environment
49       where tenants may not all choose to trust the same SAA.
50
51       Each vTPM is bound to a vTPM group at the time of its creation. Each
52       vTPM group has its own AIK in the physical TPM for quotes of the
53       hardware TPM state; when used with a conforming Privacy CA, this allows
54       each group on the system to form the basis of a distinct identity.
55

Initial Provisioning

57       When the TPM Manager first boots up, it will create a stub vTPM group
58       along with entries for any vTPMs that communicate with it. This stub
59       group must be provisioned with an SAA and a boot configuration in order
60       to survive a reboot.
61
62       When a vTPM is connected to the TPM Manager using a UUID that is not
63       recognized, a slot will be created in group 0 for it. In the future,
64       this auto-creation may be restricted to specific UUIDs (such as the
65       all-zero UUID) to enforce the use of the TPM manager as the generator
66       of the UUID. The first vTPM to be connected is given administrative
67       privileges for the TPM Manager, and should be attached to dom0 or a
68       control domain in order to send provisioning commands.
69
70       Provisioning a vTPM group for the system requires the public key of the
71       SAA and privacy CA data used to certify the AIK (see the TPM spec for
72       details). Once the group is created, a signed list of boot measurements
73       can be installed. The initial group controls the ability to boot the
74       system as a whole, and cannot be deleted once provisioned.
75

Command Line Arguments

77       Command line arguments are passed to the domain via the 'extra'
78       parameter in the VM config file. Each parameter is separated by white
79       space. For example:
80
81           extra="foo=bar baz"
82
83       Valid arguments:
84
85       owner_auth=<AUTHSPEC>
86       srk_auth=<AUTHSPEC>
87           Set the owner and SRK authdata for the TPM. If not specified, the
88           default is 160 zero bits (the well-known auth value). Valid values
89           of <AUTHSPEC> are:
90
91           well-known
92               Use the well known auth (default)
93
94           hash:<HASH>
95               Use the given 40-character ASCII hex string
96
97           text:<STR>
98               Use sha1 hash of <STR>.
99
100       tpmdriver=<DRIVER>
101           Choose the driver used for communication with the hardware TPM.
102           Values other than tpm_tis should only be used for testing.
103
104           The possible values of <DRIVER> are:
105
106           tpm_tis
107               Direct communication with a hardware TPM 1.2.  The domain must
108               have access to TPM IO memory. (default)
109
110           tpmfront
111               Use the Xen tpmfront interface to talk to another domain which
112               provides access to the TPM.
113
114       The following options only apply to the tpm_tis driver:
115
116       tpmiomem=<ADDR>
117           The base address of the hardware memory pages of the TPM.  The
118           default is 0xfed40000, as defined by the TCG's PC Client spec.
119
120       tpmirq=<IRQ>
121           The irq of the hardware TPM if using interrupts. A value of "probe"
122           can be set to probe for the irq. A value of 0 disables interrupts
123           and uses polling (default 0).
124
125       tpmlocality=<LOC>
126           Attempt to use locality <LOC> of the hardware TPM.  For full
127           functionality of the TPM Manager, this should be set to "2".
128

Platform Security Assumptions

130       While the TPM Manager has the ability to check the hash of the vTPM
131       requesting a key, there is currently no trusted method to inform the
132       TPM Manager of the hash of each new domain.  Because of this, the TPM
133       Manager trusts the UUID key in Xenstore to identify a vTPM in a trusted
134       manner.  The XSM policy may be used to strengthen this assumption if
135       the creation of vTPM-labeled domains is more constrained (for example,
136       only permitted to a domain builder service): the only grants mapped by
137       the TPM Manager should belong to vTPM domains, so restricting the
138       ability to map other domain's granted pages will prevent other domains
139       from directly requesting keys from the TPM Manager.  The TPM Manager
140       uses the hash of the XSM label of the attached vTPM as the kernel hash,
141       so vTPMs with distinct labels may be further partitioned using vTPM
142       groups.
143
144       A domain with direct access to the hardware TPM will be able to decrypt
145       the TPM Manager's disk image if the haredware TPM's PCR values are in a
146       permitted configuration.  To protect the TPM Manager's data, the list
147       of permitted configurations should be chosen to include PCRs that
148       measure the hypervisor, domain 0, the TPM Manager, and other critical
149       configuration such as the XSM policy.  If the TPM Manager is configured
150       to use locality 2 as recommended, it is safe to permit the hardware
151       domain to access locality 0 (the default in Linux), although concurrent
152       use of the TPM should be avoided as it can result in unexpected busy
153       errors from the TPM driver.  The ability to access locality 2 of the
154       TPM should be enforced using IO memory labeling in the XSM policy; the
155       physical address 0xFED42xxx is always locality 2 for TPMs using the TIS
156       driver.
157

Appendix: unsecured migration process for vtpmmgr domain upgrade

159       There is no direct upgrade supported from previous versions of the
160       vtpmmgr domain due to changes in the on-disk format and the method used
161       to seal data.  If a vTPM domain supports migration, this feature should
162       be used to migrate the vTPM's data; however, the vTPM packaged with Xen
163       does not yet support migration.
164
165       If adding migration support to the vTPM is not desired, a simpler
166       migration domain usable only for local migration can be constructed.
167       The migration process would look like the following:
168
169       1. Start the old vtpmmgr
170       2. Start the vTPM migration domain
171       3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
172       4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
173       5. Start the new vtpmmgr, possibly shutting down the old one first
174       6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
175       7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
176
177       This requires the migration domain to be added to the list of valid
178       vTPM kernel hashes. In the current version of the vtpmmgr domain, this
179       is the hash of the XSM label, not the kernel.
180

Appendix B: vtpmmgr on TPM 2.0

182   Manager disk image setup:
183       The vTPM Manager requires a disk image to store its encrypted data. The
184       image does not require a filesystem and can live anywhere on the host
185       disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using
186       the first 2MB of the image but can support more than 20,000 vTPMs.
187
188           dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
189
190   Manager config file:
191       The vTPM Manager domain (vtpmmgr-stubdom) must be started like any
192       other Xen virtual machine and requires a config file.  The manager
193       requires a disk image for storage and permission to access the hardware
194       memory pages for the TPM. The disk must be presented as "hda", and the
195       TPM memory pages are passed using the iomem configuration parameter.
196       The TPM TIS uses 5 pages of IO memory (one per locality) that start at
197       physical address 0xfed40000. By default, the TPM manager uses locality
198       0 (so only the page at 0xfed40 is needed).
199
200       Add:
201
202            extra="tpm2=1"
203
204       extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it
205       on TPM 1.x. for example:
206
207           kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
208           memory=128
209           disk=["file:/home/vtpm2/vmgr,hda,w"]
210           name="vtpmmgr"
211           iomem=["fed40,5"]
212           extra="tpm2=1"
213
214   Key Hierarchy
215           +------------------+
216           |  vTPM's secrets  | ...
217           +------------------+
218                   |  ^
219                   |  |(Bind / Unbind)
220       - - - - -  -v  |- - - - - - - - TPM 2.0
221           +------------------+
222           |        SK        +
223           +------------------+
224                   |  ^
225                   v  |
226           +------------------+
227           |       SRK        |
228           +------------------+
229                   |  ^
230                   v  |
231           +------------------+
232           | TPM 2.0 Storage  |
233           |   Primary Seed   |
234           +------------------+
235
236       Now the secrets for the vTPMs are only being bound to the presence of
237       thephysical TPM 2.0. Since using PCRs to seal the data can be an
238       important security feature that users of the vtpmmgr rely on. I will
239       replace TPM2_Bind/TPM2_Unbind with TPM2_Seal/TPM2_Unseal to provide as
240       much security as it did for TPM 1.2 in later series of patch.
241
242   Design Overview
243       The architecture of vTPM subsystem on TPM 2.0 is described below:
244
245           +------------------+
246           |    Linux DomU    | ...
247           |       |  ^       |
248           |       v  |       |
249           |   xen-tpmfront   |
250           +------------------+
251                   |  ^
252                   v  |
253           +------------------+
254           | mini-os/tpmback  |
255           |       |  ^       |
256           |       v  |       |
257           |  vtpm-stubdom    | ...
258           |       |  ^       |
259           |       v  |       |
260           | mini-os/tpmfront |
261           +------------------+
262                   |  ^
263                   v  |
264           +------------------+
265           | mini-os/tpmback  |
266           |       |  ^       |
267           |       v  |       |
268           | vtpmmgr-stubdom  |
269           |       |  ^       |
270           |       v  |       |
271           | mini-os/tpm2_tis |
272           +------------------+
273                   |  ^
274                   v  |
275           +------------------+
276           | Hardware TPM 2.0 |
277           +------------------+
278
279       Linux DomU
280           The Linux based guest that wants to use a vTPM. There many be more
281           than one of these.
282
283       xen-tpmfront.ko
284           Linux kernel virtual TPM frontend driver. This driver provides vTPM
285           access to a para-virtualized Linux based DomU.
286
287       mini-os/tpmback
288           Mini-os TPM backend driver. The Linux frontend driver connects to
289           this backend driver to facilitate communications between the Linux
290           DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to
291           communicate with vtpm-stubdom.
292
293       vtpm-stubdom
294           A mini-os stub domain that implements a vTPM. There is a one to one
295           mapping between running vtpm-stubdom instances and logical vtpms on
296           the system. The vTPM Platform Configuration Registers (PCRs) are
297           all initialized to zero.
298
299       mini-os/tpmfront
300           Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom
301           uses this driver to communicate with vtpmmgr-stubdom. This driver
302           could also be used separately to implement a mini-os domain that
303           wishes to use a vTPM of its own.
304
305       vtpmmgr-stubdom
306           A mini-os domain that implements the vTPM manager.  There is only
307           one vTPM manager and it should be running during the entire
308           lifetime of the machine.  This domain regulates access to the
309           physical TPM on the system and secures the persistent state of each
310           vTPM.
311
312       mini-os/tpm2_tis
313           Mini-os TPM version 2.0 TPM Interface Specification (TIS) driver.
314           This driver used by vtpmmgr-stubdom to talk directly to the
315           hardware TPM 2.0. Communication is facilitated by mapping hardware
316           memory pages into vtpmmgr-stubdom.
317
318       Hardware TPM 2.0
319           The physical TPM 2.0 that is soldered onto the motherboard.
320
321       Noted:
322           functionality for a virtual guest operating system (a DomU) is
323       still TPM 1.2.
324
325
326
3274.13.0                            2020-04-14                    xen-vtpmmgr(7)
Impressum