[libvirt] [PATCH 4/4] docs: secret: Unify and sanitize examples on how to set secret value
Daniel P. Berrangé
berrange at redhat.com
Tue Jan 21 13:39:49 UTC 2020
On Fri, Jan 10, 2020 at 04:42:44PM +0100, Peter Krempa wrote:
> 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>
This paragraph will need updating based on my prev patch comments.
Overall this patch looks good though.
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
More information about the libvir-list
mailing list