On 9/20/24 7:45 AM, Marc-André Lureau wrote:
Hi Stefan
On Thu, Sep 19, 2024 at 9:00 PM Stefan Berger <stefanb@xxxxxxxxxxxxx> wrote:
Add documentation for the TPM backend profile node and point the reader to
further documentation about TPM profiles available in the swtpm and
TPMLIB_SetProfile man pages.
Signed-off-by: Stefan Berger <stefanb@xxxxxxxxxxxxx>
---
docs/formatdomain.rst | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 4336cff3ac..abb16df6fc 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -8119,6 +8119,7 @@ Example: usage of the TPM Emulator
<active_pcr_banks>
<sha256/>
</active_pcr_banks>
+ <profile remove_disabled='check'>{"Name":"custom"}</profile>
</backend>
</tpm>
</devices>
@@ -8191,6 +8192,25 @@ Example: usage of the TPM Emulator
and may not have any effect otherwise. The selection of PCR banks only works
with the ``emulator`` backend. :since:`Since 7.10.0`
+``profile``
+ The ``profile`` node is used to set a profile for a TPM 2.0. This profile
+ will be set when the TPM is initially created and after that cannot be
+ changed anymore. If no profile is provided, then swtpm will use the latest
+ 'default' profile. The 'null' profile provides backwards compatibility with
+ libtpms v0.9 but also restricts the user to use only TPM features that were
+ available at the time of libtpms v0.9. The 'custom' profile is the only
+ profile that a user can modify and where the ``remove_disabled`` attribute
+ has any effect. This attribute is particularly useful when a host is running
+ in FIPS mode and therefore some crypto algorithms (camellia, tdes,
+ unpadded RSA encryption, and others) are disabled. When it is set to
+ ``check`` (recommended) then only those algorithms that are currently
+ disabled will automatically be removed from the 'custom' profile, while
+ when it is set to ``fips-host`` then all potentially disabled algorithms
+ will be removed. :since:`Since 10.???.0`
+
+ For further information about TPM profiles see the man pages for ``swtpm``
+ (swtpm v0.10) and libtpms's ``TPMLIB_SetProfile`` (libtpms v0.10).
Here is my feedback, hopefully libvirt maintainers can also comment:
- it is a bit confusing: the name of the profile is inside the element
json configuration, but you further tune/configure it with element
attributes.
Ok, I will change this. No JSON will be embedded in the XML.
- it's specific to swtpm, and not self-explanatory (you need to look
into swtpm manual page)
For someone to dive into this they need good documentation and where do
I all replicate it? TPMLIB_SetProfile needs it and swtpm needs it as
well. swtpm_setup man page points to swtpm and TPMLIB_SetProfile for
more details. Should there be a wiki page? Does libvirt need all the
details of the (design of) profiles as part of its documentation?
- remove_disabled="check" vs "fips-host", I hope we can come up with
something clearer. What are "algorithms that are currently disabled"
vs "potentially disabled algorithms".
currently disabled: The candidate algorithms (tdes, camellia, support
for RSA 1024 bit keys, support for 192 EC keys, unpadded RSA encryption,
PKCS1 padded RSA encryption, signing with SHA1) are all individually
checked whether they are disabled. Fedora, CentOS, and RHEL, and others
have a different set of crypto algorithms disabled when on a FIPS versus
when on a non-FIPS host.
https://github.com/stefanberger/libtpms/wiki/Algorithms-Restrictions:-FIPS-mode,-SHA1-etc.
potentially disabled: all the algorithm candidates that will be tested
for whether they are available when 'check' is chosen are just simply
disabled without testing for them.
+
``encryption``
The ``encryption`` element allows the state of a TPM emulator to be
encrypted. The ``secret`` must reference a secret object that holds the
--
2.46.0
