[libvirt] [PATCH 4/4] docs: secret: Unify and sanitize examples on how to set secret value

[Peter Krempa]

Discourage passing secrets as commandline arguments.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatsecret.html.in | 86 +++++++++++++++++++++++++--------------
 1 file changed, 55 insertions(+), 31 deletions(-)

diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
index 8f5383cf64..61a8396682 100644
--- a/docs/formatsecret.html.in
+++ b/docs/formatsecret.html.in
@@ -76,13 +76,13 @@
     <pre>
 # virsh secret-define volume-secret.xml
 Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
-#
-# MYSECRET=`printf %s "open sesame" | base64`
-# virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
-Secret value set
-#
     </pre>

+    <p>
+      See <a href="#settingSecrets">virsh secret-set-value</a> on how
+      to set the value of the secret.
+    </p>
+
     <p>
       The volume type secret can be supplied either in volume XML during
       creation of a <a href="formatstorage.html#StorageVol">storage volume</a>
@@ -103,12 +103,11 @@ Secret value set

 # virsh secret-define luks-secret.xml
 Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
-#
-# MYSECRET=`printf %s "letmein" | base64`
-# virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
-Secret value set
-#
     </pre>
+    <p>
+      See <a href="#settingSecrets">virsh secret-set-value</a> on how
+      to set the value of the secret.
+    </p>

     <p>
       The volume type secret can be supplied in domain XML for a luks storage
@@ -156,13 +155,11 @@ Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
  UUID                                 Usage
 -----------------------------------------------------------
  1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
-#
-# CEPHPHRASE=`printf %s "pass phrase" | base64`
-# virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
-Secret value set
-
-#
     </pre>
+    <p>
+      See <a href="#settingSecrets">virsh secret-set-value</a> on how
+      to set the value of the secret.
+    </p>

     <p>
       The ceph secret can then be used by UUID or by the
@@ -229,7 +226,9 @@ incominguser myname mysecret

     <p>
       Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
-      the secret and <code>virsh secret-set-value</code> using the generated
+      the secret and
+      <code><a href="#settingSecrets">virsh secret-set-value</a></code>
+      using the generated
       UUID value and a base64 generated secret value in order to define the
       chosen secret pass phrase.  The pass phrase must match the password
       used in the iSCSI authentication configuration file.
@@ -243,12 +242,13 @@ Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
 -----------------------------------------------------------
  c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi

-# MYSECRET=`printf %s "mysecret" | base64`
-# virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
-Secret value set
-#
     </pre>

+    <p>
+      See <a href="#settingSecrets">virsh secret-set-value</a> on how
+      to set the value of the secret.
+    </p>
+
     <p>
       The iSCSI secret can then be used by UUID or by the
       usage name via the <code><auth></code> element in a domain's
@@ -313,19 +313,13 @@ Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
       Once the secret is defined, a secret value will need to be set. The
       secret would be the passphrase used to access the TLS credentials.
       The following is a simple example of using
-      <code>virsh secret-set-value</code> to set the secret value. The
+      <code><a href="#settingSecrets">virsh secret-set-value</a></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 "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>
@@ -370,17 +364,47 @@ Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
       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
+      <code><a href="#settingSecrets">virsh secret-set-value</a></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>

+    <h2><a id="settingSecrets">Setting secret values in virsh</a></h2>
+
+    <p>
+      To set the value of the secret you can use the following virsh commands.
+      If the secret is a password-like string (printable characters, no newline)
+      you can use:
+    </p>
+    <pre>
+# virsh secret-passwd 6dd3e4a5-1d76-44ce-961f-f119f5aad935
+Enter new value for secret:
+Secret value set
+    </pre>
+
+    <p>
+      Another secure option is to read the secret from a file. This way the
+      secret can contain any bytes (even NUL and non-printable characters). The
+      length of the secret is the length of the input file.
+    </p>
+
+    <pre>
+# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file secretinfile
+Secret value set
+    </pre>
+
+    <p>
+      The secret can also be set via an argument, but note that other users
+      may see it in the process listing output. The secret must be base64
+      encoded.
+    </p>
+
     <pre>
 # MYSECRET=`printf %s "open sesame" | base64`
 # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
 Secret value set
-
     </pre>

   </body>
-- 
2.24.1