1xen-vtpm(7) Xen xen-vtpm(7)
2
6 The goal of this work is to provide a TPM functionality to a virtual
7 guest operating system (a DomU). This allows programs to interact with
8 a TPM in a virtual system the same way they interact with a TPM on the
9 physical system. Each guest gets its own unique, emulated, software
10 TPM. However, each of the vTPM's secrets (Keys, NVRAM, etc) are
11 managed by a vTPM Manager domain, which seals the secrets to the
12 Physical TPM. If the process of creating each of these domains
13 (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the
14 chain of trust rooted in the hardware TPM to virtual machines in Xen.
15 Each major component of vTPM is implemented as a separate domain,
16 providing secure separation guaranteed by the hypervisor. The vTPM
17 domains are implemented in mini-os to reduce memory and processor
18 overhead.
19 This mini-os vTPM subsystem was built on top of the previous vTPM work
21 done by IBM and Intel corporation.
22
24 The architecture of vTPM is described below:
25 +------------------+
27 | Linux DomU | ...
28 | | ^ |
29 | v | |
30 | xen-tpmfront |
31 +------------------+
32 | ^
33 v |
34 +------------------+
35 | mini-os/tpmback |
36 | | ^ |
37 | v | |
38 | vtpm-stubdom | ...
39 | | ^ |
40 | v | |
41 | mini-os/tpmfront |
42 +------------------+
43 | ^
44 v |
45 +------------------+
46 | mini-os/tpmback |
47 | | ^ |
48 | v | |
49 | vtpmmgr-stubdom |
50 | | ^ |
51 | v | |
52 | mini-os/tpm_tis |
53 +------------------+
54 | ^
55 v |
56 +------------------+
57 | Hardware TPM |
58 +------------------+
59 Linux DomU
61 The Linux based guest that wants to use a vTPM. There many be more
62 than one of these.
63 xen-tpmfront.ko
65 Linux kernel virtual TPM frontend driver. This driver provides vTPM
66 access to a para-virtualized Linux based DomU.
67 mini-os/tpmback
69 Mini-os TPM backend driver. The Linux frontend driver connects to
70 this backend driver to facilitate communications between the Linux
71 DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to
72 communicate with vtpm-stubdom.
73 vtpm-stubdom
75 A mini-os stub domain that implements a vTPM. There is a one to one
76 mapping between running vtpm-stubdom instances and logical vtpms on
77 the system. The vTPM Platform Configuration Registers (PCRs) are
78 all initialized to zero.
79 mini-os/tpmfront
81 Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom
82 uses this driver to communicate with vtpmmgr-stubdom. This driver
83 could also be used separately to implement a mini-os domain that
84 wishes to use a vTPM of its own.
85 vtpmmgr-stubdom
87 A mini-os domain that implements the vTPM manager. There is only
88 one vTPM manager and it should be running during the entire
89 lifetime of the machine. This domain regulates access to the
90 physical TPM on the system and secures the persistent state of each
91 vTPM.
92 mini-os/tpm_tis
94 Mini-os TPM version 1.2 TPM Interface Specification (TIS) driver.
95 This driver used by vtpmmgr-stubdom to talk directly to the
96 hardware TPM. Communication is facilitated by mapping hardware
97 memory pages into vtpmmgr-stubdom.
98 Hardware TPM
100 The physical TPM that is soldered onto the motherboard.
101
103 Prerequisites:
104 You must have an x86 machine with a TPM on the motherboard. The only
105 extra software requirement for compiling vTPM is cmake. You must use
106 libxl to manage domains with vTPMs; 'xm' is deprecated and does not
107 support vTPMs.
108 Compiling the Xen tree:
110 Compile and install the Xen tree as usual; be sure that the vTPM
111 domains are enabled when you run configure.
112 Compiling the LINUX dom0 kernel:
114 Because the TPM manager uses direct access to the physical TPM, it may
115 interfere with access to the TPM by dom0. The simplest solution for
116 this is to prevent dom0 from accessing the physical TPM by compiling
117 the kernel without a driver or blacklisting the module. If dom0 needs
118 a TPM but does not need to use it during the boot process (i.e. it is
119 not using IMA), a virtual TPM can be attached to dom0 after the system
120 is booted.
121 Access to the physical TPM may be required in order to manage the NVRAM
123 or to perform other advanced operations where the vTPM is insufficient.
124 In order to prevent interference, the TPM Manager and dom0 should use
125 different values for the TPM's locality; since Linux always uses
126 locality 0, using locality 2 for the TPM Manager is recommended. If
127 both Linux and the TPM Manager attempt to access the TPM at the same
128 time, the TPM device will return a busy status; some applications will
129 consider this a fatal error instead of retrying the command at a later
130 time. If a vTPM gets an error when loading its key, it will currently
131 generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).
132 Compiling the LINUX domU kernel:
134 The domU kernel used by domains with vtpms must include the
135 xen-tpmfront.ko driver. It can be built directly into the kernel or as
136 a module; however, some features such as IMA require the TPM to be
137 built in to the kernel.
138 CONFIG_TCG_TPM=y
140 CONFIG_TCG_XEN=y
141
143 Manager disk image setup:
144 The vTPM Manager requires a disk image to store its encrypted data. The
145 image does not require a filesystem and can live anywhere on the host
146 disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using
147 the first 2MB of the image but can support more than 20,000 vTPMs.
148 Manager config file:
150 The vTPM Manager domain (vtpmmgr-stubdom) must be started like any
151 other Xen virtual machine and requires a config file. The manager
152 requires a disk image for storage and permission to access the hardware
153 memory pages for the TPM. The disk must be presented as "hda", and the
154 TPM memory pages are passed using the iomem configuration parameter.
155 The TPM TIS uses 5 pages of IO memory (one per locality) that start at
156 physical address 0xfed40000. By default, the TPM manager uses locality
157 0 (so only the page at 0xfed40 is needed); this can be changed on the
158 domain's command line. For full functionality in deep quotes, using
159 locality 2 is required to manipulate PCR 20-22.
160 Starting and stopping the manager:
162 The vTPM manager should be started at boot; you may wish to create an
163 init script to do this. If a domain builder is used, the TPM Manager
164 should be started by the domain builder to minimize the trusted
165 computing base for the vTPM manager's secrets.
166 Once initialization is complete you should see the following:
168 INFO[VTPM]: Waiting for commands from vTPM's:
170 The TPM Manager does not respond to shutdown requests; use the destroy
172 command to shut it down.
173
175 vTPM disk image setup:
176 The vTPM requires a disk image to store its persistent data (RSA keys,
177 NVRAM, etc). The image does not require a filesystem. The image does
178 not need to be large; 2 Mb should be sufficient.
179 vTPM config file:
181 The vTPM domain requires a configuration file like any other domain.
182 The vTPM requires a disk image for storage and a TPM frontend driver to
183 communicate with the manager. You are required to generate a uuid for
184 this vtpm, which is specified on the "vtpm=" line that describes its
185 connection to the vTPM Manager. The uuidgen application may be used to
186 generate a uuid, or one from the output of the "manage-vtpmmgr.pl
187 vtpm-add" command may be used to create a vTPM belonging to a specific
188 group.
189 If you wish to clear the vTPM data you can either recreate the disk
191 image or change the uuid.
192 Linux Guest config file:
194 The Linux guest config file needs to be modified to include the Linux
195 tpmfront driver. Add the following line:
196 vtpm=["backend=domu-vtpm"]
198 Currently only Linux guests are supported (PV or HVM with PV drivers).
200 While attaching a vTPM after a guest is booted (using xl vtpm-attach)
202 is supported, the attached vTPM will not have a record of the boot of
203 the attached guest. Furthermore, if the vTPM has been freshly created,
204 a malicious guest could then extend any values into PCRs, potentially
205 forging its boot configuration. Attaching a vTPM to a running domain
206 should only be used for trusted domains or when measurements have
207 already been sent to the vTPM from another source.
208 Using the vTPM in the guest:
210 If xen-tpmfront was compiled as a module, it must be loaded it in the
211 guest.
212 # modprobe xen-tpmfront
214 After the Linux domain boots and the xen-tpmfront driver is loaded, you
216 should see the following on the vtpm console:
217 Info: VTPM attached to Frontend X/Y
219 You can quickly test the vTPM by using the sysfs interface:
221 # cat /sys/devices/vtpm-0/pubek
223 # cat /sys/devices/vtpm-0/pcrs
224 If you have trousers and tpm_tools installed on the guest, the
226 tpm_version command should return the following:
227 The version command should return the following:
229 TPM 1.2 Version Info:
231 Chip Version: 1.2.0.7
232 Spec Level: 2
233 Errata Revision: 1
234 TPM Vendor ID: ETHZ
235 TPM Version: 01010000
236 Manufacturer Info: 4554485a
237 You should also see the command being sent to the vtpm console as well
239 as the vtpm saving its state. You should see the vtpm key being
240 encrypted and stored on the vtpmmgr console.
241 You may wish to write a script to start your vtpm and guest together
243 and to destroy the vtpm when the guest shuts down.
244
246 The vTPM currently starts up with all PCRs set to their default values
247 (all zeros for the lower 16). This means that any decisions about the
248 trustworthiness of the created domain must be made based on the
249 environment that created the vTPM and the domU; for example, a system
250 that only constructs images using a trusted configuration and guest
251 kernel be able to provide guarantees about the guests and any
252 measurements done that kernel (such as the IMA TCB log). Guests
253 wishing to use a custom kernel in such a secure environment are often
254 started using the pv-grub bootloader as the kernel, which then can load
255 the untrusted kernel without needing to parse an untrusted filesystem
256 and kernel in dom0. If the pv-grub stub domain succeeds in connecting
257 to a vTPM, it will extend the hash of the kernel that it boots into PCR
258 #4, and will extend the command line and initrd into PCR #5 before
259 booting so that a domU booted in this way can attest to its early boot
260 state.
261
263 See <xen-vtpmmgr(7)> for more details about how the manager domain
264 works, how to use it, and its command line parameters.
265
267 The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest
268 OS to use. It is a small wrapper around the Berlios TPM emulator
269 version 0.7.4. Commands are passed from the linux guest via the mini-
270 os TPM backend driver. vTPM data is encrypted and stored via a disk
271 image provided to the virtual machine. The key used to encrypt the data
272 along with a hash of the vTPM's data is sent to the vTPM manager for
273 secure storage and later retrieval. The vTPM domain communicates with
274 the manager using a mini-os tpm front/back device pair.
275
277 Command line arguments are passed to the domain via the 'extra'
278 parameter in the VM config file. Each parameter is separated by white
279 space. For example:
280 extra="foo=bar baz"
282 List of Arguments:
284 loglevel=<LOG>
285 Controls the amount of logging printed to the console. The
286 possible values for <LOG> are:
287 · error
289 · info (default)
291 · debug
293 clear
295 Start the Berlios emulator in "clear" mode. (default)
296 save
298 Start the Berlios emulator in "save" mode.
299 deactivated
301 Start the Berlios emulator in "deactivated" mode. See the Berlios
302 TPM emulator documentation for details about the startup mode. For
303 all normal use, always use clear which is the default. You should
304 not need to specify any of these.
305 maintcmds=<1|0>
307 Enable to disable the TPM maintenance commands. These commands are
308 used by tpm manufacturers and thus open a security hole. They are
309 disabled by default.
310 hwinitpcr=<PCRSPEC>
312 Initialize the virtual Platform Configuration Registers (PCRs) with
313 PCR values from the hardware TPM. Each pcr specified by <PCRSPEC>
314 will be initialized with the value of that same PCR in TPM once at
315 startup. By default all PCRs are zero initialized. Possible values
316 of <PCRSPEC> are:
317 · all: copy all pcrs
319 · none: copy no pcrs (default)
321 · <N>: copy pcr n
323 · <X-Y>: copy pcrs x to y (inclusive)
325 These can also be combined by comma separation, for example:
327 "hwinitpcrs=5,12-16" will copy pcrs 5, 12, 13, 14, 15, and 16.
328
330 Berlios TPM Emulator: <http://tpm-emulator.berlios.de/>
3314.11.1 2018-11-29 xen-vtpm(7)