[libvirt] [PATCH v7 18/19] 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>
Reviewed-by: Marc-André Lureau <marcandre.lureau(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.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..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><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.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
+<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