[libvirt PATCH 2/2] docs: stop mentioning insecure / broken SASL mechanisms

[Daniel P. Berrangé]

We don't need to go to the trouble of telling users about existance of
insecure SASL mechanisms only to then say that they shouldn't be used.
We should only tell people about the GSSAPI mechanism for TCP sockets.

For the SCRAM mechanism we should be telling people about the SHA256
variant only, and also warning that the password database stores the
passwords in clear text.

Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
---
 docs/auth.rst            | 67 ++++++++++++----------------------------
 src/remote/libvirtd.sasl | 11 ++++---
 2 files changed, 26 insertions(+), 52 deletions(-)

diff --git a/docs/auth.rst b/docs/auth.rst
index 506e6b5c13..783ef9231b 100644
--- a/docs/auth.rst
+++ b/docs/auth.rst
@@ -207,61 +207,30 @@ with libvirtd's TLS or TCP socket listeners. When used with the TCP listener,
 the SASL mechanism is required to provide session encryption in addition to
 authentication. Only a very few SASL mechanisms are able to do this, and of
 those that can do it, only the ``GSSAPI`` plugin is considered acceptably secure
-by modern standards:
-
-* **GSSAPI**:
-
-  *This is the current default mechanism to use with libvirtd*.
-  It uses the Kerberos v5 authentication protocol underneath, and assuming
-  the Kerberos client/server are configured with modern ciphers (AES),
-  it provides strong session encryption capabilities.
-
-* **DIGEST-MD5**:
-
-  This was previously set as the default mechanism to use with libvirtd.
-  It provides a simple username/password based authentication mechanism
-  that includes session encryption.
-  `RFC 6331` <https://tools.ietf.org/html/rfc6331>, however,
-  documents a number of serious security flaws with ``DIGEST-MD5`` and as a
-  result marks it as ``OBSOLETE``. Specific concerns are that
-  it is vulnerable to MITM attacks and the ``MD5`` hash can be brute-forced
-  to reveal the password. A replacement is provided via the ``SCRAM`` mechanism,
-  however, note that this does not provide encryption, so the ``SCRAM``
-  mechanism can only be used on the libvirtd TLS listener.
-
-* **PASSDSS-3DES-1**:
-
-  This provides a simple username/password based authentication
-  mechanism that includes session encryption. The current ``cyrus-sasl``
-  implementation does not provide a way to validate the server's
-  public key identity, thus it is susceptible to a MITM attacker
-  impersonating the server. It is also not enabled in many OS
-  distros when building SASL libraries.
-
-* **KERBEROS_V4**:
-
-  This uses the obsolete Kerberos v4 protocol to provide both authentication
-  and session encryption. Kerberos v4 protocol has been obsolete since the
-  early 1990's and has known security vulnerabilities so this will never be
-  used in practice.
-
-Other SASL mechanisms, not listed above, can only be used when the libvirtd
-TLS or UNIX socket listeners.
+by modern standards. ``GSSAPI`` is the default mechanism enabled in the libvirt
+SASL configuration. It uses the Kerberos v5 authentication protocol underneath,
+and assuming the Kerberos client/server are configured with modern ciphers
+(AES), it provides strong session encryption capabilities. All other SASL
+mechanisms should only be used with the libvirtd TLS or UNIX socket listeners.
 
 Username/password auth
 ~~~~~~~~~~~~~~~~~~~~~~
 
-As noted above, the DIGEST-MD5 mechanism is considered obsolete and should
-not be used anymore. To provide a simple username/password auth scheme on
-the libvirt UNIX socket or TLS listeners, however, it is possible to use
-the SCRAM mechanism. The ``auth_unix_ro``, ``auth_unix_rw``,
-``auth_tls`` config params in ``libvirt.conf`` can be used
-to turn on SASL auth in these listeners.
+To provide a simple username/password auth scheme on the libvirt UNIX socket
+or TLS listeners, however, it is possible to use the ``SCRAM`` mechanism, in its
+``SCRAM-SHA-256`` variant. The ``auth_unix_ro``, ``auth_unix_rw``, ``auth_tls``
+config params in ``libvirt.conf`` can be used to turn on SASL auth in these
+listeners.
 
 Since the libvirt SASL config file defaults to using ``GSSAPI`` (Kerberos), a
 config change is required to enable plain password auth. This is done by
 editing ``/etc/sasl2/libvirt.conf`` to set the ``mech_list``
-parameter to ``scram-sha-1``.
+parameter to ``scram-sha-256``.
+
+**Note:** previous versions of libvirt suggested ``DIGEST-MD5`` and
+``SCRAM-SHA-1`` mechanisms. Use of these is strongly discouraged as they are
+not considered secure by modern standards. It is possible to replace them with
+use of ``SCRAM-SHA-256``, while still using the same password database.
 
 Out of the box, no user accounts are defined, so no clients will be able to
 authenticate on the TCP socket. Adding users and setting their passwords is
@@ -291,6 +260,10 @@ again:
 
    # saslpasswd2 -a libvirt -d fred
 
+**Note:** the SASL ``passwd.db`` file stores passwords in clear text, so
+care should be taken not to let its contents be disclosed to unauthorized
+users.
+
 GSSAPI/Kerberos auth
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/src/remote/libvirtd.sasl b/src/remote/libvirtd.sasl
index 7a45470a9d..53596c7c9d 100644
--- a/src/remote/libvirtd.sasl
+++ b/src/remote/libvirtd.sasl
@@ -22,22 +22,23 @@ mech_list: gssapi
 
 # If using a TLS socket or UNIX socket only, it is possible to
 # enable plugins which don't provide session encryption. The
-# 'scram-sha-1' plugin allows plain username/password authentication
+# 'scram-sha-256' plugin allows plain username/password authentication
 # to be performed
 #
-#mech_list: scram-sha-1
+#mech_list: scram-sha-256
 
 #
 # You can also list many mechanisms at once, then the user can choose
 # by adding  '?auth=sasl.gssapi' to their libvirt URI, eg
 #   qemu+tcp://hostname/system?auth=sasl.gssapi
-#mech_list: scram-sha-1 gssapi
+#mech_list: scram-sha-256 gssapi
 
 # File containing the service principal for libvirtd
 #
 keytab: /etc/libvirt/krb5.tab
 
-# If using scram-sha-1 for username/passwds, then this is the file
+# If using scram-sha-256 for username/passwds, then this is the file
 # containing the passwds. Use 'saslpasswd2 -a libvirt [username]'
-# to add entries, and 'sasldblistusers2 -f [sasldb_path]' to browse it
+# to add entries, and 'sasldblistusers2 -f [sasldb_path]' to browse it.
+# Note that this file stores passwords in clear text.
 #sasldb_path: /etc/libvirt/passwd.db
-- 
2.29.2