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

NAME

6       xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem
7

RUBRIC

9       Copyright (c) 2010-2012 United States Government, as represented by the
10       Secretary of Defense.  All rights reserved.  November 12 2012 Authors:
11       Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
12
13       This document describes the virtual Trusted Platform Module (vTPM)
14       subsystem for Xen. The reader is assumed to have familiarity with
15       building and installing Xen, Linux, and a basic understanding of the
16       TPM and vTPM concepts.
17

INTRODUCTION

19       The goal of this work is to provide a TPM functionality to a virtual
20       guest operating system (a DomU).  This allows programs to interact with
21       a TPM in a virtual system the same way they interact with a TPM on the
22       physical system.  Each guest gets its own unique, emulated, software
23       TPM.  However, each of the vTPM's secrets (Keys, NVRAM, etc) are
24       managed by a vTPM Manager domain, which seals the secrets to the
25       Physical TPM.  If the process of creating each of these domains
26       (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the
27       chain of trust rooted in the hardware TPM to virtual machines in Xen.
28       Each major component of vTPM is implemented as a separate domain,
29       providing secure separation guaranteed by the hypervisor. The vTPM
30       domains are implemented in mini-os to reduce memory and processor
31       overhead.
32
33       This mini-os vTPM subsystem was built on top of the previous vTPM work
34       done by IBM and Intel corporation.
35

DESIGN OVERVIEW

37       The architecture of vTPM is described below:
38
39           +------------------+
40           |    Linux DomU    | ...
41           |       |  ^       |
42           |       v  |       |
43           |   xen-tpmfront   |
44           +------------------+
45                   |  ^
46                   v  |
47           +------------------+
48           | mini-os/tpmback  |
49           |       |  ^       |
50           |       v  |       |
51           |  vtpm-stubdom    | ...
52           |       |  ^       |
53           |       v  |       |
54           | mini-os/tpmfront |
55           +------------------+
56                   |  ^
57                   v  |
58           +------------------+
59           | mini-os/tpmback  |
60           |       |  ^       |
61           |       v  |       |
62           | vtpmmgr-stubdom  |
63           |       |  ^       |
64           |       v  |       |
65           | mini-os/tpm_tis  |
66           +------------------+
67                   |  ^
68                   v  |
69           +------------------+
70           |   Hardware TPM   |
71           +------------------+
72
73       Linux DomU
74           The Linux based guest that wants to use a vTPM. There many be more
75           than one of these.
76
77       xen-tpmfront.ko
78           Linux kernel virtual TPM frontend driver. This driver provides vTPM
79           access to a para-virtualized Linux based DomU.
80
81       mini-os/tpmback
82           Mini-os TPM backend driver. The Linux frontend driver connects to
83           this backend driver to facilitate communications between the Linux
84           DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to
85           communicate with vtpm-stubdom.
86
87       vtpm-stubdom
88           A mini-os stub domain that implements a vTPM. There is a one to one
89           mapping between running vtpm-stubdom instances and logical vtpms on
90           the system. The vTPM Platform Configuration Registers (PCRs) are
91           all initialized to zero.
92
93       mini-os/tpmfront
94           Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom
95           uses this driver to communicate with vtpmmgr-stubdom. This driver
96           could also be used separately to implement a mini-os domain that
97           wishes to use a vTPM of its own.
98
99       vtpmmgr-stubdom
100           A mini-os domain that implements the vTPM manager.  There is only
101           one vTPM manager and it should be running during the entire
102           lifetime of the machine.  This domain regulates access to the
103           physical TPM on the system and secures the persistent state of each
104           vTPM.
105
106       mini-os/tpm_tis
107           Mini-os TPM version 1.2 TPM Interface Specification (TIS) driver.
108           This driver used by vtpmmgr-stubdom to talk directly to the
109           hardware TPM. Communication is facilitated by mapping hardware
110           memory pages into vtpmmgr-stubdom.
111
112       Hardware TPM
113           The physical TPM that is soldered onto the motherboard.
114

INSTALLATION

116   Prerequisites:
117       You must have an x86 machine with a TPM on the motherboard.  The only
118       extra software requirement for compiling vTPM is cmake.  You must use
119       libxl to manage domains with vTPMs; 'xm' is deprecated and does not
120       support vTPMs.
121
122   Compiling the Xen tree:
123       Compile and install the Xen tree as usual; be sure that the vTPM
124       domains are enabled when you run configure.
125
126   Compiling the LINUX dom0 kernel:
127       Because the TPM manager uses direct access to the physical TPM, it may
128       interfere with access to the TPM by dom0.  The simplest solution for
129       this is to prevent dom0 from accessing the physical TPM by compiling
130       the kernel without a driver or blacklisting the module.  If dom0 needs
131       a TPM but does not need to use it during the boot process (i.e. it is
132       not using IMA), a virtual TPM can be attached to dom0 after the system
133       is booted.
134
135       Access to the physical TPM may be required in order to manage the NVRAM
136       or to perform other advanced operations where the vTPM is insufficient.
137       In order to prevent interference, the TPM Manager and dom0 should use
138       different values for the TPM's locality; since Linux always uses
139       locality 0, using locality 2 for the TPM Manager is recommended.  If
140       both Linux and the TPM Manager attempt to access the TPM at the same
141       time, the TPM device will return a busy status; some applications will
142       consider this a fatal error instead of retrying the command at a later
143       time.  If a vTPM gets an error when loading its key, it will currently
144       generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).
145
146   Compiling the LINUX domU kernel:
147       The domU kernel used by domains with vtpms must include the
148       xen-tpmfront.ko driver. It can be built directly into the kernel or as
149       a module; however, some features such as IMA require the TPM to be
150       built in to the kernel.
151
152           CONFIG_TCG_TPM=y
153           CONFIG_TCG_XEN=y
154

