[PATCH v3 1/9] docs: documentation and schema for the new TPM Proxy model

[Stefan Berger]

On 5/13/20 3:30 PM, Daniel Henrique Barboza wrote:
> QEMU 4.1.0 introduced a new device type called TPM Proxy, currently
> implemented by PPC64 guests via a new virtual device called
> 'spapr-tpm-proxy' (see QEMU 0fb6bd073230 for more info).
>
> The TPM Proxy device interacts with a TPM Resource Manager, a host
> device capable of multiplexing the host TPM with multiple processes.
> This allows multiple guests to access some TPM features at the
> same time. Note that this mode of operation does not provide
> full TPM features to be available for the guest - for that case
> the guest still needs to assign a vTPM device (tpm-spapr for
> PPC64 guests). Although redundant, there is currently no technical
> limitation for a guest to assign both a vTPM and a TPM Proxy at the
> same time.
>
> This patch adds documentation and schema for a new TPM model
> type called 'spapr-tpm-proxy' that creates this new TPM Proxy
> device. This model is valid only for the 'passthrough' backend.
> An example of a TPM Proxy device connected to a TPM Resource Manager
> '/dev/tpmrm0' will look like this:
>
> <tpm model='spapr-tpm-proxy'>
>    <backend type='passthrough'>
>      <device path='/dev/tpmrm0'/>
>    </backend>
> </tpm>
>
> Signed-off-by: Daniel Henrique Barboza <danielhb413 at gmail.com>


Reviewed-by: Stefan Berger <stefanb at linux.ibm.com>


> ---
>   docs/formatdomain.html.in     | 18 +++++++++++++++++-
>   docs/schemas/domaincommon.rng |  1 +
>   2 files changed, 18 insertions(+), 1 deletion(-)
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 23eb029234..15a92aa4f4 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -8792,6 +8792,17 @@ qemu-kvm -net nic,model=? /dev/null
>             backend device is a TPM 2.0. <span class="since">Since 6.1.0</span>,
>             pSeries guests on PPC64 are supported and the default is
>             <code>tpm-spapr</code>.
> +
> +          <span class="since">Since 6.4.0</span>, a new model called
> +          <code>spapr-tpm-proxy</code> was added for pSeries guests. This model
> +          only works with the 'passthrough' backend. It creates a TPM Proxy
> +          device that communicates with an existing TPM Resource Manager in the host,
> +          for example /dev/tpmrm0, enabling the guest to run in secure virtual machine
> +          mode with the help of an Ultravisor. Adding a TPM Proxy to a pSeries guest
> +          brings no security benefits unless the guest is running on a PPC64 host that
> +          has an Ultravisor and a TPM Resource Manager. Only one TPM Proxy device is
> +          allowed per guest, but a TPM Proxy device can be added together with
> +          other TPM devices.
>           </p>
>         </dd>
>         <dt><code>backend</code></dt>
> @@ -8804,7 +8815,7 @@ qemu-kvm -net nic,model=? /dev/null
>             <dt><code>passthrough</code></dt>
>             <dd>
>               <p>
> -              Use the host's TPM device.
> +              Use the host's TPM or TPM Resource Manager device.
>               </p>
>               <p>
>                 This backend type requires exclusive access to a TPM device on
> @@ -8812,6 +8823,11 @@ qemu-kvm -net nic,model=? /dev/null
>                 qualified file name is specified by path attribute of the
>                 <code>source</code> element. If no file name is specified then
>                 /dev/tpm0 is automatically used.
> +
> +              <span class="since">Since 6.4.0</span>, when choosing the
> +              <code>spapr-tpm-proxy</code> model, the file name specified is
> +              expected to be a TPM Resource Manager device, e.g.
> +              /dev/tpmrm0.
>               </p>
>             </dd>
>           </dl>
> diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
> index 9d60b090f3..50860419c3 100644
> --- a/docs/schemas/domaincommon.rng
> +++ b/docs/schemas/domaincommon.rng
> @@ -4610,6 +4610,7 @@
>               <value>tpm-tis</value>
>               <value>tpm-crb</value>
>               <value>tpm-spapr</value>
> +            <value>spapr-tpm-proxy</value>
>             </choice>
>           </attribute>
>         </optional>