1Author: Daniel De Graaf <dgdegra@tycho.nsa.gov>
2
3================================================================================
4Overview
5================================================================================
6
7This document describes example platforms which use virtual TPMs to provide
8security properties for guests running on the platforms.  There are several
9tradeoffs between flexibility and trust which must be considered when
10implementing a platform containing vTPMs.
11
12================================================================================
13Example 1: Trusted Domain 0
14================================================================================
15
16This is the simplest example and provides maximal flexibility for testing the
17vTPM Manager and vTPMs.  The vtpmmgr, vtpm, and guest domains are created using
18xl from the command line on domain 0.
19
20Provisioning on domain 0:
21# dd if=/dev/zero of=/images/vtpmmgr-stubdom.img bs=2M count=1
22# dd if=/dev/zero of=/images/vtpm-guest1.img bs=2M count=1
23# dd if=/dev/zero of=/images/vtpm-guest2.img bs=2M count=1
24
25The vtpmmgr configuration file (vtpmmgr.cfg):
26
27name="vtpmmgr"
28kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
29extra="tpmlocality=2"
30memory=8
31disk=["file:/images/vtpmmgr-stubdom.img,hda,w"]
32iomem=["fed42,1"]
33
34The vtpm configuration files (vtpm-guest1.cfg, vtpm-guest2.cfg):
35
36name="vtpm-guest1"
37kernel="/usr/lib/xen/boot/vtpm-stubdom.gz"
38extra="loglevel=debug"
39memory=8
40disk=["file:/images/vtpm-guest1.img,hda,w"]
41vtpm=["backend=vtpmmgr,uuid=ac0a5b9e-cbe2-4c07-b43b-1d69e46fb839"]
42
43name="vtpm-guest2"
44kernel="/usr/lib/xen/boot/vtpm-stubdom.gz"
45extra="loglevel=debug"
46memory=8
47disk=["file:/images/vtpm-guest2.img,hda,w"]
48vtpm=["backend=vtpmmgr,uuid=6c3ff5f1-8d58-4fed-b00d-a5ea9a817f7f"]
49
50The guest configuration files (guest1.cfg, guest2.cfg):
51
52name="guest1"
53kernel="/usr/lib/xen/boot/pv-grub-x86_64.gz"
54memory=1024
55disk=["file:/images/guest1.img,xvda,w"]
56vif=['mac=00:01:02:03:04:05,bridge=br0']
57vtpm=["backend=vtpm-guest1"]
58
59name="guest2"
60kernel="/usr/lib/xen/boot/pv-grub-x86_64.gz"
61memory=1024
62disk=["file:/images/guest2.img,xvda,w"]
63vif=['mac=00:01:02:03:04:06,bridge=br0']
64vtpm=["backend=vtpm-guest2"]
65
66Starting domains:
67
68# xl create vtpmmgr.cfg
69# xl create vtpm-guest1.cfg
70# xl create guest1.cfg
71
72================================================================================
73Example 2: Domain Builder with Static vTPMs
74================================================================================
75
76This example uses the domain builder to construct a TPM Manager and vTPM which
77do not require trusting the hardware domain with the vTPM's secrets.  However,
78it is not possible to construct additional vTPMs after the system is booted, and
79the guests with access to vTPMs may not be rebooted without rebooting the entire
80platform.
81
82The domain builder (dom0) constructs:
83	dom1 - xenstore    system_u:system_r:xenstore_t
84	dom2 - hardware    system_u:system_r:hwdom_t
85	dom3 - vtpmmgr     system_u:system_r:vtpmmgr_t
86	dom4 - vtpm-hw     system_u:system_r:vtpm_t
87	dom5 - vtpm-g1     guest1_u:vm_r:vtpm_t
88	dom6 - vtpm-g2     guest2_u:vm_r:vtpm_t
89	dom7 - guest1      guest1_u:vm_r:guest_t
90	dom8 - guest2      guest2_u:vm_r:guest_t
91
92It unpauses dom1 and dom2 after setting up Xenstore. The hardware domain is not
93permitted access to IO memory at 0xfed42; this IO memory is accessible to the
94vtpmmgr domain.  The two guest domains may be instantiated using pv-grub or
95using the same kernel as the hardware domain to conserve space in the domain
96builder's initrd.
97
98Once the hardware domain boots, it runs:
99
100# xl block-attach vtpmmgr 'backendtype=phy,backend=hardware,vdev=hda,access=w,target=/dev/lvm/vtpmmgr'
101# xl block-attach vtpm-hw 'backendtype=phy,backend=hardware,vdev=hda,access=w,target=/dev/lvm/vtpm-hw'
102# xl block-attach vtpm-g1 'backendtype=phy,backend=hardware,vdev=hda,access=w,target=/dev/lvm/vtpm-g1'
103# xl block-attach vtpm-g2 'backendtype=phy,backend=hardware,vdev=hda,access=w,target=/dev/lvm/vtpm-g2'
104# xl block-attach guest1 'backendtype=phy,backend=hardware,vdev=xvda,access=w,target=/dev/lvm/guest1'
105# xl block-attach guest2 'backendtype=phy,backend=hardware,vdev=xvda,access=w,target=/dev/lvm/guest2'
106# xl vtpm-attach vtpm-hw uuid=062b6416-ed46-492a-9e65-a2f92dc07f7f backend=vtpmmgr
107# xl vtpm-attach vtpm-g1 uuid=e9aa9d0f-ece5-4b84-b129-93004ba61a5f backend=vtpmmgr
108# xl vtpm-attach vtpm-g2 uuid=3fb2caf0-d305-4516-96c7-420618d98efb backend=vtpmmgr
109# xl vtpm-attach hardware uuid=062b6416-ed46-492a-9e65-a2f92dc07f7f backend=vtpm-hw
110# xl vtpm-attach guest1 uuid=e9aa9d0f-ece5-4b84-b129-93004ba61a5f backend=vtpm-g1
111# xl vtpm-attach guest2 uuid=3fb2caf0-d305-4516-96c7-420618d98efb backend=vtpm-g2
112
113Once these commands are complete, the domains are unpaused and may boot. The XSM
114policy must be configured to not allow any of the domain types named above to be
115created by any domain except the domain builder; guests created by the hardware
116domain or one of the primary guests acting as a control domain must have a
117different type. The type vtpmmgr_t may only map grants from vtpm_t; vtpm_t may
118only map grants from a domain of type guest_t or hwdom_t with the same user
119field.
120
121This example may be extended to allow dynamic creation of domains by using a
122domain builder that accepts build requests.  A single build request would create
123a pair of domains using an unused XSM user field: a vTPM and a pv-grub domain
124which requires the presence of a vTPM.  To bind the configuration of the guest
125to the vTPM, the guest may use full-disk encryption which can be unlocked using
126an unseal operation; using the wrong vTPM will then yield a non-functioning
127guest.
128
129In order to use pv-grub to obtain measurements of the guest kernel in PCRs 4 and
1305, it must not be possible to attach to a guest's vTPM without booting a fresh
131guest image.  This requires pairing every vTPM's launch with the launch of a
132guest, as described above, and using the --vtpm-label= argument to pv-grub so
133that it refuses to launch a guest if it could not write to the vTPM.  To permit
134the hardware domain, which cannot use pv-grub, to use a vTPM in this situation,
135multiple vTPM groups must be used in the TPM Manager.  Group 0 would be for the
136hardware domain only, and would only support vTPMs with label
137"system_u:system_r:vtpm_t".  Group 1 would support vTPMs with label
138"*:vm_r:vtpm_t", and would be used for all guest vTPMs.  The EK quote used in
139initial provisioning and any deep quotes produced later would include the label,
140which would allow a verifier to reliably determine if the value of the vTPM's
141PCR 4 contains the hash of the domain's kernel.
142