VTPM MANAGER SETUP

156   Manager disk image setup:
157       The vTPM Manager requires a disk image to store its encrypted data. The
158       image does not require a filesystem and can live anywhere on the host
159       disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using
160       the first 2MB of the image but can support more than 20,000 vTPMs.
161
162   Manager config file:
163       The vTPM Manager domain (vtpmmgr-stubdom) must be started like any
164       other Xen virtual machine and requires a config file.  The manager
165       requires a disk image for storage and permission to access the hardware
166       memory pages for the TPM. The disk must be presented as "hda", and the
167       TPM memory pages are passed using the iomem configuration parameter.
168       The TPM TIS uses 5 pages of IO memory (one per locality) that start at
169       physical address 0xfed40000. By default, the TPM manager uses locality
170       0 (so only the page at 0xfed40 is needed); this can be changed on the
171       domain's command line.  For full functionality in deep quotes, using
172       locality 2 is required to manipulate PCR 20-22.
173
174   Starting and stopping the manager:
175       The vTPM manager should be started at boot; you may wish to create an
176       init script to do this.  If a domain builder is used, the TPM Manager
177       should be started by the domain builder to minimize the trusted
178       computing base for the vTPM manager's secrets.
179
180       Once initialization is complete you should see the following:
181
182           INFO[VTPM]: Waiting for commands from vTPM's:
183
184       The TPM Manager does not respond to shutdown requests; use the destroy
185       command to shut it down.
186

VTPM AND LINUX PVM SETUP

188   vTPM disk image setup:
189       The vTPM requires a disk image to store its persistent data (RSA keys,
190       NVRAM, etc). The image does not require a filesystem. The image does
191       not need to be large; 2 Mb should be sufficient.
192
193   vTPM config file:
194       The vTPM domain requires a configuration file like any other domain.
195       The vTPM requires a disk image for storage and a TPM frontend driver to
196       communicate with the manager.  You are required to generate a uuid for
197       this vtpm, which is specified on the "vtpm=" line that describes its
198       connection to the vTPM Manager.  The uuidgen application may be used to
199       generate a uuid, or one from the output of the "manage-vtpmmgr.pl
200       vtpm-add" command may be used to create a vTPM belonging to a specific
201       group.
202
203       If you wish to clear the vTPM data you can either recreate the disk
204       image or change the uuid.
205
206   Linux Guest config file:
207       The Linux guest config file needs to be modified to include the Linux
208       tpmfront driver. Add the following line:
209
210           vtpm=["backend=domu-vtpm"]
211
212       Currently only Linux guests are supported (PV or HVM with PV drivers).
213
214       While attaching a vTPM after a guest is booted (using xl vtpm-attach)
215       is supported, the attached vTPM will not have a record of the boot of
216       the attached guest.  Furthermore, if the vTPM has been freshly created,
217       a malicious guest could then extend any values into PCRs, potentially
218       forging its boot configuration.  Attaching a vTPM to a running domain
219       should only be used for trusted domains or when measurements have
220       already been sent to the vTPM from another source.
221
222   Using the vTPM in the guest:
223       If xen-tpmfront was compiled as a module, it must be loaded it in the
224       guest.
225
226           # modprobe xen-tpmfront
227
228       After the Linux domain boots and the xen-tpmfront driver is loaded, you
229       should see the following on the vtpm console:
230
231           Info: VTPM attached to Frontend X/Y
232
233       You can quickly test the vTPM by using the sysfs interface:
234
235           # cat /sys/devices/vtpm-0/pubek
236           # cat /sys/devices/vtpm-0/pcrs
237
238       If you have trousers and tpm_tools installed on the guest, the
239       tpm_version command should return the following:
240
241       The version command should return the following:
242
243           TPM 1.2 Version Info:
244           Chip Version:        1.2.0.7
245           Spec Level:          2
246           Errata Revision:     1
247           TPM Vendor ID:       ETHZ
248           TPM Version:         01010000
249           Manufacturer Info:   4554485a
250
251       You should also see the command being sent to the vtpm console as well
252       as the vtpm saving its state. You should see the vtpm key being
253       encrypted and stored on the vtpmmgr console.
254
255       You may wish to write a script to start your vtpm and guest together
256       and to destroy the vtpm when the guest shuts down.
257

