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