[PATCH v1 1/8] docs: documentation and schema for the new TPM Proxy device

[Stefan Berger]

On 5/8/20 8:06 AM, 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 the new TPM Proxy device.
> An example of a TPM Proxy device connected to a TPM Resource Manager
> '/dev/tpmrm0' will look like this:
>
>    <tpmproxy model='spapr-tpm-proxy'>
>      <device path='/dev/tpmrm0'/>
>    </tpmproxy>
>
> Signed-off-by: Daniel Henrique Barboza <danielhb413 at gmail.com>
> ---
>   docs/formatdomain.html.in     | 42 +++++++++++++++++++++++++++++++++++
>   docs/schemas/domaincommon.rng | 18 +++++++++++++++
>   2 files changed, 60 insertions(+)
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 23eb029234..650e2a8c6e 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -8849,6 +8849,48 @@ qemu-kvm -net nic,model=? /dev/null
>         </dd>
>       </dl>
>   
> +    <h4><a id="elementsTpmProxy">TPM Proxy device</a></h4>
> +
> +    <p>
> +      The TPM Proxy device allows a QEMU guest to interact with an
> +      existing TPM Resource Manager in the host. A TPM Resource Manager
> +      enables a TPM device to be securely multiplexed across several
> +      guests. Only one TPM Proxy device is allowed per guest.


I think you should mention SVMs here and that this is what this 
extension is used for or are there other uses than secure VMs?


> +    </p>
> +    <p>
> +      A guest using the TPM Proxy device does not have access to all the
> +      features a TPM device provides. This means that a guest can have both
> +      a TPM Proxy and a TPM device assigned at the same time.


And this TPM Proxy device only enables the H_COMM_TPM hypercall rather 
than talking to /dev/tpm(rm)0 inside the SVM. I think this should be 
clarified because otherwise people might confuse it with the passthrough 
device that does expose /dev/tpm0 inside the VM for example.


> +    </p>
> +    <p>
> +      The TPM Proxy device is currently available only for pSeries guests.
> +      <span class="since">since 6.4.0</span>
> +    </p>
> +    <p>
> +     Example: usage of the TPM Proxy device
> +    </p>
> +<pre>
> +...
> +<devices>
> +  <tpmproxy model='spapr-tpm-proxy'>
> +    <device path='/dev/tpmrm0'/>
> +  </tpmproxy>
> +</devices>
> +...
> +</pre>
> +
> +    <dl>
> +      <dt><code>model</code></dt>
> +      <dd>
> +        <p>
> +          The <code>model</code> attribute specifies what device
> +          model QEMU provides to the guest. If no model name is provided,
> +          <code>spapr-tpm-proxy</code> will automatically be chosen for
> +          PPC64 architectures.
> +        </p>
> +      </dd>
> +    </dl>
> +
>       <h4><a id="elementsNVRAM">NVRAM device</a></h4>
>       <p>
>         nvram device is always added to pSeries guest on PPC64, and its address
> diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
> index 9d60b090f3..44bbd92244 100644
> --- a/docs/schemas/domaincommon.rng
> +++ b/docs/schemas/domaincommon.rng
> @@ -4676,6 +4676,23 @@
>       </optional>
>     </define>
>   
> +  <define name="tpmproxy">
> +    <element name="tpmproxy">
> +      <optional>
> +        <attribute name="model">
> +          <choice>
> +            <value>spapr-tpm-proxy</value>
> +          </choice>
> +        </attribute>
> +      </optional>
> +      <element name="device">
> +        <attribute name="path">
> +          <ref name="filePath"/>
> +        </attribute>
> +      </element>
> +    </element>
> +  </define>
> +
>     <define name="vsock">
>       <element name="vsock">
>         <optional>
> @@ -5279,6 +5296,7 @@
>               <ref name="tpm"/>
>               <ref name="shmem"/>
>               <ref name="memorydev"/>
> +            <ref name="tpmproxy"/>
>             </choice>
>           </zeroOrMore>
>           <optional>