1xen-vtpmmgr(7) Xen xen-vtpmmgr(7)
2
6 xen-vtpmgr - Xen virtual TPM stubdomain
7
9 Daniel De Graaf <dgdegra@tycho.nsa.gov>
10 Quan Xu <quan.xu@intel.com>
11 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
17 The TPM Manager has three primary functions:
18 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 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 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
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 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 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
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 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 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
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 extra="foo=bar baz"
82 Valid arguments:
84 srk_handle=<HANDLE>
86 Specify a srk_handle for TPM 2.0. TPM 2.0 uses a key hierarchy,
87 and this allow specifying the parent handle for vtpmmgr to create
88 its own key under. Using this option bypasses vtpmmgr trying to
89 take ownership of the TPM.
90 owner_auth=<AUTHSPEC>
92 srk_auth=<AUTHSPEC>
93 Set the owner and SRK authdata for the TPM. If not specified, the
94 default is 160 zero bits (the well-known auth value). Valid values
95 of <AUTHSPEC> are:
96 well-known
98 Use the well known auth (default)
99 hash:<HASH>
101 Use the given 40-character ASCII hex string
102 text:<STR>
104 Use sha1 hash of <STR>.
105 tpmdriver=<DRIVER>
107 Choose the driver used for communication with the hardware TPM.
108 Values other than tpm_tis should only be used for testing.
109 The possible values of <DRIVER> are:
111 tpm_tis
113 Direct communication with a hardware TPM 1.2. The domain must
114 have access to TPM IO memory. (default)
115 tpmfront
117 Use the Xen tpmfront interface to talk to another domain which
118 provides access to the TPM.
119 The following options only apply to the tpm_tis driver:
121 tpmiomem=<ADDR>
123 The base address of the hardware memory pages of the TPM. The
124 default is 0xfed40000, as defined by the TCG's PC Client spec.
125 tpmirq=<IRQ>
127 The irq of the hardware TPM if using interrupts. A value of "probe"
128 can be set to probe for the irq. A value of 0 disables interrupts
129 and uses polling (default 0).
130 tpmlocality=<LOC>
132 Attempt to use locality <LOC> of the hardware TPM. For full
133 functionality of the TPM Manager, this should be set to "2".
134
136 While the TPM Manager has the ability to check the hash of the vTPM
137 requesting a key, there is currently no trusted method to inform the
138 TPM Manager of the hash of each new domain. Because of this, the TPM
139 Manager trusts the UUID key in Xenstore to identify a vTPM in a trusted
140 manner. The XSM policy may be used to strengthen this assumption if
141 the creation of vTPM-labeled domains is more constrained (for example,
142 only permitted to a domain builder service): the only grants mapped by
143 the TPM Manager should belong to vTPM domains, so restricting the
144 ability to map other domain's granted pages will prevent other domains
145 from directly requesting keys from the TPM Manager. The TPM Manager
146 uses the hash of the XSM label of the attached vTPM as the kernel hash,
147 so vTPMs with distinct labels may be further partitioned using vTPM
148 groups.
149 A domain with direct access to the hardware TPM will be able to decrypt
151 the TPM Manager's disk image if the haredware TPM's PCR values are in a
152 permitted configuration. To protect the TPM Manager's data, the list
153 of permitted configurations should be chosen to include PCRs that
154 measure the hypervisor, domain 0, the TPM Manager, and other critical
155 configuration such as the XSM policy. If the TPM Manager is configured
156 to use locality 2 as recommended, it is safe to permit the hardware
157 domain to access locality 0 (the default in Linux), although concurrent
158 use of the TPM should be avoided as it can result in unexpected busy
159 errors from the TPM driver. The ability to access locality 2 of the
160 TPM should be enforced using IO memory labeling in the XSM policy; the
161 physical address 0xFED42xxx is always locality 2 for TPMs using the TIS
162 driver.
163
165 There is no direct upgrade supported from previous versions of the
166 vtpmmgr domain due to changes in the on-disk format and the method used
167 to seal data. If a vTPM domain supports migration, this feature should
168 be used to migrate the vTPM's data; however, the vTPM packaged with Xen
169 does not yet support migration.
170 If adding migration support to the vTPM is not desired, a simpler
172 migration domain usable only for local migration can be constructed.
173 The migration process would look like the following:
174 1. Start the old vtpmmgr
176 2. Start the vTPM migration domain
177 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
178 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
179 5. Start the new vtpmmgr, possibly shutting down the old one first
180 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
181 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
182 This requires the migration domain to be added to the list of valid
184 vTPM kernel hashes. In the current version of the vtpmmgr domain, this
185 is the hash of the XSM label, not the kernel.
186
188 WARNING: Incomplete - cannot persist data
189 TPM 2.0 support for vTPM manager is incomplete. There is no support
190 for persisting an encryption key, so vTPM manager regenerates primary
191 and secondary key handles each boot.
192 Also, the vTPM manger group command implementation hardcodes TPM 1.2
194 commands. This means running manage-vtpmmgr.pl fails when the TPM 2.0
195 hardware rejects the TPM 1.2 commands. vTPM manager with TPM 2.0
196 cannot create groups and therefore cannot persist vTPM contents.
197 Manager disk image setup:
199 The vTPM Manager requires a disk image to store its encrypted data. The
200 image does not require a filesystem and can live anywhere on the host
201 disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using
202 the first 2MB of the image but can support more than 20,000 vTPMs.
203 dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
205 Manager config file:
207 The vTPM Manager domain (vtpmmgr-stubdom) must be started like any
208 other Xen virtual machine and requires a config file. The manager
209 requires a disk image for storage and permission to access the hardware
210 memory pages for the TPM. The disk must be presented as "hda", and the
211 TPM memory pages are passed using the iomem configuration parameter.
212 The TPM TIS uses 5 pages of IO memory (one per locality) that start at
213 physical address 0xfed40000. By default, the TPM manager uses locality
214 0 (so only the page at 0xfed40 is needed).
215 Add:
217 extra="tpm2=1"
219 extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it
221 on TPM 1.x. for example:
222 kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
224 memory=128
225 disk=["file:/home/vtpm2/vmgr,hda,w"]
226 name="vtpmmgr"
227 iomem=["fed40,5"]
228 extra="tpm2=1"
229 Key Hierarchy
231 +------------------+
232 | vTPM's secrets | ...
233 +------------------+
234 | ^
235 | |(Bind / Unbind)
236 - - - - - -v |- - - - - - - - TPM 2.0
237 +------------------+
238 | SK +
239 +------------------+
240 | ^
241 v |
242 +------------------+
243 | SRK |
244 +------------------+
245 | ^
246 v |
247 +------------------+
248 | TPM 2.0 Storage |
249 | Primary Seed |
250 +------------------+
251 Now the secrets for the vTPMs are only being bound to the presence of
253 thephysical TPM 2.0. Since using PCRs to seal the data can be an
254 important security feature that users of the vtpmmgr rely on. I will
255 replace TPM2_Bind/TPM2_Unbind with TPM2_Seal/TPM2_Unseal to provide as
256 much security as it did for TPM 1.2 in later series of patch.
257 Design Overview
259 The architecture of vTPM subsystem on TPM 2.0 is described below:
260 +------------------+
262 | Linux DomU | ...
263 | | ^ |
264 | v | |
265 | xen-tpmfront |
266 +------------------+
267 | ^
268 v |
269 +------------------+
270 | mini-os/tpmback |
271 | | ^ |
272 | v | |
273 | vtpm-stubdom | ...
274 | | ^ |
275 | v | |
276 | mini-os/tpmfront |
277 +------------------+
278 | ^
279 v |
280 +------------------+
281 | mini-os/tpmback |
282 | | ^ |
283 | v | |
284 | vtpmmgr-stubdom |
285 | | ^ |
286 | v | |
287 | mini-os/tpm2_tis |
288 +------------------+
289 | ^
290 v |
291 +------------------+
292 | Hardware TPM 2.0 |
293 +------------------+
294 Linux DomU
296 The Linux based guest that wants to use a vTPM. There many be more
297 than one of these.
298 xen-tpmfront.ko
300 Linux kernel virtual TPM frontend driver. This driver provides vTPM
301 access to a para-virtualized Linux based DomU.
302 mini-os/tpmback
304 Mini-os TPM backend driver. The Linux frontend driver connects to
305 this backend driver to facilitate communications between the Linux
306 DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to
307 communicate with vtpm-stubdom.
308 vtpm-stubdom
310 A mini-os stub domain that implements a vTPM. There is a one to one
311 mapping between running vtpm-stubdom instances and logical vtpms on
312 the system. The vTPM Platform Configuration Registers (PCRs) are
313 all initialized to zero.
314 mini-os/tpmfront
316 Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom
317 uses this driver to communicate with vtpmmgr-stubdom. This driver
318 could also be used separately to implement a mini-os domain that
319 wishes to use a vTPM of its own.
320 vtpmmgr-stubdom
322 A mini-os domain that implements the vTPM manager. There is only
323 one vTPM manager and it should be running during the entire
324 lifetime of the machine. This domain regulates access to the
325 physical TPM on the system and secures the persistent state of each
326 vTPM.
327 mini-os/tpm2_tis
329 Mini-os TPM version 2.0 TPM Interface Specification (TIS) driver.
330 This driver used by vtpmmgr-stubdom to talk directly to the
331 hardware TPM 2.0. Communication is facilitated by mapping hardware
332 memory pages into vtpmmgr-stubdom.
333 Hardware TPM 2.0
335 The physical TPM 2.0 that is soldered onto the motherboard.
336 Noted:
338 functionality for a virtual guest operating system (a DomU) is
339 still TPM 1.2.
3404.16.3 2022-12-19 xen-vtpmmgr(7)