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