External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 13:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: secret: Unify and sanitize examples on how to set secret value

Browse Source 
Discourage passing secrets as commandline arguments.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Peter Krempa 2020-01-10 16:35:11 +01:00
parent 70c7453895
commit 9dbf6871e6
1 changed files with 58 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/formatsecret.html.in
View File

@ -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>&lt;auth&gt;</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,50 @@ 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-set-value --interactive 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. Alternatively the
<code>--plain</code> option can be omitted if the file contents are
base64-encoded.
</p>
<pre>
# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile
Secret value set
</pre>
<p>
<b>WARNING</b> The following approach is <b>insecure</b> and deprecated.
The secret can also be set via an argument. Note that other users may see
the actual secret in the process listing!
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>