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@linux.ibm.com>
---
 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).
+
 ``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

Hi Stefan

On Thu, Sep 19, 2024 at 9:00 PM Stefan Berger <stefanb@linux.ibm.com> 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@linux.ibm.com>
> ---
>  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.
- it's specific to swtpm, and not self-explanatory (you need to look
into swtpm manual page)
- 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".



> +
>  ``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
>

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@linux.ibm.com> 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@linux.ibm.com>
>> ---
>>   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
>>
>