docs: Add docs for vTPM support
What it is, why you'd want it and how you can configure it. Part of blueprint add-emulated-virtual-tpm Change-Id: I8e52a397bca8f09e6aaa6cab44eee7dded529c55 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
parent
e0ca2652ed
commit
0ed4ec6f26
120
doc/source/admin/emulated-tpm.rst
Normal file
120
doc/source/admin/emulated-tpm.rst
Normal file
@ -0,0 +1,120 @@
|
||||
=======================================
|
||||
Emulated Trusted Platform Module (vTPM)
|
||||
=======================================
|
||||
|
||||
.. versionadded:: 22.0.0 (Victoria)
|
||||
|
||||
Starting in the 22.0.0 (Victoria) release, Nova supports adding an emulated
|
||||
virtual `Trusted Platform Module`__ (vTPM) to guests.
|
||||
|
||||
.. __: https://en.wikipedia.org/wiki/Trusted_Platform_Module
|
||||
|
||||
|
||||
Enabling vTPM
|
||||
-------------
|
||||
|
||||
The following are required on each compute host wishing to support the vTPM
|
||||
feature:
|
||||
|
||||
* Currently vTPM is only supported when using the libvirt compute driver with a
|
||||
:oslo.config:option:`libvirt.virt_type` of ``kvm`` or ``qemu``.
|
||||
|
||||
* A `key manager service`__, such as `barbican`__, must be configured to store
|
||||
secrets used to encrypt the virtual device files at rest.
|
||||
|
||||
* QEMU version >= 2.11 (>= 2.12 is recommended)
|
||||
|
||||
* Libvirt version >= 5.6.0
|
||||
|
||||
* The swtpm__ binary and associated libraries__.
|
||||
|
||||
* Set the :oslo.config:option:`libvirt.swtpm_enabled` config option to
|
||||
``True``. This will enable support for both TPM version 1.2 and 2.0.
|
||||
|
||||
With the above requirements satisfied, verify vTPM support by inspecting the
|
||||
traits on the compute node's resource provider:
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ openstack resource provider trait list $compute_uuid | grep SECURITY_TPM
|
||||
| COMPUTE_SECURITY_TPM_1_2 |
|
||||
| COMPUTE_SECURITY_TPM_2_0 |
|
||||
|
||||
.. __: https://docs.openstack.org/api-guide/key-manager/
|
||||
.. __: https://docs.openstack.org/barbican/latest/
|
||||
.. __: https://github.com/stefanberger/swtpm/wiki
|
||||
.. __: https://github.com/stefanberger/libtpms/
|
||||
|
||||
|
||||
Configuring a flavor or image
|
||||
-----------------------------
|
||||
|
||||
A vTPM can be requested on a server via :ref:`flavor extra_specs <vtpm-flavor>`
|
||||
or image metadata properties.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Flavor extra_specs
|
||||
- Image metadata
|
||||
- Description
|
||||
* - ``hw:tpm_version``
|
||||
- ``hw_tpm_version``
|
||||
- Specify the TPM version, ``1.2`` or ``2.0``. Required if requesting a
|
||||
vTPM.
|
||||
* - ``hw:tpm_model``
|
||||
- ``hw_tpm_model``
|
||||
- Specify the TPM model, ``tpm-tis`` (the default) or ``tpm-crb`` (only
|
||||
valid with version ``2.0``.
|
||||
|
||||
Scheduling will fail if flavor and image supply conflicting values, or if model
|
||||
``tpm-crb`` is requested with version ``1.2``.
|
||||
|
||||
Upon successful boot, the server should see a TPM device such as ``/dev/tpm0``
|
||||
which can be used in the same manner as a hardware TPM.
|
||||
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
* Only server operations performed by the server owner are supported, as the
|
||||
user's credentials are required to unlock the virtual device files on the
|
||||
host. Thus the admin may need to decide whether to grant the user additional
|
||||
policy roles; if not, those operations are effectively disabled.
|
||||
|
||||
* Live migration, cold migration, resize, evacuation, shelving and rescuing of
|
||||
servers with vTPMs is not currently supported.
|
||||
|
||||
|
||||
Security
|
||||
--------
|
||||
|
||||
With a hardware TPM, the root of trust is a secret known only to the TPM user.
|
||||
In contrast, an emulated TPM comprises a file on disk which the libvirt daemon
|
||||
must be able to present to the guest. At rest, this file is encrypted using a
|
||||
passphrase stored in a key manager service. The passphrase in the key manager
|
||||
is associated with the credentials of the owner of the server (the user who
|
||||
initially created it). The passphrase is retrieved and used by libvirt to
|
||||
unlock the emulated TPM data any time the server is booted.
|
||||
|
||||
Although the above mechanism uses a libvirt secret__ that is both ``private``
|
||||
(can't be displayed via the libvirt API or ``virsh``) and ``ephemeral`` (exists
|
||||
only in memory, never on disk), it is theoretically possible for a sufficiently
|
||||
privileged user to retrieve the secret and/or vTPM data from memory.
|
||||
|
||||
A full analysis and discussion of security issues related to emulated TPM is
|
||||
beyond the scope of this document.
|
||||
|
||||
.. __: https://libvirt.org/formatsecret.html#SecretAttributes
|
||||
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
* `QEMU docs on tpm`__
|
||||
* `Libvirt XML to request emulated TPM device`__
|
||||
* `Libvirt secret for usage type ``vtpm```__
|
||||
|
||||
.. __: https://github.com/qemu/qemu/blob/stable-2.12/docs/specs/tpm.txt
|
||||
.. __: https://libvirt.org/formatdomain.html#elementsTpm
|
||||
.. __: https://libvirt.org/formatsecret.html#vTPMUsageType
|
||||
@ -112,6 +112,7 @@ instance for these kind of workloads.
|
||||
file-backed-memory
|
||||
ports-with-resource-requests
|
||||
virtual-persistent-memory
|
||||
emulated-tpm
|
||||
|
||||
|
||||
Additional guides
|
||||
|
||||
@ -926,3 +926,26 @@ Numbered groupings of resource classes and traits
|
||||
See `Granular Resource Request Syntax`_ for more details.
|
||||
|
||||
.. _Granular Resource Request Syntax: https://specs.openstack.org/openstack/nova-specs/specs/rocky/implemented/granular-resource-requests.html
|
||||
|
||||
.. _vtpm-flavor:
|
||||
|
||||
Emulated Virtual TPM
|
||||
If supported by the compute host, you can add an :doc:`emulated trusted
|
||||
platform module (TPM) </admin/emulated-tpm>` to the guest OS.
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME \
|
||||
--property hw:tpm_version=$VERSION \
|
||||
--property hw:tpm_model=$MODEL
|
||||
|
||||
``hw:tpm_version`` is required to enable support. Valid ``$VERSION`` values
|
||||
are:
|
||||
|
||||
- ``1.2`` : Selects TPM version 1.2 support.
|
||||
- ``2.0`` : Selects TPM version 2.0 support.
|
||||
|
||||
``hw:tpm_model`` is optional. Valid ``$MODEL`` values are:
|
||||
|
||||
- ``tpm-tis``: Selects TIS device model. This is the default value.
|
||||
- ``tpm-crb``: Selects CRB device model. Only valid for TPM version 2.0.
|
||||
|
||||
@ -1636,3 +1636,29 @@ driver-notes.powervm=The PowerVM driver does image caching natively when using
|
||||
the SSP disk driver. It does not use the config options in the [image_cache]
|
||||
group.
|
||||
driver.zvm=missing
|
||||
|
||||
[operation.boot-emulated-tpm]
|
||||
title=Boot instance with an emulated trusted platform module (TPM)
|
||||
status=optional
|
||||
notes=Allows VMs to be booted with an emulated trusted platform module (TPM)
|
||||
device. Only lifecycle operations performed by the VM owner are supported, as
|
||||
the user's credentials are required to unlock the virtual device files on the
|
||||
host.
|
||||
cli=openstack server create <usual server create parameters>
|
||||
driver.xenserver=missing
|
||||
driver.libvirt-kvm-x86=partial
|
||||
driver-notes.libvirt-kvm-x86=Move operations are not yet supported.
|
||||
driver.libvirt-kvm-aarch64=missing
|
||||
driver.libvirt-kvm-ppc64=missing
|
||||
driver.libvirt-kvm-s390x=missing
|
||||
driver.libvirt-qemu-x86=partial
|
||||
driver-notes.libvirt-qemu-x86=Move operations are not yet supported.
|
||||
driver.libvirt-lxc=missing
|
||||
driver.libvirt-xen=missing
|
||||
driver.vmware=missing
|
||||
driver.hyperv=missing
|
||||
driver.ironic=missing
|
||||
driver.libvirt-vz-vm=missing
|
||||
driver.libvirt-vz-ct=missing
|
||||
driver.powervm=missing
|
||||
driver.zvm=missing
|
||||
|
||||
Loading…
Reference in New Issue
Block a user