Skip to content

Commit 38a6070

Browse files
Zuulopenstack-gerrit
Zuul
authored and
openstack-gerrit
committed
Merge "docs: Add docs for vTPM support"
2 parents d3be7c5 + 0ed4ec6 commit 38a6070

File tree

4 files changed

+170
-0
lines changed

4 files changed

+170
-0
lines changed

‎doc/source/admin/emulated-tpm.rst‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
=======================================
2+
Emulated Trusted Platform Module (vTPM)
3+
=======================================
4+
5+
.. versionadded:: 22.0.0 (Victoria)
6+
7+
Starting in the 22.0.0 (Victoria) release, Nova supports adding an emulated
8+
virtual `Trusted Platform Module`__ (vTPM) to guests.
9+
10+
.. __: https://en.wikipedia.org/wiki/Trusted_Platform_Module
11+
12+
13+
Enabling vTPM
14+
-------------
15+
16+
The following are required on each compute host wishing to support the vTPM
17+
feature:
18+
19+
* Currently vTPM is only supported when using the libvirt compute driver with a
20+
:oslo.config:option:`libvirt.virt_type` of ``kvm`` or ``qemu``.
21+
22+
* A `key manager service`__, such as `barbican`__, must be configured to store
23+
secrets used to encrypt the virtual device files at rest.
24+
25+
* QEMU version >= 2.11 (>= 2.12 is recommended)
26+
27+
* Libvirt version >= 5.6.0
28+
29+
* The swtpm__ binary and associated libraries__.
30+
31+
* Set the :oslo.config:option:`libvirt.swtpm_enabled` config option to
32+
``True``. This will enable support for both TPM version 1.2 and 2.0.
33+
34+
With the above requirements satisfied, verify vTPM support by inspecting the
35+
traits on the compute node's resource provider:
36+
37+
.. code:: console
38+
39+
$ openstack resource provider trait list $compute_uuid | grep SECURITY_TPM
40+
| COMPUTE_SECURITY_TPM_1_2 |
41+
| COMPUTE_SECURITY_TPM_2_0 |
42+
43+
.. __: https://docs.openstack.org/api-guide/key-manager/
44+
.. __: https://docs.openstack.org/barbican/latest/
45+
.. __: https://github.com/stefanberger/swtpm/wiki
46+
.. __: https://github.com/stefanberger/libtpms/
47+
48+
49+
Configuring a flavor or image
50+
-----------------------------
51+
52+
A vTPM can be requested on a server via :ref:`flavor extra_specs <vtpm-flavor>`
53+
or image metadata properties.
54+
55+
.. list-table::
56+
:header-rows: 1
57+
58+
* - Flavor extra_specs
59+
- Image metadata
60+
- Description
61+
* - ``hw:tpm_version``
62+
- ``hw_tpm_version``
63+
- Specify the TPM version, ``1.2`` or ``2.0``. Required if requesting a
64+
vTPM.
65+
* - ``hw:tpm_model``
66+
- ``hw_tpm_model``
67+
- Specify the TPM model, ``tpm-tis`` (the default) or ``tpm-crb`` (only
68+
valid with version ``2.0``.
69+
70+
Scheduling will fail if flavor and image supply conflicting values, or if model
71+
``tpm-crb`` is requested with version ``1.2``.
72+
73+
Upon successful boot, the server should see a TPM device such as ``/dev/tpm0``
74+
which can be used in the same manner as a hardware TPM.
75+
76+
77+
Limitations
78+
-----------
79+
80+
* Only server operations performed by the server owner are supported, as the
81+
user's credentials are required to unlock the virtual device files on the
82+
host. Thus the admin may need to decide whether to grant the user additional
83+
policy roles; if not, those operations are effectively disabled.
84+
85+
* Live migration, cold migration, resize, evacuation, shelving and rescuing of
86+
servers with vTPMs is not currently supported.
87+
88+
89+
Security
90+
--------
91+
92+
With a hardware TPM, the root of trust is a secret known only to the TPM user.
93+
In contrast, an emulated TPM comprises a file on disk which the libvirt daemon
94+
must be able to present to the guest. At rest, this file is encrypted using a
95+
passphrase stored in a key manager service. The passphrase in the key manager
96+
is associated with the credentials of the owner of the server (the user who
97+
initially created it). The passphrase is retrieved and used by libvirt to
98+
unlock the emulated TPM data any time the server is booted.
99+
100+
Although the above mechanism uses a libvirt secret__ that is both ``private``
101+
(can't be displayed via the libvirt API or ``virsh``) and ``ephemeral`` (exists
102+
only in memory, never on disk), it is theoretically possible for a sufficiently
103+
privileged user to retrieve the secret and/or vTPM data from memory.
104+
105+
A full analysis and discussion of security issues related to emulated TPM is
106+
beyond the scope of this document.
107+
108+
.. __: https://libvirt.org/formatsecret.html#SecretAttributes
109+
110+
111+
References
112+
----------
113+
114+
* `QEMU docs on tpm`__
115+
* `Libvirt XML to request emulated TPM device`__
116+
* `Libvirt secret for usage type ``vtpm```__
117+
118+
.. __: https://github.com/qemu/qemu/blob/stable-2.12/docs/specs/tpm.txt
119+
.. __: https://libvirt.org/formatdomain.html#elementsTpm
120+
.. __: https://libvirt.org/formatsecret.html#vTPMUsageType

‎doc/source/admin/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ instance for these kind of workloads.
112112
file-backed-memory
113113
ports-with-resource-requests
114114
virtual-persistent-memory
115+
emulated-tpm
115116

116117

117118
Additional guides

‎doc/source/user/flavors.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -926,3 +926,26 @@ Numbered groupings of resource classes and traits
926926
See `Granular Resource Request Syntax`_ for more details.
927927

928928
.. _Granular Resource Request Syntax: https://specs.openstack.org/openstack/nova-specs/specs/rocky/implemented/granular-resource-requests.html
929+
930+
.. _vtpm-flavor:
931+
932+
Emulated Virtual TPM
933+
If supported by the compute host, you can add an :doc:`emulated trusted
934+
platform module (TPM) </admin/emulated-tpm>` to the guest OS.
935+
936+
.. code:: console
937+
938+
$ openstack flavor set FLAVOR-NAME \
939+
--property hw:tpm_version=$VERSION \
940+
--property hw:tpm_model=$MODEL
941+
942+
``hw:tpm_version`` is required to enable support. Valid ``$VERSION`` values
943+
are:
944+
945+
- ``1.2`` : Selects TPM version 1.2 support.
946+
- ``2.0`` : Selects TPM version 2.0 support.
947+
948+
``hw:tpm_model`` is optional. Valid ``$MODEL`` values are:
949+
950+
- ``tpm-tis``: Selects TIS device model. This is the default value.
951+
- ``tpm-crb``: Selects CRB device model. Only valid for TPM version 2.0.

‎doc/source/user/support-matrix.ini‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1636,3 +1636,29 @@ driver-notes.powervm=The PowerVM driver does image caching natively when using
16361636
the SSP disk driver. It does not use the config options in the [image_cache]
16371637
group.
16381638
driver.zvm=missing
1639+
1640+
[operation.boot-emulated-tpm]
1641+
title=Boot instance with an emulated trusted platform module (TPM)
1642+
status=optional
1643+
notes=Allows VMs to be booted with an emulated trusted platform module (TPM)
1644+
device. Only lifecycle operations performed by the VM owner are supported, as
1645+
the user's credentials are required to unlock the virtual device files on the
1646+
host.
1647+
cli=openstack server create <usual server create parameters>
1648+
driver.xenserver=missing
1649+
driver.libvirt-kvm-x86=partial
1650+
driver-notes.libvirt-kvm-x86=Move operations are not yet supported.
1651+
driver.libvirt-kvm-aarch64=missing
1652+
driver.libvirt-kvm-ppc64=missing
1653+
driver.libvirt-kvm-s390x=missing
1654+
driver.libvirt-qemu-x86=partial
1655+
driver-notes.libvirt-qemu-x86=Move operations are not yet supported.
1656+
driver.libvirt-lxc=missing
1657+
driver.libvirt-xen=missing
1658+
driver.vmware=missing
1659+
driver.hyperv=missing
1660+
driver.ironic=missing
1661+
driver.libvirt-vz-vm=missing
1662+
driver.libvirt-vz-ct=missing
1663+
driver.powervm=missing
1664+
driver.zvm=missing

0 commit comments

Comments
 (0)