[libvirt] [PATCH v4 22/23] docs: Extend Secret XML documentation with vtpm usage type

Extend the Secret XML documentation with vtpm usage type. Signed-off-by: Stefan Berger <stefanb(a)linux.ibm.com&gt; Reviewed-by: Marc-André Lureau <marcandre.lureau(a)redhat.com&gt; --- 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..8d0630a7c3 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>&lt;usage type='vtpm'&gt;</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>&lt;encryption&gt;</code> element of + a <a href="formatdomain.html#elementsTpm">tpm</a> when using an + emulator. + <span class="since">Since 5.6.0</span>. The following is an example + of the steps to be taken. First create a vtpm-secret.xml file: </p> + + <pre> +# cat vtpm-secret.xml +&lt;secret ephemeral='no' private='yes'&gt; + &lt;description&gt;sample vTPM secret&lt;/description&gt; + &lt;usage type='vtpm'&gt; + &lt;name&gt;VTPM_example&lt;/name&gt; + &lt;/usage&gt; +&lt;/secret&gt; + +# 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