[libvirt] [PATCH 17/18] docs: Extend Secret XML documentation with vtpm usage type

[Marc-André Lureau]

On Tue, Jul 9, 2019 at 9:24 PM Stefan Berger <stefanb at linux.vnet.ibm.com> wrote:
>
> Extend the Secret XML documentation with vtpm usage type.
>
> Signed-off-by: Stefan Berger <stefanb at linux.ibm.com>
> ---
>  docs/formatsecret.html.in | 61 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 59 insertions(+), 2 deletions(-)
>
> diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
> index defbe71731..aaa31bc76c 100644
> --- a/docs/formatsecret.html.in
> +++ b/docs/formatsecret.html.in
> @@ -42,8 +42,8 @@
>          Specifies what this secret is used for.  A mandatory
>          <code>type</code> attribute specifies the usage category, currently
>          only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
> -        and <code>tls</code> are defined. Specific usage categories
> -        are described below.
> +        <code>tls</code>, and <code>vtpm</code> are defined. Specific usage
> +        categories are described below.
>        </dd>
>      </dl>
>
> @@ -322,6 +322,63 @@ Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
>      <pre>
>  # MYSECRET=`printf %s "letmein" | base64`
>  # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
> +Secret value set
> +
> +    </pre>
> +
> +    <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3>
> +
> +    <p>
> +      This secret is associated with a virtualized TPM (vTPM) and serves
> +      as a passphrase for deriving a key from for encrypting the state
> +      of the vTPM.
> +      The <code><usage type='vtpm'></code> element must contain
> +      a single <code>name</code> element that specifies a usage name
> +      for the secret.  The vTPM secret can then be used by UUID or by
> +      this usage name via the <code><encryption></code> element of
> +      a <a href="formatdomain.html#elementsTpm">tpm</a> when using an
> +      emulator.
> +      <span class="since">Since 5.5.0</span>. The following is an example

will need to be updated, I guess 5.6.0 ?

> +      of the steps to be taken.  First create a vtpm-secret.xml file:    </p>
> +
> +    <pre>
> +# cat vtpm-secret.xml
> +<secret ephemeral='no' private='yes'>
> +   <description>sample vTPM secret</description>
> +   <usage type='vtpm'>
> +      <name>VTPM_example</name>
> +   </usage>
> +</secret>
> +
> +# virsh secret-define vtpm-secret.xml
> +Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
> +
> +# virsh secret-list
> + UUID                                   Usage
> +----------------------------------------------------------------------------------------
> + 6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example
> +
> +#
> +
> +    </pre>
> +
> +    <p>
> +      A secret may also be defined via the
> +      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
> +       <code>virSecretDefineXML</code></a> API.
> +
> +      Once the secret is defined, a secret value will need to be set. The
> +      secret would be the passphrase used to decrypt the vTPM state.
> +      The following is a simple example of using
> +      <code>virsh secret-set-value</code> to set the secret value. The
> +      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
> +      <code>virSecretSetValue</code></a> API may also be used to set
> +      a more secure secret without using printable/readable characters.
> +    </p>
> +
> +    <pre>
> +# MYSECRET=`printf %s "open sesame" | base64`
> +# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
>  Secret value set
>
>      </pre>
> --
> 2.20.1
>
Reviewed-by: Marc-André Lureau <marcandre.lureau at redhat.com>