.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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-vtpmmgr 7" .TH xen-vtpmmgr 7 "2023-03-23" "4.14.5" "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\-vtpmgr \- Xen virtual TPM stubdomain .SH "Authors" .IX Header "Authors" .IP "Daniel De Graaf " 4 .IX Item "Daniel De Graaf " .PD 0 .IP "Quan Xu " 4 .IX Item "Quan Xu " .PD .PP This document describes the operation and command line interface of vtpmmgr-stubdom. See \fBxen\-vtpm\fR\|(7) for details on the vTPM subsystem as a whole. .SH "Overview" .IX Header "Overview" The \s-1TPM\s0 Manager has three primary functions: .IP "1. Securely store the encryption keys for vTPMs" 4 .IX Item "1. Securely store the encryption keys for vTPMs" .PD 0 .IP "2. Provide a single controlled path of access to the physical \s-1TPM\s0" 4 .IX Item "2. Provide a single controlled path of access to the physical TPM" .IP "3. Provide evidence (via \s-1TPM\s0 Quotes) of the current configuration" 4 .IX Item "3. Provide evidence (via TPM Quotes) of the current configuration" .PD .PP When combined with a platform that provides a trusted method for creating domains, the \s-1TPM\s0 Manager provides assurance that the private keys in a vTPM are only available in specific trusted configurations. .PP The manager accepts commands from the vtpm-stubdom domains via the mini-os \s-1TPM\s0 backend driver. The vTPM manager communicates directly with hardware \s-1TPM\s0 using the mini-os tpm_tis driver. .SH "Boot Configurations and TPM Groups" .IX Header "Boot Configurations and TPM Groups" The \s-1TPM\s0 Manager's data is secured by using the physical \s-1TPM\s0's seal operation, which allows data to be bound to specific PCRs. These PCRs are populated in the physical \s-1TPM\s0 during the boot process, either by the firmware/BIOS or by a dynamic launch environment such as \s-1TBOOT.\s0 In order to provide assurance of the system's security, the PCRs used to seal the \s-1TPM\s0 manager's data must contain measurements for domains used to bootstrap the \s-1TPM\s0 Manager and vTPMs. .PP Because these measurements are based on hashes, they will change any time that any component of the system is upgraded. Since it is not possible to construct a list of all possible future good measurements, the job of approving configurations is delegated to a third party, referred to here as the system approval agent (\s-1SAA\s0). The \s-1SAA\s0 is identified by its public (\s-1RSA\s0) signature key, which is used to sign lists of valid configurations. A single \s-1TPM\s0 manager can support multiple SAAs via the use of vTPM groups. Each group is associated with a single \s-1SAA\s0; this allows the creation of a multi-tenant environment where tenants may not all choose to trust the same \s-1SAA.\s0 .PP Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group has its own \s-1AIK\s0 in the physical \s-1TPM\s0 for quotes of the hardware \s-1TPM\s0 state; when used with a conforming Privacy \s-1CA,\s0 this allows each group on the system to form the basis of a distinct identity. .SH "Initial Provisioning" .IX Header "Initial Provisioning" When the \s-1TPM\s0 Manager first boots up, it will create a stub vTPM group along with entries for any vTPMs that communicate with it. This stub group must be provisioned with an \s-1SAA\s0 and a boot configuration in order to survive a reboot. .PP When a vTPM is connected to the \s-1TPM\s0 Manager using a \s-1UUID\s0 that is not recognized, a slot will be created in group 0 for it. In the future, this auto-creation may be restricted to specific UUIDs (such as the all-zero \s-1UUID\s0) to enforce the use of the \s-1TPM\s0 manager as the generator of the \s-1UUID.\s0 The first vTPM to be connected is given administrative privileges for the \s-1TPM\s0 Manager, and should be attached to dom0 or a control domain in order to send provisioning commands. .PP Provisioning a vTPM group for the system requires the public key of the \s-1SAA\s0 and privacy \s-1CA\s0 data used to certify the \s-1AIK\s0 (see the \s-1TPM\s0 spec for details). Once the group is created, a signed list of boot measurements can be installed. The initial group controls the ability to boot the system as a whole, and cannot be deleted once provisioned. .SH "Command Line Arguments" .IX Header "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 .PP Valid arguments: .IP "owner_auth=<\s-1AUTHSPEC\s0>" 4 .IX Item "owner_auth=" .PD 0 .IP "srk_auth=<\s-1AUTHSPEC\s0>" 4 .IX Item "srk_auth=" .PD Set the owner and \s-1SRK\s0 authdata for the \s-1TPM.\s0 If not specified, the default is 160 zero bits (the well-known auth value). Valid values of <\s-1AUTHSPEC\s0> are: .RS 4 .IP "well-known" 4 .IX Item "well-known" Use the well known auth (default) .IP "hash:<\s-1HASH\s0>" 4 .IX Item "hash:" Use the given 40\-character \s-1ASCII\s0 hex string .IP "text:<\s-1STR\s0>" 4 .IX Item "text:" Use sha1 hash of <\s-1STR\s0>. .RE .RS 4 .RE .IP "tpmdriver=<\s-1DRIVER\s0>" 4 .IX Item "tpmdriver=" Choose the driver used for communication with the hardware \s-1TPM.\s0 Values other than tpm_tis should only be used for testing. .Sp The possible values of <\s-1DRIVER\s0> are: .RS 4 .IP "tpm_tis" 4 .IX Item "tpm_tis" Direct communication with a hardware \s-1TPM 1.2.\s0 The domain must have access to \s-1TPM IO\s0 memory. (default) .IP "tpmfront" 4 .IX Item "tpmfront" Use the Xen tpmfront interface to talk to another domain which provides access to the \s-1TPM.\s0 .RE .RS 4 .RE .PP The following options only apply to the tpm_tis driver: .IP "tpmiomem=<\s-1ADDR\s0>" 4 .IX Item "tpmiomem=" The base address of the hardware memory pages of the \s-1TPM.\s0 The default is 0xfed40000, as defined by the \s-1TCG\s0's \s-1PC\s0 Client spec. .IP "tpmirq=<\s-1IRQ\s0>" 4 .IX Item "tpmirq=" The irq of the hardware \s-1TPM\s0 if using interrupts. A value of \&\*(L"probe\*(R" can be set to probe for the irq. A value of 0 disables interrupts and uses polling (default 0). .IP "tpmlocality=<\s-1LOC\s0>" 4 .IX Item "tpmlocality=" Attempt to use locality <\s-1LOC\s0> of the hardware \s-1TPM.\s0 For full functionality of the \s-1TPM\s0 Manager, this should be set to \*(L"2\*(R". .SH "Platform Security Assumptions" .IX Header "Platform Security Assumptions" While the \s-1TPM\s0 Manager has the ability to check the hash of the vTPM requesting a key, there is currently no trusted method to inform the \s-1TPM\s0 Manager of the hash of each new domain. Because of this, the \s-1TPM\s0 Manager trusts the \s-1UUID\s0 key in Xenstore to identify a vTPM in a trusted manner. The \s-1XSM\s0 policy may be used to strengthen this assumption if the creation of vTPM-labeled domains is more constrained (for example, only permitted to a domain builder service): the only grants mapped by the \s-1TPM\s0 Manager should belong to vTPM domains, so restricting the ability to map other domain's granted pages will prevent other domains from directly requesting keys from the \s-1TPM\s0 Manager. The \s-1TPM\s0 Manager uses the hash of the \s-1XSM\s0 label of the attached vTPM as the kernel hash, so vTPMs with distinct labels may be further partitioned using vTPM groups. .PP A domain with direct access to the hardware \s-1TPM\s0 will be able to decrypt the \s-1TPM\s0 Manager's disk image if the haredware \s-1TPM\s0's \s-1PCR\s0 values are in a permitted configuration. To protect the \s-1TPM\s0 Manager's data, the list of permitted configurations should be chosen to include PCRs that measure the hypervisor, domain 0, the \s-1TPM\s0 Manager, and other critical configuration such as the \s-1XSM\s0 policy. If the \s-1TPM\s0 Manager is configured to use locality 2 as recommended, it is safe to permit the hardware domain to access locality 0 (the default in Linux), although concurrent use of the \s-1TPM\s0 should be avoided as it can result in unexpected busy errors from the \s-1TPM\s0 driver. The ability to access locality 2 of the \s-1TPM\s0 should be enforced using \s-1IO\s0 memory labeling in the \s-1XSM\s0 policy; the physical address 0xFED42xxx is always locality 2 for TPMs using the \s-1TIS\s0 driver. .SH "Appendix: unsecured migration process for vtpmmgr domain upgrade" .IX Header "Appendix: unsecured migration process for vtpmmgr domain upgrade" There is no direct upgrade supported from previous versions of the vtpmmgr domain due to changes in the on-disk format and the method used to seal data. If a vTPM domain supports migration, this feature should be used to migrate the vTPM's data; however, the vTPM packaged with Xen does not yet support migration. .PP If adding migration support to the vTPM is not desired, a simpler migration domain usable only for local migration can be constructed. The migration process would look like the following: .IP "1. Start the old vtpmmgr" 4 .IX Item "1. Start the old vtpmmgr" .PD 0 .IP "2. Start the vTPM migration domain" 4 .IX Item "2. Start the vTPM migration domain" .IP "3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr" 4 .IX Item "3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr" .IP "4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0" 4 .IX Item "4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0" .IP "5. Start the new vtpmmgr, possibly shutting down the old one first" 4 .IX Item "5. Start the new vtpmmgr, possibly shutting down the old one first" .IP "6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr" 4 .IX Item "6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr" .IP "7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1" 4 .IX Item "7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1" .PD .PP This requires the migration domain to be added to the list of valid vTPM kernel hashes. In the current version of the vtpmmgr domain, this is the hash of the \&\s-1XSM\s0 label, not the kernel. .SH "Appendix B: vtpmmgr on TPM 2.0" .IX Header "Appendix B: vtpmmgr on TPM 2.0" .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. .PP .Vb 1 \& dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1 .Ve .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). .PP Add: .PP .Vb 1 \& extra="tpm2=1" .Ve .PP extra option to launch vtpmmgr-stubdom domain on \s-1TPM 2.0,\s0 and ignore it on \s-1TPM 1\s0.x. for example: .PP .Vb 6 \& kernel="/usr/lib/xen/boot/vtpmmgr\-stubdom.gz" \& memory=128 \& disk=["file:/home/vtpm2/vmgr,hda,w"] \& name="vtpmmgr" \& iomem=["fed40,5"] \& extra="tpm2=1" .Ve .SS "Key Hierarchy" .IX Subsection "Key Hierarchy" .Vb 10 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | vTPM\*(Aqs secrets | ... \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& | |(Bind / Unbind) \&\- \- \- \- \- \-v |\- \- \- \- \- \- \- \- TPM 2.0 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | SK + \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | SRK | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | TPM 2.0 Storage | \& | Primary Seed | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP Now the secrets for the vTPMs are only being bound to the presence of thephysical \&\s-1TPM 2.0.\s0 Since using PCRs to seal the data can be an important security feature that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with TPM2_Seal/TPM2_Unseal to provide as much security as it did for \s-1TPM 1.2\s0 in later series of patch. .SS "Design Overview" .IX Subsection "Design Overview" The architecture of vTPM subsystem on \s-1TPM 2.0\s0 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/tpm2_tis | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | ^ \& v | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Hardware TPM 2.0 | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .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/tpm2_tis" 4 .IX Item "mini-os/tpm2_tis" Mini-os \s-1TPM\s0 version 2.0 \s-1TPM\s0 Interface Specification (\s-1TIS\s0) driver. This driver used by vtpmmgr-stubdom to talk directly to the hardware \s-1TPM 2.0.\s0 Communication is facilitated by mapping hardware memory pages into vtpmmgr-stubdom. .IP "Hardware \s-1TPM 2.0\s0" 4 .IX Item "Hardware TPM 2.0" The physical \s-1TPM 2.0\s0 that is soldered onto the motherboard. .PP Noted: functionality for a virtual guest operating system (a DomU) is still \s-1TPM 1.2.\s0