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

[Stefan Berger]

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