.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "xen-vtpm 7" .TH xen-vtpm 7 "2021-03-24" "4.11.4" "Xen" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" xen\-vtpm \- Xen virtual Trusted Platform Module (vTPM) subsystem .SH "RUBRIC" .IX Header "RUBRIC" Copyright (c) 2010\-2012 United States Government, as represented by the Secretary of Defense. All rights reserved. November 12 2012 Authors: Matthew Fioravante (\s-1JHUAPL\s0), Daniel De Graaf (\s-1NSA\s0) .PP This document describes the virtual Trusted Platform Module (vTPM) subsystem for Xen. The reader is assumed to have familiarity with building and installing Xen, Linux, and a basic understanding of the \s-1TPM\s0 and vTPM concepts. .SH "INTRODUCTION" .IX Header "INTRODUCTION" The goal of this work is to provide a \s-1TPM\s0 functionality to a virtual guest operating system (a DomU). This allows programs to interact with a \s-1TPM\s0 in a virtual system the same way they interact with a \s-1TPM\s0 on the physical system. Each guest gets its own unique, emulated, software \s-1TPM.\s0 However, each of the vTPM's secrets (Keys, \s-1NVRAM,\s0 etc) are managed by a vTPM Manager domain, which seals the secrets to the Physical \s-1TPM.\s0 If the process of creating each of these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the chain of trust rooted in the hardware \s-1TPM\s0 to virtual machines in Xen. Each major component of vTPM is implemented as a separate domain, providing secure separation guaranteed by the hypervisor. The vTPM domains are implemented in mini-os to reduce memory and processor overhead. .PP This mini-os vTPM subsystem was built on top of the previous vTPM work done by \&\s-1IBM\s0 and Intel corporation. .SH "DESIGN OVERVIEW" .IX Header "DESIGN OVERVIEW" The architecture of vTPM is described below: .PP .Vb 10 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Linux DomU | ... \& | | ^ | \& | v | | \& | xen\-tpmfront | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | mini\-os/tpmback | \& | | ^ | \& | v | | \& | vtpm\-stubdom | ... \& | | ^ | \& | v | | \& | mini\-os/tpmfront | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | mini\-os/tpmback | \& | | ^ | \& | v | | \& | vtpmmgr\-stubdom | \& | | ^ | \& | v | | \& | mini\-os/tpm_tis | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Hardware TPM | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .IP "Linux DomU" 4 .IX Item "Linux DomU" The Linux based guest that wants to use a vTPM. There many be more than one of these. .IP "xen\-tpmfront.ko" 4 .IX Item "xen-tpmfront.ko" Linux kernel virtual \s-1TPM\s0 frontend driver. This driver provides vTPM access to a para-virtualized Linux based DomU. .IP "mini\-os/tpmback" 4 .IX Item "mini-os/tpmback" Mini-os \s-1TPM\s0 backend driver. The Linux frontend driver connects to this backend driver to facilitate communications between the Linux DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to communicate with vtpm-stubdom. .IP "vtpm-stubdom" 4 .IX Item "vtpm-stubdom" A mini-os stub domain that implements a vTPM. There is a one to one mapping between running vtpm-stubdom instances and logical vtpms on the system. The vTPM Platform Configuration Registers (PCRs) are all initialized to zero. .IP "mini\-os/tpmfront" 4 .IX Item "mini-os/tpmfront" Mini-os \s-1TPM\s0 frontend driver. The vTPM mini-os domain vtpm-stubdom uses this driver to communicate with vtpmmgr-stubdom. This driver could also be used separately to implement a mini-os domain that wishes to use a vTPM of its own. .IP "vtpmmgr-stubdom" 4 .IX Item "vtpmmgr-stubdom" A mini-os domain that implements the vTPM manager. There is only one vTPM manager and it should be running during the entire lifetime of the machine. This domain regulates access to the physical \s-1TPM\s0 on the system and secures the persistent state of each vTPM. .IP "mini\-os/tpm_tis" 4 .IX Item "mini-os/tpm_tis" Mini-os \s-1TPM\s0 version 1.2 \s-1TPM\s0 Interface Specification (\s-1TIS\s0) driver. This driver used by vtpmmgr-stubdom to talk directly to the hardware \s-1TPM.\s0 Communication is facilitated by mapping hardware memory pages into vtpmmgr-stubdom. .IP "Hardware \s-1TPM\s0" 4 .IX Item "Hardware TPM" The physical \s-1TPM\s0 that is soldered onto the motherboard. .SH "INSTALLATION" .IX Header "INSTALLATION" .SS "Prerequisites:" .IX Subsection "Prerequisites:" You must have an x86 machine with a \s-1TPM\s0 on the motherboard. The only extra software requirement for compiling vTPM is cmake. You must use libxl to manage domains with vTPMs; 'xm' is deprecated and does not support vTPMs. .SS "Compiling the Xen tree:" .IX Subsection "Compiling the Xen tree:" Compile and install the Xen tree as usual; be sure that the vTPM domains are enabled when you run configure. .SS "Compiling the \s-1LINUX\s0 dom0 kernel:" .IX Subsection "Compiling the LINUX dom0 kernel:" Because the \s-1TPM\s0 manager uses direct access to the physical \s-1TPM,\s0 it may interfere with access to the \s-1TPM\s0 by dom0. The simplest solution for this is to prevent dom0 from accessing the physical \s-1TPM\s0 by compiling the kernel without a driver or blacklisting the module. If dom0 needs a \s-1TPM\s0 but does not need to use it during the boot process (i.e. it is not using \s-1IMA\s0), a virtual \s-1TPM\s0 can be attached to dom0 after the system is booted. .PP Access to the physical \s-1TPM\s0 may be required in order to manage the \s-1NVRAM\s0 or to perform other advanced operations where the vTPM is insufficient. In order to prevent interference, the \s-1TPM\s0 Manager and dom0 should use different values for the \s-1TPM\s0's locality; since Linux always uses locality 0, using locality 2 for the \&\s-1TPM\s0 Manager is recommended. If both Linux and the \s-1TPM\s0 Manager attempt to access the \s-1TPM\s0 at the same time, the \s-1TPM\s0 device will return a busy status; some applications will consider this a fatal error instead of retrying the command at a later time. If a vTPM gets an error when loading its key, it will currently generate a fresh vTPM image (with a new \s-1EK, SRK,\s0 and blank \s-1NVRAM\s0). .SS "Compiling the \s-1LINUX\s0 domU kernel:" .IX Subsection "Compiling the LINUX domU kernel:" The domU kernel used by domains with vtpms must include the xen\-tpmfront.ko driver. It can be built directly into the kernel or as a module; however, some features such as \s-1IMA\s0 require the \s-1TPM\s0 to be built in to the kernel. .PP .Vb 2 \& CONFIG_TCG_TPM=y \& CONFIG_TCG_XEN=y .Ve .SH "VTPM MANAGER SETUP" .IX Header "VTPM MANAGER SETUP" .SS "Manager disk image setup:" .IX Subsection "Manager disk image setup:" The vTPM Manager requires a disk image to store its encrypted data. The image does not require a filesystem and can live anywhere on the host disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image but can support more than 20,000 vTPMs. .SS "Manager config file:" .IX Subsection "Manager config file:" The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen virtual machine and requires a config file. The manager requires a disk image for storage and permission to access the hardware memory pages for the \s-1TPM.\s0 The disk must be presented as \*(L"hda\*(R", and the \s-1TPM\s0 memory pages are passed using the iomem configuration parameter. The \s-1TPM TIS\s0 uses 5 pages of \s-1IO\s0 memory (one per locality) that start at physical address 0xfed40000. By default, the \s-1TPM\s0 manager uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on the domain's command line. For full functionality in deep quotes, using locality 2 is required to manipulate \s-1PCR 20\-22.\s0 .SS "Starting and stopping the manager:" .IX Subsection "Starting and stopping the manager:" The vTPM manager should be started at boot; you may wish to create an init script to do this. If a domain builder is used, the \s-1TPM\s0 Manager should be started by the domain builder to minimize the trusted computing base for the vTPM manager's secrets. .PP Once initialization is complete you should see the following: .PP .Vb 1 \& INFO[VTPM]: Waiting for commands from vTPM\*(Aqs: .Ve .PP The \s-1TPM\s0 Manager does not respond to shutdown requests; use the destroy command to shut it down. .SH "VTPM AND LINUX PVM SETUP" .IX Header "VTPM AND LINUX PVM SETUP" .SS "vTPM disk image setup:" .IX Subsection "vTPM disk image setup:" The vTPM requires a disk image to store its persistent data (\s-1RSA\s0 keys, \s-1NVRAM,\s0 etc). The image does not require a filesystem. The image does not need to be large; 2 Mb should be sufficient. .SS "vTPM config file:" .IX Subsection "vTPM config file:" The vTPM domain requires a configuration file like any other domain. The vTPM requires a disk image for storage and a \s-1TPM\s0 frontend driver to communicate with the manager. You are required to generate a uuid for this vtpm, which is specified on the \f(CW\*(C`vtpm=\*(C'\fR line that describes its connection to the vTPM Manager. The uuidgen application may be used to generate a uuid, or one from the output of the \f(CW\*(C`manage\-vtpmmgr.pl vtpm\-add\*(C'\fR command may be used to create a vTPM belonging to a specific group. .PP If you wish to clear the vTPM data you can either recreate the disk image or change the uuid. .SS "Linux Guest config file:" .IX Subsection "Linux Guest config file:" The Linux guest config file needs to be modified to include the Linux tpmfront driver. Add the following line: .PP .Vb 1 \& vtpm=["backend=domu\-vtpm"] .Ve .PP Currently only Linux guests are supported (\s-1PV\s0 or \s-1HVM\s0 with \s-1PV\s0 drivers). .PP While attaching a vTPM after a guest is booted (using xl vtpm-attach) is supported, the attached vTPM will not have a record of the boot of the attached guest. Furthermore, if the vTPM has been freshly created, a malicious guest could then extend any values into PCRs, potentially forging its boot configuration. Attaching a vTPM to a running domain should only be used for trusted domains or when measurements have already been sent to the vTPM from another source. .SS "Using the vTPM in the guest:" .IX Subsection "Using the vTPM in the guest:" If xen-tpmfront was compiled as a module, it must be loaded it in the guest. .PP .Vb 1 \& # modprobe xen\-tpmfront .Ve .PP After the Linux domain boots and the xen-tpmfront driver is loaded, you should see the following on the vtpm console: .PP .Vb 1 \& Info: VTPM attached to Frontend X/Y .Ve .PP You can quickly test the vTPM by using the sysfs interface: .PP .Vb 2 \& # cat /sys/devices/vtpm\-0/pubek \& # cat /sys/devices/vtpm\-0/pcrs .Ve .PP If you have trousers and tpm_tools installed on the guest, the tpm_version command should return the following: .PP The version command should return the following: .PP .Vb 7 \& TPM 1.2 Version Info: \& Chip Version: 1.2.0.7 \& Spec Level: 2 \& Errata Revision: 1 \& TPM Vendor ID: ETHZ \& TPM Version: 01010000 \& Manufacturer Info: 4554485a .Ve .PP You should also see the command being sent to the vtpm console as well as the vtpm saving its state. You should see the vtpm key being encrypted and stored on the vtpmmgr console. .PP You may wish to write a script to start your vtpm and guest together and to destroy the vtpm when the guest shuts down. .SH "INTEGRATION WITH PV-GRUB" .IX Header "INTEGRATION WITH PV-GRUB" The vTPM currently starts up with all PCRs set to their default values (all zeros for the lower 16). This means that any decisions about the trustworthiness of the created domain must be made based on the environment that created the vTPM and the domU; for example, a system that only constructs images using a trusted configuration and guest kernel be able to provide guarantees about the guests and any measurements done that kernel (such as the \s-1IMA TCB\s0 log). Guests wishing to use a custom kernel in such a secure environment are often started using the pv-grub bootloader as the kernel, which then can load the untrusted kernel without needing to parse an untrusted filesystem and kernel in dom0. If the pv-grub stub domain succeeds in connecting to a vTPM, it will extend the hash of the kernel that it boots into \s-1PCR\s0 #4, and will extend the command line and initrd into \s-1PCR\s0 #5 before booting so that a domU booted in this way can attest to its early boot state. .SH "MORE INFORMATION" .IX Header "MORE INFORMATION" See <\fBxen\-vtpmmgr\fR\|(7)> for more details about how the manager domain works, how to use it, and its command line parameters. .SH "VTPM DOMAIN OPERATION" .IX Header "VTPM DOMAIN OPERATION" The vtpm-stubdom is a mini-OS domain that emulates a \s-1TPM\s0 for the guest \s-1OS\s0 to use. It is a small wrapper around the Berlios \s-1TPM\s0 emulator version 0.7.4. Commands are passed from the linux guest via the mini-os \s-1TPM\s0 backend driver. vTPM data is encrypted and stored via a disk image provided to the virtual machine. The key used to encrypt the data along with a hash of the vTPM's data is sent to the vTPM manager for secure storage and later retrieval. The vTPM domain communicates with the manager using a mini-os tpm front/back device pair. .SH "VTPM DOMAIN COMMAND LINE ARGUMENTS" .IX Header "VTPM DOMAIN COMMAND LINE ARGUMENTS" Command line arguments are passed to the domain via the 'extra' parameter in the \&\s-1VM\s0 config file. Each parameter is separated by white space. For example: .PP .Vb 1 \& extra="foo=bar baz" .Ve .SS "List of Arguments:" .IX Subsection "List of Arguments:" .IP "\fBloglevel\fR=<\s-1LOG\s0>" 4 .IX Item "loglevel=" Controls the amount of logging printed to the console. The possible values for <\s-1LOG\s0> are: .RS 4 .IP "\(bu" 4 error .IP "\(bu" 4 info (default) .IP "\(bu" 4 debug .RE .RS 4 .RE .IP "\fBclear\fR" 4 .IX Item "clear" Start the Berlios emulator in \*(L"clear\*(R" mode. (default) .IP "\fBsave\fR" 4 .IX Item "save" Start the Berlios emulator in \*(L"save\*(R" mode. .IP "\fBdeactivated\fR" 4 .IX Item "deactivated" Start the Berlios emulator in \*(L"deactivated\*(R" mode. See the Berlios \s-1TPM\s0 emulator documentation for details about the startup mode. For all normal use, always use clear which is the default. You should not need to specify any of these. .IP "\fBmaintcmds\fR=<1|0>" 4 .IX Item "maintcmds=<1|0>" Enable to disable the \s-1TPM\s0 maintenance commands. These commands are used by tpm manufacturers and thus open a security hole. They are disabled by default. .IP "\fBhwinitpcr\fR=<\s-1PCRSPEC\s0>" 4 .IX Item "hwinitpcr=" Initialize the virtual Platform Configuration Registers (PCRs) with \s-1PCR\s0 values from the hardware \s-1TPM.\s0 Each pcr specified by <\s-1PCRSPEC\s0> will be initialized with the value of that same \s-1PCR\s0 in \s-1TPM\s0 once at startup. By default all PCRs are zero initialized. Possible values of <\s-1PCRSPEC\s0> are: .RS 4 .IP "\(bu" 4 all: copy all pcrs .IP "\(bu" 4 none: copy no pcrs (default) .IP "\(bu" 4 : copy pcr n .IP "\(bu" 4 : copy pcrs x to y (inclusive) .RE .RS 4 .Sp These can also be combined by comma separation, for example: \&\f(CW\*(C`hwinitpcrs=5,12\-16\*(C'\fR will copy pcrs 5, 12, 13, 14, 15, and 16. .RE .SH "REFERENCES" .IX Header "REFERENCES" Berlios \s-1TPM\s0 Emulator: