1=head1 NAME
2
3xen-vtpmgr - Xen virtual TPM stubdomain
4
5=head1 Authors
6
7=over 4
8
9=item Daniel De Graaf <dgdegra@tycho.nsa.gov>
10
11=item Quan Xu <quan.xu@intel.com>
12
13=back
14
15This document describes the operation and command line interface of
16vtpmmgr-stubdom. See L<xen-vtpm(7)> for details on the vTPM subsystem as a
17whole.
18
19=head1 Overview
20
21The TPM Manager has three primary functions:
22
23=over 4
24
25=item 1. Securely store the encryption keys for vTPMs
26
27=item 2. Provide a single controlled path of access to the physical TPM
28
29=item 3. Provide evidence (via TPM Quotes) of the current configuration
30
31=back
32
33When combined with a platform that provides a trusted method for creating
34domains, the TPM Manager provides assurance that the private keys in a vTPM are
35only available in specific trusted configurations.
36
37The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM
38backend driver. The vTPM manager communicates directly with hardware TPM using
39the mini-os tpm_tis driver.
40
41=head1 Boot Configurations and TPM Groups
42
43The TPM Manager's data is secured by using the physical TPM's seal operation,
44which allows data to be bound to specific PCRs. These PCRs are populated in the
45physical TPM during the boot process, either by the firmware/BIOS or by a
46dynamic launch environment such as TBOOT. In order to provide assurance of the
47system's security, the PCRs used to seal the TPM manager's data must contain
48measurements for domains used to bootstrap the TPM Manager and vTPMs.
49
50Because these measurements are based on hashes, they will change any time that
51any component of the system is upgraded. Since it is not possible to construct a
52list of all possible future good measurements, the job of approving
53configurations is delegated to a third party, referred to here as the system
54approval agent (SAA). The SAA is identified by its public (RSA) signature key,
55which is used to sign lists of valid configurations. A single TPM manager can
56support multiple SAAs via the use of vTPM groups. Each group is associated with
57a single SAA; this allows the creation of a multi-tenant environment where
58tenants may not all choose to trust the same SAA.
59
60Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group
61has its own AIK in the physical TPM for quotes of the hardware TPM state; when
62used with a conforming Privacy CA, this allows each group on the system to form
63the basis of a distinct identity.
64
65=head1 Initial Provisioning
66
67When the TPM Manager first boots up, it will create a stub vTPM group along with
68entries for any vTPMs that communicate with it. This stub group must be
69provisioned with an SAA and a boot configuration in order to survive a reboot.
70
71When a vTPM is connected to the TPM Manager using a UUID that is not recognized,
72a slot will be created in group 0 for it. In the future, this auto-creation may
73be restricted to specific UUIDs (such as the all-zero UUID) to enforce the use
74of the TPM manager as the generator of the UUID. The first vTPM to be connected
75is given administrative privileges for the TPM Manager, and should be attached
76to dom0 or a control domain in order to send provisioning commands.
77
78Provisioning a vTPM group for the system requires the public key of the SAA and
79privacy CA data used to certify the AIK (see the TPM spec for details). Once the
80group is created, a signed list of boot measurements can be installed. The
81initial group controls the ability to boot the system as a whole, and cannot be
82deleted once provisioned.
83
84=head1 Command Line Arguments
85
86Command line arguments are passed to the domain via the 'extra' parameter in the
87VM config file. Each parameter is separated by white space. For example:
88
89    extra="foo=bar baz"
90
91Valid arguments:
92
93=over 4
94
95=item owner_auth=<AUTHSPEC>
96
97=item srk_auth=<AUTHSPEC>
98
99Set the owner and SRK authdata for the TPM. If not specified, the
100default is 160 zero bits (the well-known auth value). Valid values of
101<AUTHSPEC> are:
102
103=over 4
104
105=item well-known
106
107Use the well known auth (default)
108
109=item hash:<HASH>
110
111Use the given 40-character ASCII hex string
112
113=item text:<STR>
114
115Use sha1 hash of <STR>.
116
117=back
118
119=item tpmdriver=<DRIVER>
120
121Choose the driver used for communication with the hardware TPM. Values
122other than tpm_tis should only be used for testing.
123
124The possible values of <DRIVER> are:
125
126=over 4
127
128=item tpm_tis
129
130Direct communication with a hardware TPM 1.2.  The
131domain must have access to TPM IO memory. (default)
132
133=item tpmfront
134
135Use the Xen tpmfront interface to talk to another
136domain which provides access to the TPM.
137
138=back
139
140=back
141
142The following options only apply to the tpm_tis driver:
143
144=over 4
145
146=item tpmiomem=<ADDR>
147
148The base address of the hardware memory pages of the TPM.
149The default is 0xfed40000, as defined by the TCG's PC Client spec.
150
151=item tpmirq=<IRQ>
152
153The irq of the hardware TPM if using interrupts. A value of
154"probe" can be set to probe for the irq. A value of 0 disables
155interrupts and uses polling (default 0).
156
157=item tpmlocality=<LOC>
158
159Attempt to use locality <LOC> of the hardware TPM.
160For full functionality of the TPM Manager, this should be set to "2".
161
162=back
163
164=head1 Platform Security Assumptions
165
166While the TPM Manager has the ability to check the hash of the vTPM requesting a
167key, there is currently no trusted method to inform the TPM Manager of the hash
168of each new domain.  Because of this, the TPM Manager trusts the UUID key in
169Xenstore to identify a vTPM in a trusted manner.  The XSM policy may be used to
170strengthen this assumption if the creation of vTPM-labeled domains is more
171constrained (for example, only permitted to a domain builder service): the only
172grants mapped by the TPM Manager should belong to vTPM domains, so restricting
173the ability to map other domain's granted pages will prevent other domains from
174directly requesting keys from the TPM Manager.  The TPM Manager uses the hash of
175the XSM label of the attached vTPM as the kernel hash, so vTPMs with distinct
176labels may be further partitioned using vTPM groups.
177
178A domain with direct access to the hardware TPM will be able to decrypt the TPM
179Manager's disk image if the haredware TPM's PCR values are in a permitted
180configuration.  To protect the TPM Manager's data, the list of permitted
181configurations should be chosen to include PCRs that measure the hypervisor,
182domain 0, the TPM Manager, and other critical configuration such as the XSM
183policy.  If the TPM Manager is configured to use locality 2 as recommended, it
184is safe to permit the hardware domain to access locality 0 (the default in
185Linux), although concurrent use of the TPM should be avoided as it can result in
186unexpected busy errors from the TPM driver.  The ability to access locality 2 of
187the TPM should be enforced using IO memory labeling in the XSM policy; the
188physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver.
189
190=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade
191
192There is no direct upgrade supported from previous versions of the vtpmmgr
193domain due to changes in the on-disk format and the method used to seal data.
194If a vTPM domain supports migration, this feature should be used to migrate the
195vTPM's data; however, the vTPM packaged with Xen does not yet support migration.
196
197If adding migration support to the vTPM is not desired, a simpler migration
198domain usable only for local migration can be constructed. The migration process
199would look like the following:
200
201=over 4
202
203=item 1. Start the old vtpmmgr
204
205=item 2. Start the vTPM migration domain
206
207=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
208
209=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
210
211=item 5. Start the new vtpmmgr, possibly shutting down the old one first
212
213=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
214
215=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
216
217=back
218
219This requires the migration domain to be added to the list of valid vTPM kernel
220hashes. In the current version of the vtpmmgr domain, this is the hash of the
221XSM label, not the kernel.
222
223=head1 Appendix B: vtpmmgr on TPM 2.0
224
225=head2 Manager disk image setup:
226
227The vTPM Manager requires a disk image to store its encrypted data. The image
228does not require a filesystem and can live anywhere on the host disk. The image
229is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
230but can support more than 20,000 vTPMs.
231
232    dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
233
234=head2 Manager config file:
235
236The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
237virtual machine and requires a config file.  The manager requires a disk image
238for storage and permission to access the hardware memory pages for the TPM. The
239disk must be presented as "hda", and the TPM memory pages are passed using the
240iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per
241locality) that start at physical address 0xfed40000. By default, the TPM manager
242uses locality 0 (so only the page at 0xfed40 is needed).
243
244Add:
245
246     extra="tpm2=1"
247
248extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
2491.x. for example:
250
251    kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
252    memory=128
253    disk=["file:/home/vtpm2/vmgr,hda,w"]
254    name="vtpmmgr"
255    iomem=["fed40,5"]
256    extra="tpm2=1"
257
258
259=head2 Key Hierarchy
260
261    +------------------+
262    |  vTPM's secrets  | ...
263    +------------------+
264            |  ^
265            |  |(Bind / Unbind)
266- - - - -  -v  |- - - - - - - - TPM 2.0
267    +------------------+
268    |        SK        +
269    +------------------+
270            |  ^
271            v  |
272    +------------------+
273    |       SRK        |
274    +------------------+
275            |  ^
276            v  |
277    +------------------+
278    | TPM 2.0 Storage  |
279    |   Primary Seed   |
280    +------------------+
281
282Now the secrets for the vTPMs are only being bound to the presence of thephysical
283TPM 2.0. Since using PCRs to seal the data can be an important security feature
284that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with
285TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later
286series of patch.
287
288=head2 Design Overview
289
290The architecture of vTPM subsystem on TPM 2.0 is described below:
291
292    +------------------+
293    |    Linux DomU    | ...
294    |       |  ^       |
295    |       v  |       |
296    |   xen-tpmfront   |
297    +------------------+
298            |  ^
299            v  |
300    +------------------+
301    | mini-os/tpmback  |
302    |       |  ^       |
303    |       v  |       |
304    |  vtpm-stubdom    | ...
305    |       |  ^       |
306    |       v  |       |
307    | mini-os/tpmfront |
308    +------------------+
309            |  ^
310            v  |
311    +------------------+
312    | mini-os/tpmback  |
313    |       |  ^       |
314    |       v  |       |
315    | vtpmmgr-stubdom  |
316    |       |  ^       |
317    |       v  |       |
318    | mini-os/tpm2_tis |
319    +------------------+
320            |  ^
321            v  |
322    +------------------+
323    | Hardware TPM 2.0 |
324    +------------------+
325
326=over 4
327
328=item Linux DomU
329
330The Linux based guest that wants to use a vTPM. There many be
331more than one of these.
332
333=item xen-tpmfront.ko
334
335Linux kernel virtual TPM frontend driver. This driver
336provides vTPM access to a para-virtualized Linux based DomU.
337
338=item mini-os/tpmback
339
340Mini-os TPM backend driver. The Linux frontend driver
341connects to this backend driver to facilitate
342communications between the Linux DomU and its vTPM. This
343driver is also used by vtpmmgr-stubdom to communicate with
344vtpm-stubdom.
345
346=item vtpm-stubdom
347
348A mini-os stub domain that implements a vTPM. There is a
349one to one mapping between running vtpm-stubdom instances and
350logical vtpms on the system. The vTPM Platform Configuration
351Registers (PCRs) are all initialized to zero.
352
353=item mini-os/tpmfront
354
355Mini-os TPM frontend driver. The vTPM mini-os domain
356vtpm-stubdom uses this driver to communicate with
357vtpmmgr-stubdom. This driver could also be used separately to
358implement a mini-os domain that wishes to use a vTPM of
359its own.
360
361=item vtpmmgr-stubdom
362
363A mini-os domain that implements the vTPM manager.
364There is only one vTPM manager and it should be running during
365the entire lifetime of the machine.  This domain regulates
366access to the physical TPM on the system and secures the
367persistent state of each vTPM.
368
369=item mini-os/tpm2_tis
370
371Mini-os TPM version 2.0 TPM Interface Specification (TIS)
372driver. This driver used by vtpmmgr-stubdom to talk directly
373to the hardware TPM 2.0. Communication is facilitated by mapping
374hardware memory pages into vtpmmgr-stubdom.
375
376=item Hardware TPM 2.0
377
378The physical TPM 2.0 that is soldered onto the motherboard.
379
380=back
381
382Noted:
383    functionality for a virtual guest operating system (a DomU) is still TPM 1.2.
384