INTEGRATION WITH PV-GRUB

259       The vTPM currently starts up with all PCRs set to their default values
260       (all zeros for the lower 16).  This means that any decisions about the
261       trustworthiness of the created domain must be made based on the
262       environment that created the vTPM and the domU; for example, a system
263       that only constructs images using a trusted configuration and guest
264       kernel be able to provide guarantees about the guests and any
265       measurements done that kernel (such as the IMA TCB log).  Guests
266       wishing to use a custom kernel in such a secure environment are often
267       started using the pv-grub bootloader as the kernel, which then can load
268       the untrusted kernel without needing to parse an untrusted filesystem
269       and kernel in dom0.  If the pv-grub stub domain succeeds in connecting
270       to a vTPM, it will extend the hash of the kernel that it boots into PCR
271       #4, and will extend the command line and initrd into PCR #5 before
272       booting so that a domU booted in this way can attest to its early boot
273       state.
274

MORE INFORMATION

276       See <xen-vtpmmgr(7)> for more details about how the manager domain
277       works, how to use it, and its command line parameters.
278

VTPM DOMAIN OPERATION

280       The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest
281       OS to use. It is a small wrapper around the Berlios TPM emulator
282       version 0.7.4.  Commands are passed from the linux guest via the mini-
283       os TPM backend driver.  vTPM data is encrypted and stored via a disk
284       image provided to the virtual machine. The key used to encrypt the data
285       along with a hash of the vTPM's data is sent to the vTPM manager for
286       secure storage and later retrieval.  The vTPM domain communicates with
287       the manager using a mini-os tpm front/back device pair.
288

VTPM DOMAIN COMMAND LINE ARGUMENTS

290       Command line arguments are passed to the domain via the 'extra'
291       parameter in the VM config file. Each parameter is separated by white
292       space. For example:
293
294           extra="foo=bar baz"
295
296   List of Arguments:
297       loglevel=<LOG>
298           Controls the amount of logging printed to the console.  The
299           possible values for <LOG> are:
300
301           •   error
302
303           •   info (default)
304
305           •   debug
306
307       clear
308           Start the Berlios emulator in "clear" mode. (default)
309
310       save
311           Start the Berlios emulator in "save" mode.
312
313       deactivated
314           Start the Berlios emulator in "deactivated" mode.  See the Berlios
315           TPM emulator documentation for details about the startup mode. For
316           all normal use, always use clear which is the default. You should
317           not need to specify any of these.
318
319       maintcmds=<1|0>
320           Enable to disable the TPM maintenance commands.  These commands are
321           used by tpm manufacturers and thus open a security hole. They are
322           disabled by default.
323
324       hwinitpcr=<PCRSPEC>
325           Initialize the virtual Platform Configuration Registers (PCRs) with
326           PCR values from the hardware TPM. Each pcr specified by <PCRSPEC>
327           will be initialized with the value of that same PCR in TPM once at
328           startup. By default all PCRs are zero initialized.  Possible values
329           of <PCRSPEC> are:
330
331           •   all: copy all pcrs
332
333           •   none: copy no pcrs (default)
334
335           •   <N>: copy pcr n
336
337           •   <X-Y>: copy pcrs x to y (inclusive)
338
339           These can also be combined by comma separation, for example:
340           "hwinitpcrs=5,12-16" will copy pcrs 5, 12, 13, 14, 15, and 16.
341

REFERENCES

343       Berlios TPM Emulator: <https://github.com/PeterHuewe/tpm-emulator>
344
345
346
3474.16.3                            2022-12-19                       xen-vtpm(7)
Impressum