7:10 p.m.
GSSAPI and SCRAM-SHA-256 are the only two SASL mechanisms we
especially want people to be using. Even the latter is a little
questionable due to storing passwords in cleartext on the server.
Daniel P. Berrangé (2):
docs: convert auth page into RST format
docs: stop mentioning insecure / broken SASL mechanisms
docs/auth.html.in | 368 ---------------------------------------
docs/auth.rst | 323 ++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
src/remote/libvirtd.sasl | 11 +-
4 files changed, 330 insertions(+), 374 deletions(-)
delete mode 100644 docs/auth.html.in
create mode 100644 docs/auth.rst
--
2.29.2
7:10 p.m.
New subject: [libvirt PATCH 1/2] docs: convert auth page into RST format
Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/auth.html.in | 368 ----------------------------------------------
docs/auth.rst | 350 +++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 351 insertions(+), 369 deletions(-)
delete mode 100644 docs/auth.html.in
create mode 100644 docs/auth.rst
diff --git a/docs/auth.html.in b/docs/auth.html.in
deleted file mode 100644
index 9b940a8598..0000000000
--- a/docs/auth.html.in
+++ /dev/null
@@ -1,368 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Connection authentication</h1>
- <p>
- When connecting to libvirt, some connections may require client
- authentication before allowing use of the APIs. The set of possible
- authentication mechanisms is administrator controlled, independent
- of applications using libvirt. Once authenticated, libvirt can apply
- fine grained <a href="acl.html">access control</a> to the
operations
- performed by a client.
- </p>
-
- <ul id="toc"></ul>
-
- <h2><a id="Auth_client_config">Client
configuration</a></h2>
-
- <p>
- When connecting to a remote hypervisor which requires authentication,
-most libvirt applications will prompt the user for the credentials. It is
-also possible to provide a client configuration file containing all the
-authentication credentials, avoiding any interaction. Libvirt will look
-for the authentication file using the following sequence:
- </p>
- <ol>
- <li>The file path specified by the $LIBVIRT_AUTH_FILE environment
- variable.</li>
- <li>The file path specified by the "authfile=/some/file" URI
- query parameter</li>
- <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li>
- <li>The file /etc/libvirt/auth.conf</li>
- </ol>
-
- <p>
- The auth configuration file uses the traditional
<code>".ini"</code>
- style syntax. There are two types of groups that can be present in
- the config. First there are one or more <strong>credential</strong>
- sets, which provide the actual authentication credentials. The keys
- within the group may be:
- </p>
-
- <ul>
- <li><code>username</code>: the user login name to act as. This
- is relevant for ESX, Xen, HyperV and SSH, but probably not
- the one you want to libvirtd with SASL.</li>
- <li><code>authname</code>: the name to authorize as. This is
- what is commonly required for libvirtd with SASL.</li>
- <li><code>password</code>: the secret password</li>
- <li><code>realm</code>: the domain realm for SASL, mostly
- unused</li>
- </ul>
-
- <p>
- Each set of credentials has a name, which is part of the group
- entry name. Overall the syntax is
- </p>
-
- <pre>
-[credentials-$NAME]
-credname1=value1
-credname2=value2</pre>
-
- <p>
- For example, to define two sets of credentials used for production
- and test machines, using libvirtd, and a further ESX server for dev:
- </p>
-<pre>
-[credentials-test]
-authname=fred
-password=123456
-
-[credentials-prod]
-authname=bar
-password=letmein
-
-[credentials-dev]
-username=joe
-password=hello
-
-[credentials-defgrp]
-username=defuser
-password=defpw</pre>
-
- <p>
- The second set of groups provide mappings of credentials to
- specific machine services. The config file group names compromise
- the service type and host:
- </p>
-
- <pre>
-[auth-$SERVICE-$HOSTNAME]
-credentials=$CREDENTIALS</pre>
-
- <p>
- For example, following the previous example, here is how to
- map some machines. For convenience libvirt supports a default
- mapping of credentials to machines:
- </p>
-
- <pre>
-[auth-libvirt-test1.example.com]
-credentials=test
-
-[auth-libvirt-test2.example.com]
-credentials=test
-
-[auth-libvirt-demo3.example.com]
-credentials=test
-
-[auth-libvirt-prod1.example.com]
-credentials=prod
-
-[auth-libvirt-default]
-credentials=defgrp
-
-[auth-esx-dev1.example.com]
-credentials=dev
-
-[auth-esx-default]
-credentials=defgrp</pre>
-
-
- <p>
- The following service types are known to libvirt:
- </p>
-
- <ul>
- <li><code>esx</code> - used for connections to an ESX or
- VirtualCenter server</li>
- <li><code>hyperv</code> - used for connections to an HyperV
- server</li>
- <li><code>libvirt</code> - used for connections to a libvirtd
- server, which is configured with SASL auth</li>
- <li><code>ssh</code> - used for connections to a remote QEMU
driver
- over SSH</li>
- </ul>
-
- <p>
- Applications using libvirt are free to use this same configuration
- file for storing other credentials. For example, it can be used
- to storage VNC or SPICE login credentials
- </p>
-
- <h2><a id="ACL_server_config">Server
configuration</a></h2>
- <p>
-The libvirt daemon allows the administrator to choose the authentication
-mechanisms used for client connections on each network socket independently.
-This is primarily controlled via the libvirt daemon master config file in
-<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
-have its authentication mechanism configured independently. There is
-currently a choice of <code>none</code>, <code>polkit</code>, and
<code>sasl</code>.
-The SASL scheme can be further configured to choose between a large
-number of different mechanisms.
-</p>
- <h2><a id="ACL_server_unix_perms">UNIX socket
permissions/group</a></h2>
- <p>
-If libvirt does not contain support for PolicyKit, then access control for
-the UNIX domain socket is done using traditional file user/group ownership
-and permissions. There are 2 sockets, one for full read-write access, the
-other for read-only access. The RW socket will be restricted (mode 0700) to
-only allow the <code>root</code> user to connect. The read-only socket will
-be open access (mode 0777) to allow any user to connect.
-</p>
- <p>
-To allow non-root users greater access, the <code>libvirtd.conf</code> file
-can be edited to change the permissions via the
<code>unix_sock_rw_perms</code>,
-config parameter and to set a user group via the
<code>unix_sock_group</code>
-parameter. For example, setting the former to mode <code>0770</code> and the
-latter <code>wheel</code> would let any user in the wheel group connect to
-the libvirt daemon.
-</p>
- <h2><a id="ACL_server_polkit">UNIX socket PolicyKit
auth</a></h2>
- <p>
-If libvirt contains support for PolicyKit, then access control options are
-more advanced. The <code>auth_unix_rw</code> parameter will default to
-<code>polkit</code>, and the file permissions will default to
<code>0777</code>
-even on the RW socket. Upon connecting to the socket, the client application
-will be required to identify itself with PolicyKit. The default policy for the
-RW daemon socket will require any application running in the current desktop
-session to authenticate using the user's password. This is akin to
<code>sudo</code>
-auth, but does not require that the client application ultimately run as root.
-Default policy will still allow any application to connect to the RO socket.
-</p>
- <p>
-The default policy can be overridden by creating a new policy file in the
-<code>/etc/polkit-1/rules.d</code> directory. Information on the options
-available can be found by reading the <code>polkit(8)</code> man page. The
-two libvirt actions are named <code>org.libvirt.unix.manage</code> for full
-management access, and <code>org.libvirt.unix.monitor</code> for read-only
-access.
-</p>
- <p>
-As an example, creating
<code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code>
-with the following gives the user <code>fred</code> full management access
-when accessing from an active local session:
- </p>
-<pre>polkit.addRule(function(action, subject) {
- if (action.id == "org.libvirt.unix.manage" &&
- subject.local && subject.active && subject.user ==
"fred") {
- return polkit.Result.YES;
- }
-});</pre>
- <p>
-Older versions of PolicyKit used policy files ending with .pkla in the
-local override directory
<code>/etc/polkit-1/localauthority/50-local.d/</code>.
-Compatibility with this older format is provided by <a
-href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As
an
-example, this gives the user <code>fred</code> full management access:
- </p>
-<pre>[Allow fred libvirt management permissions]
-Identity=unix-user:fred
-Action=org.libvirt.unix.manage
-ResultAny=yes
-ResultInactive=yes
-ResultActive=yes</pre>
- <h2><a id="ACL_server_sasl">SASL pluggable
authentication</a></h2>
-
- <p>
-Libvirt integrates with the cyrus-sasl library to provide a pluggable authentication
-system using the SASL protocol. SASL can be used in combination with libvirtd's TLS
-or TCP socket listeners. When used with the TCP listener, the SASL mechanism is
-rqeuired 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:
- </p>
-
- <dl>
- <dt>GSSAPI</dt>
- <dd><strong>This is the current default mechanism to use with
libvirtd</strong>.
- 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.</dd>
-
- <dt>DIGEST-MD5</dt>
- <dd>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.
- <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>,
however,
- documents a number of serious security flaws with DIGEST-MD5 and as a
- result marks it as <code>OBSOLETE</code>. 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.
- </dd>
-
- <dt>PASSDSS-3DES-1</dt>
- <dd>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.</dd>
-
- <dt>KERBEROS_V4</dt>
- <dd>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.</dd>
- </dl>
-
- <p>
- Other SASL mechanisms, not listed above, can only be used when the libvirtd
- TLS or UNIX socket listeners.
- </p>
-
- <h3><a id="ACL_server_username">Username/password
auth</a></h3>
- <p>
-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 <code>auth_unix_ro</code>,
<code>auth_unix_rw</code>,
-<code>auth_tls</code> config params in <code>libvirt.conf</code>
can be used
-to turn on SASL auth in these listeners.
- </p>
- <p>
-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 <code>/etc/sasl2/libvirt.conf</code> to set the
<code>mech_list</code>
-parameter to <code>scram-sha-1</code>.
- </p>
- <p>
-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 done with the
<code>saslpasswd2</code>
-command. When running this command it is important to tell it that the appname is
<code>libvirt</code>.
-As an example, to add a user <code>fred</code>, run
-</p>
- <pre>
-# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-</pre>
- <p>
-To see a list of all accounts the <code>sasldblistusers2</code> command can
be used.
-This command expects to be given the path to the libvirt user database, which is kept
-in <code>/etc/libvirt/passwd.db</code>
-</p>
- <pre>
-# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred(a)t60wlan.home.berrange.com: userPassword
-</pre>
- <p>
-Finally, to disable a user's access, the <code>saslpasswd2</code> command
can be used
-again:
-</p>
- <pre>
-# saslpasswd2 -a libvirt -d fred
-</pre>
- <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos
auth</a></h3>
- <p>
-The plain TCP listener of the libvirt daemon defaults to using SASL for authentication.
-The libvirt SASL config also defaults to GSSAPI, so there is no need to edit the
-SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are used,
-then the Kerberos session encryption will be disabled since it is not required
-in these scenarios - only the plain TCP listener needs encryption
-</p>
- <p>
-Some operating systems do not install the SASL kerberos plugin by default. It
-may be necessary to install a sub-package such as
<code>cyrus-sasl-gssapi</code>.
-To check whether the Kerberos plugin is installed run the
<code>pluginviewer</code>
-program and verify that <code>gssapi</code> is listed, e.g.:
-</p>
- <pre>
-# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded], API version: 4
- SASL mechanism: GSSAPI, best SSF: 56
- security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
- features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-</pre>
- <p>
-Next it is necessary for the administrator of the Kerberos realm to
-issue a principal for the libvirt server. There needs to be one
-principal per host running the libvirt daemon. The principal should be
-named <code>libvirt/full.hostname(a)KERBEROS.REALM</code>. This is
-typically done by running the <code>kadmin.local</code> command on the
-Kerberos server, though some Kerberos servers have alternate ways of
-setting up service principals. Once created, the principal should be
-exported to a keytab, copied to the host running the libvirt daemon
-and placed in <code>/etc/libvirt/krb5.tab</code>
-</p>
- <pre>
-# kadmin.local
-kadmin.local: add_principal libvirt/foo.example.com
-Enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
-Principal "libvirt/foo.example.com(a)EXAMPLE.COM" created.
-
-kadmin.local: ktadd -k /root/libvirt-foo-example.tab
libvirt/foo.example.com(a)EXAMPLE.COM
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type DES
with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type DES
cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-
-kadmin.local: quit
-
-# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
-# rm /root/libvirt-foo-example.tab
-</pre>
- <p>
-Any client application wishing to connect to a Kerberos enabled libvirt server
-merely needs to run <code>kinit</code> to gain a user principal. This may
well
-be done automatically when a user logs into a desktop session, if PAM is set up
-to authenticate against Kerberos.
-</p>
- </body>
-</html>
diff --git a/docs/auth.rst b/docs/auth.rst
new file mode 100644
index 0000000000..506e6b5c13
--- /dev/null
+++ b/docs/auth.rst
@@ -0,0 +1,350 @@
+=========================
+Connection authentication
+=========================
+
+.. contents::
+
+When connecting to libvirt, some connections may require client
+authentication before allowing use of the APIs. The set of possible
+authentication mechanisms is administrator controlled, independent
+of applications using libvirt. Once authenticated, libvirt can apply
+fine grained `access control <acl.html>`_ to the operations
+performed by a client.
+
+Client configuration
+====================
+
+When connecting to a remote hypervisor which requires authentication,
+most libvirt applications will prompt the user for the credentials. It is
+also possible to provide a client configuration file containing all the
+authentication credentials, avoiding any interaction. Libvirt will look
+for the authentication file using the following sequence:
+
+* The file path specified by the ``$LIBVIRT_AUTH_FILE`` environment
+ variable.
+* The file path specified by the ``authfile=/some/file`` URI
+ query parameter
+* The file ``$XDG_CONFIG_HOME/libvirt/auth.conf``
+* The file ``/etc/libvirt/auth.conf``
+
+The auth configuration file uses the traditional ``.ini``
+style syntax. There are two types of groups that can be present in
+the config. First there are one or more ``credential``
+sets, which provide the actual authentication credentials. The keys
+within the group may be:
+
+* ``username``: the user login name to act as. This
+ is relevant for ESX, Xen, HyperV and SSH, but probably not
+ the one you want to libvirtd with SASL.
+* ``authname``: the name to authorize as. This is
+ what is commonly required for libvirtd with SASL.
+* ``password``: the secret password.
+* ``realm``: the domain realm for SASL, mostly unused.
+
+Each set of credentials has a name, which is part of the group
+entry name. Overall the syntax is
+
+::
+
+ [credentials-$NAME]
+ credname1=value1
+ credname2=value2
+
+
+For example, to define two sets of credentials used for production
+and test machines, using libvirtd, and a further ESX server for dev:
+
+::
+
+ [credentials-test]
+ authname=fred
+ password=123456
+
+ [credentials-prod]
+ authname=bar
+ password=letmein
+
+ [credentials-dev]
+ username=joe
+ password=hello
+
+ [credentials-defgrp]
+ username=defuser
+ password=defpw
+
+The second set of groups provide mappings of credentials to
+specific machine services. The config file group names compromise
+the service type and host:
+
+::
+
+ [auth-$SERVICE-$HOSTNAME]
+ credentials=$CREDENTIALS</pre>
+
+For example, following the previous example, here is how to
+map some machines. For convenience libvirt supports a default
+mapping of credentials to machines:
+
+::
+
+ [auth-libvirt-test1.example.com]
+ credentials=test
+
+ [auth-libvirt-test2.example.com]
+ credentials=test
+
+ [auth-libvirt-demo3.example.com]
+ credentials=test
+
+ [auth-libvirt-prod1.example.com]
+ credentials=prod
+
+ [auth-libvirt-default]
+ credentials=defgrp
+
+ [auth-esx-dev1.example.com]
+ credentials=dev
+
+ [auth-esx-default]
+ credentials=defgrp
+
+The following service types are known to libvirt:
+
+* ``esx`` - used for connections to an ESX or VirtualCenter server
+* ``hyperv`` - used for connections to an HyperV server
+* ``libvirt`` - used for connections to a libvirtd
+ server, which is configured with SASL auth
+* ``ssh`` - used for connections to a remote QEMU driver over SSH
+
+
+Applications using libvirt are free to use this same configuration
+file for storing other credentials. For example, it can be used
+to storage VNC or SPICE login credentials
+
+Server configuration
+====================
+
+The libvirt daemon allows the administrator to choose the authentication
+mechanisms used for client connections on each network socket independently.
+This is primarily controlled via the libvirt daemon master config file in
+``/etc/libvirt/libvirtd.conf``. Each of the libvirt sockets can
+have its authentication mechanism configured independently. There is
+currently a choice of ``none``, ``polkit``, and ``sasl``.
+The SASL scheme can be further configured to choose between a large
+number of different mechanisms.
+
+UNIX socket permissions/group
+-----------------------------
+
+If libvirt does not contain support for PolicyKit, then access control for
+the UNIX domain socket is done using traditional file user/group ownership
+and permissions. There are 2 sockets, one for full read-write access, the
+other for read-only access. The RW socket will be restricted (mode 0700) to
+only allow the ``root`` user to connect. The read-only socket will
+be open access (mode 0777) to allow any user to connect.
+
+To allow non-root users greater access, the ``libvirtd.conf`` file
+can be edited to change the permissions via the ``unix_sock_rw_perms``,
+config parameter and to set a user group via the ``unix_sock_group``
+parameter. For example, setting the former to mode ``0770`` and the
+latter ``wheel`` would let any user in the wheel group connect to
+the libvirt daemon.
+
+UNIX socket PolicyKit auth
+--------------------------
+
+If libvirt contains support for PolicyKit, then access control options are
+more advanced. The ``auth_unix_rw`` parameter will default to
+``polkit``, and the file permissions will default to ``0777``
+even on the RW socket. Upon connecting to the socket, the client application
+will be required to identify itself with PolicyKit. The default policy for the
+RW daemon socket will require any application running in the current desktop
+session to authenticate using the user's password. This is akin to ``sudo``
+auth, but does not require that the client application ultimately run as root.
+Default policy will still allow any application to connect to the RO socket.
+
+The default policy can be overridden by creating a new policy file in the
+``/etc/polkit-1/rules.d`` directory. Information on the options
+available can be found by reading the ``polkit(8)`` man page. The
+two libvirt actions are named ``org.libvirt.unix.manage`` for full
+management access, and ``org.libvirt.unix.monitor`` for read-only
+access.
+
+As an example, creating ``/etc/polkit-1/rules.d/80-libvirt-manage.rules``
+with the following gives the user ``fred`` full management access
+when accessing from an active local session:
+
+::
+
+ polkit.addRule(function(action, subject) {
+ if (action.id == "org.libvirt.unix.manage" &&
+ subject.local && subject.active &&; subject.user ==
"fred") {
+ return polkit.Result.YES;
+ }
+ });
+
+Older versions of PolicyKit used policy files ending with .pkla in the
+local override directory ``/etc/polkit-1/localauthority/50-local.d/``.
+Compatibility with this older format is provided by
+`polkit-pkla-compat <https://pagure.io/polkit-pkla-compat>`_. As an
+example, this gives the user ``fred`` full management access:
+
+::
+
+ [Allow fred libvirt management permissions]
+ Identity=unix-user:fred
+ Action=org.libvirt.unix.manage
+ ResultAny=yes
+ ResultInactive=yes
+ ResultActive=yes
+
+SASL pluggable authentication
+-----------------------------
+
+Libvirt integrates with the ``cyrus-sasl`` library to provide a pluggable
+authentication system using the SASL protocol. SASL can be used in combination
+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.
+
+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.
+
+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``.
+
+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
+done with the ``saslpasswd2`` command. When running this command it is
+important to tell it that the appname is ``libvirt``. As an example, to add
+a user ``fred``, run
+
+::
+
+ # saslpasswd2 -a libvirt fred
+ Password: xxxxxx
+ Again (for verification): xxxxxx
+
+To see a list of all accounts the ``sasldblistusers2`` command can be used.
+This command expects to be given the path to the libvirt user database, which
+is kept in ``/etc/libvirt/passwd.db``
+
+::
+
+ # sasldblistusers2 -f /etc/libvirt/passwd.db
+ fred(a)t60wlan.home.berrange.com: userPassword
+
+Finally, to disable a user's access, the ``saslpasswd2`` command can be used
+again:
+
+::
+
+ # saslpasswd2 -a libvirt -d fred
+
+GSSAPI/Kerberos auth
+~~~~~~~~~~~~~~~~~~~~
+
+The plain TCP listener of the libvirt daemon defaults to using SASL for
+authentication. The libvirt SASL config also defaults to ``GSSAPI``, so there
+is no need to edit the SASL config when using ``GSSAPI``. If the libvirtd TLS
+or UNIX listeners are used, then the Kerberos session encryption will be
+disabled since it is not required in these scenarios - only the plain TCP
+listener needs encryption.
+
+Some operating systems do not install the SASL kerberos plugin by default. It
+may be necessary to install a sub-package such as ``cyrus-sasl-gssapi``.
+To check whether the Kerberos plugin is installed run the ``pluginviewer``
+program and verify that ``gssapi`` is listed, e.g.:
+
+::
+
+ # pluginviewer
+ ...snip...
+ Plugin "gssapiv2" [loaded], API version: 4
+ SASL mechanism: GSSAPI, best SSF: 56
+ security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
+ features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
+
+Next it is necessary for the administrator of the Kerberos realm to
+issue a principal for the libvirt server. There needs to be one
+principal per host running the libvirt daemon. The principal should be
+named ``libvirt/full.hostname(a)KERBEROS.REALM``. This is
+typically done by running the ``kadmin.local`` command on the
+Kerberos server, though some Kerberos servers have alternate ways of
+setting up service principals. Once created, the principal should be
+exported to a keytab, copied to the host running the libvirt daemon
+and placed in ``/etc/libvirt/krb5.tab``
+
+::
+
+ # kadmin.local
+ kadmin.local: add_principal libvirt/foo.example.com
+ Enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
+ Re-enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
+ Principal "libvirt/foo.example.com(a)EXAMPLE.COM" created.
+
+ kadmin.local: ktadd -k /root/libvirt-foo-example.tab
libvirt/foo.example.com(a)EXAMPLE.COM
+ Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+ Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+ Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+ Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+
+ kadmin.local: quit
+
+ # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
+ # rm /root/libvirt-foo-example.tab
+
+Any client application wishing to connect to a Kerberos enabled libvirt server
+merely needs to run ``kinit`` to gain a user principal. This may well
+be done automatically when a user logs into a desktop session, if PAM is set up
+to authenticate against Kerberos.
diff --git a/docs/meson.build b/docs/meson.build
index 5536005125..cb4ab676d6 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -38,7 +38,6 @@ docs_html_in_files = [
'apps',
'architecture',
'auditlog',
- 'auth',
'bindings',
'bugs',
'cgroups',
@@ -107,6 +106,7 @@ docs_html_in_files = [
docs_rst_files = [
'advanced-tests',
+ 'auth',
'best-practices',
'ci',
'coding-style',
--
2.29.2
2:06 p.m.
New subject: [libvirt PATCH 1/2] docs: convert auth page into RST format
On Thu, Mar 04, 2021 at 06:10:12PM +0000, Daniel P. Berrangé wrote:
Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/auth.html.in | 368 ----------------------------------------------
docs/auth.rst | 350 +++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 351 insertions(+), 369 deletions(-)
delete mode 100644 docs/auth.html.in
create mode 100644 docs/auth.rst
diff --git a/docs/auth.html.in b/docs/auth.html.in
deleted file mode 100644
index 9b940a8598..0000000000
--- a/docs/auth.html.in
+++ /dev/null
@@ -1,368 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Connection authentication</h1>
- <p>
- When connecting to libvirt, some connections may require client
- authentication before allowing use of the APIs. The set of possible
- authentication mechanisms is administrator controlled, independent
- of applications using libvirt. Once authenticated, libvirt can apply
- fine grained <a href="acl.html">access control</a> to the
operations
- performed by a client.
- </p>
-
- <ul id="toc"></ul>
-
- <h2><a id="Auth_client_config">Client
configuration</a></h2>
-
- <p>
- When connecting to a remote hypervisor which requires authentication,
-most libvirt applications will prompt the user for the credentials. It is
-also possible to provide a client configuration file containing all the
-authentication credentials, avoiding any interaction. Libvirt will look
-for the authentication file using the following sequence:
- </p>
- <ol>
- <li>The file path specified by the $LIBVIRT_AUTH_FILE environment
- variable.</li>
- <li>The file path specified by the "authfile=/some/file" URI
- query parameter</li>
- <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li>
- <li>The file /etc/libvirt/auth.conf</li>
- </ol>
-
- <p>
- The auth configuration file uses the traditional
<code>".ini"</code>
- style syntax. There are two types of groups that can be present in
- the config. First there are one or more <strong>credential</strong>
- sets, which provide the actual authentication credentials. The keys
- within the group may be:
- </p>
-
- <ul>
- <li><code>username</code>: the user login name to act as. This
- is relevant for ESX, Xen, HyperV and SSH, but probably not
- the one you want to libvirtd with SASL.</li>
- <li><code>authname</code>: the name to authorize as. This is
- what is commonly required for libvirtd with SASL.</li>
- <li><code>password</code>: the secret password</li>
- <li><code>realm</code>: the domain realm for SASL, mostly
- unused</li>
- </ul>
-
- <p>
- Each set of credentials has a name, which is part of the group
- entry name. Overall the syntax is
- </p>
-
- <pre>
-[credentials-$NAME]
-credname1=value1
-credname2=value2</pre>
-
- <p>
- For example, to define two sets of credentials used for production
- and test machines, using libvirtd, and a further ESX server for dev:
- </p>
-<pre>
-[credentials-test]
-authname=fred
-password=123456
-
-[credentials-prod]
-authname=bar
-password=letmein
-
-[credentials-dev]
-username=joe
-password=hello
-
-[credentials-defgrp]
-username=defuser
-password=defpw</pre>
-
- <p>
- The second set of groups provide mappings of credentials to
- specific machine services. The config file group names compromise
- the service type and host:
- </p>
-
- <pre>
-[auth-$SERVICE-$HOSTNAME]
-credentials=$CREDENTIALS</pre>
-
- <p>
- For example, following the previous example, here is how to
- map some machines. For convenience libvirt supports a default
- mapping of credentials to machines:
- </p>
-
- <pre>
-[auth-libvirt-test1.example.com]
-credentials=test
-
-[auth-libvirt-test2.example.com]
-credentials=test
-
-[auth-libvirt-demo3.example.com]
-credentials=test
-
-[auth-libvirt-prod1.example.com]
-credentials=prod
-
-[auth-libvirt-default]
-credentials=defgrp
-
-[auth-esx-dev1.example.com]
-credentials=dev
-
-[auth-esx-default]
-credentials=defgrp</pre>
-
-
- <p>
- The following service types are known to libvirt:
- </p>
-
- <ul>
- <li><code>esx</code> - used for connections to an ESX or
- VirtualCenter server</li>
- <li><code>hyperv</code> - used for connections to an HyperV
- server</li>
- <li><code>libvirt</code> - used for connections to a libvirtd
- server, which is configured with SASL auth</li>
- <li><code>ssh</code> - used for connections to a remote QEMU
driver
- over SSH</li>
- </ul>
-
- <p>
- Applications using libvirt are free to use this same configuration
- file for storing other credentials. For example, it can be used
- to storage VNC or SPICE login credentials
- </p>
-
- <h2><a id="ACL_server_config">Server
configuration</a></h2>
- <p>
-The libvirt daemon allows the administrator to choose the authentication
-mechanisms used for client connections on each network socket independently.
-This is primarily controlled via the libvirt daemon master config file in
-<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
-have its authentication mechanism configured independently. There is
-currently a choice of <code>none</code>, <code>polkit</code>,
and <code>sasl</code>.
-The SASL scheme can be further configured to choose between a large
-number of different mechanisms.
-</p>
- <h2><a id="ACL_server_unix_perms">UNIX socket
permissions/group</a></h2>
- <p>
-If libvirt does not contain support for PolicyKit, then access control for
-the UNIX domain socket is done using traditional file user/group ownership
-and permissions. There are 2 sockets, one for full read-write access, the
-other for read-only access. The RW socket will be restricted (mode 0700) to
-only allow the <code>root</code> user to connect. The read-only socket will
-be open access (mode 0777) to allow any user to connect.
-</p>
- <p>
-To allow non-root users greater access, the <code>libvirtd.conf</code> file
-can be edited to change the permissions via the
<code>unix_sock_rw_perms</code>,
-config parameter and to set a user group via the
<code>unix_sock_group</code>
-parameter. For example, setting the former to mode <code>0770</code> and
the
-latter <code>wheel</code> would let any user in the wheel group connect to
-the libvirt daemon.
-</p>
- <h2><a id="ACL_server_polkit">UNIX socket PolicyKit
auth</a></h2>
- <p>
-If libvirt contains support for PolicyKit, then access control options are
-more advanced. The <code>auth_unix_rw</code> parameter will default to
-<code>polkit</code>, and the file permissions will default to
<code>0777</code>
-even on the RW socket. Upon connecting to the socket, the client application
-will be required to identify itself with PolicyKit. The default policy for the
-RW daemon socket will require any application running in the current desktop
-session to authenticate using the user's password. This is akin to
<code>sudo</code>
-auth, but does not require that the client application ultimately run as root.
-Default policy will still allow any application to connect to the RO socket.
-</p>
- <p>
-The default policy can be overridden by creating a new policy file in the
-<code>/etc/polkit-1/rules.d</code> directory. Information on the options
-available can be found by reading the <code>polkit(8)</code> man page. The
-two libvirt actions are named <code>org.libvirt.unix.manage</code> for full
-management access, and <code>org.libvirt.unix.monitor</code> for read-only
-access.
-</p>
- <p>
-As an example, creating
<code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code>
-with the following gives the user <code>fred</code> full management access
-when accessing from an active local session:
- </p>
-<pre>polkit.addRule(function(action, subject) {
- if (action.id == "org.libvirt.unix.manage" &&
- subject.local && subject.active && subject.user ==
"fred") {
- return polkit.Result.YES;
- }
-});</pre>
- <p>
-Older versions of PolicyKit used policy files ending with .pkla in the
-local override directory
<code>/etc/polkit-1/localauthority/50-local.d/</code>.
-Compatibility with this older format is provided by <a
-href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>.
As an
-example, this gives the user <code>fred</code> full management access:
- </p>
-<pre>[Allow fred libvirt management permissions]
-Identity=unix-user:fred
-Action=org.libvirt.unix.manage
-ResultAny=yes
-ResultInactive=yes
-ResultActive=yes</pre>
- <h2><a id="ACL_server_sasl">SASL pluggable
authentication</a></h2>
-
- <p>
-Libvirt integrates with the cyrus-sasl library to provide a pluggable authentication
-system using the SASL protocol. SASL can be used in combination with libvirtd's TLS
-or TCP socket listeners. When used with the TCP listener, the SASL mechanism is
-rqeuired 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:
- </p>
-
- <dl>
- <dt>GSSAPI</dt>
- <dd><strong>This is the current default mechanism to use with
libvirtd</strong>.
- 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.</dd>
-
- <dt>DIGEST-MD5</dt>
- <dd>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.
- <a href="https://tools.ietf.org/html/rfc6331">RFC
6331</a>, however,
- documents a number of serious security flaws with DIGEST-MD5 and as a
- result marks it as <code>OBSOLETE</code>. 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.
- </dd>
-
- <dt>PASSDSS-3DES-1</dt>
- <dd>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.</dd>
-
- <dt>KERBEROS_V4</dt>
- <dd>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.</dd>
- </dl>
-
- <p>
- Other SASL mechanisms, not listed above, can only be used when the libvirtd
- TLS or UNIX socket listeners.
- </p>
-
- <h3><a id="ACL_server_username">Username/password
auth</a></h3>
- <p>
-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 <code>auth_unix_ro</code>,
<code>auth_unix_rw</code>,
-<code>auth_tls</code> config params in <code>libvirt.conf</code>
can be used
-to turn on SASL auth in these listeners.
- </p>
- <p>
-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 <code>/etc/sasl2/libvirt.conf</code> to set the
<code>mech_list</code>
-parameter to <code>scram-sha-1</code>.
- </p>
- <p>
-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 done with the
<code>saslpasswd2</code>
-command. When running this command it is important to tell it that the appname is
<code>libvirt</code>.
-As an example, to add a user <code>fred</code>, run
-</p>
- <pre>
-# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-</pre>
- <p>
-To see a list of all accounts the <code>sasldblistusers2</code> command can
be used.
-This command expects to be given the path to the libvirt user database, which is kept
-in <code>/etc/libvirt/passwd.db</code>
-</p>
- <pre>
-# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred(a)t60wlan.home.berrange.com: userPassword
-</pre>
- <p>
-Finally, to disable a user's access, the <code>saslpasswd2</code>
command can be used
-again:
-</p>
- <pre>
-# saslpasswd2 -a libvirt -d fred
-</pre>
- <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos
auth</a></h3>
- <p>
-The plain TCP listener of the libvirt daemon defaults to using SASL for authentication.
-The libvirt SASL config also defaults to GSSAPI, so there is no need to edit the
-SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are used,
-then the Kerberos session encryption will be disabled since it is not required
-in these scenarios - only the plain TCP listener needs encryption
-</p>
- <p>
-Some operating systems do not install the SASL kerberos plugin by default. It
-may be necessary to install a sub-package such as
<code>cyrus-sasl-gssapi</code>.
-To check whether the Kerberos plugin is installed run the
<code>pluginviewer</code>
-program and verify that <code>gssapi</code> is listed, e.g.:
-</p>
- <pre>
-# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded], API version: 4
- SASL mechanism: GSSAPI, best SSF: 56
- security flags:
NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
- features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-</pre>
- <p>
-Next it is necessary for the administrator of the Kerberos realm to
-issue a principal for the libvirt server. There needs to be one
-principal per host running the libvirt daemon. The principal should be
-named <code>libvirt/full.hostname(a)KERBEROS.REALM</code>. This is
-typically done by running the <code>kadmin.local</code> command on the
-Kerberos server, though some Kerberos servers have alternate ways of
-setting up service principals. Once created, the principal should be
-exported to a keytab, copied to the host running the libvirt daemon
-and placed in <code>/etc/libvirt/krb5.tab</code>
-</p>
- <pre>
-# kadmin.local
-kadmin.local: add_principal libvirt/foo.example.com
-Enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
-Principal "libvirt/foo.example.com(a)EXAMPLE.COM" created.
-
-kadmin.local: ktadd -k /root/libvirt-foo-example.tab
libvirt/foo.example.com(a)EXAMPLE.COM
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type
ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type DES
with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, encryption type DES
cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-
-kadmin.local: quit
-
-# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
-# rm /root/libvirt-foo-example.tab
-</pre>
- <p>
-Any client application wishing to connect to a Kerberos enabled libvirt server
-merely needs to run <code>kinit</code> to gain a user principal. This may
well
-be done automatically when a user logs into a desktop session, if PAM is set up
-to authenticate against Kerberos.
-</p>
- </body>
-</html>
diff --git a/docs/auth.rst b/docs/auth.rst
new file mode 100644
index 0000000000..506e6b5c13
--- /dev/null
+++ b/docs/auth.rst
@@ -0,0 +1,350 @@
+=========================
+Connection authentication
+=========================
+
+.. contents::
+
+When connecting to libvirt, some connections may require client
+authentication before allowing use of the APIs. The set of possible
+authentication mechanisms is administrator controlled, independent
+of applications using libvirt. Once authenticated, libvirt can apply
+fine grained `access control <acl.html>`_ to the operations
+performed by a client.
+
+Client configuration
+====================
+
+When connecting to a remote hypervisor which requires authentication,
+most libvirt applications will prompt the user for the credentials. It is
+also possible to provide a client configuration file containing all the
+authentication credentials, avoiding any interaction. Libvirt will look
+for the authentication file using the following sequence:
+
+* The file path specified by the ``$LIBVIRT_AUTH_FILE`` environment
+ variable.
+* The file path specified by the ``authfile=/some/file`` URI
+ query parameter
+* The file ``$XDG_CONFIG_HOME/libvirt/auth.conf``
+* The file ``/etc/libvirt/auth.conf``
+
+The auth configuration file uses the traditional ``.ini``
+style syntax. There are two types of groups that can be present in
+the config. First there are one or more ``credential``
+sets, which provide the actual authentication credentials. The keys
+within the group may be:
+
+* ``username``: the user login name to act as. This
+ is relevant for ESX, Xen, HyperV and SSH, but probably not
+ the one you want to libvirtd with SASL.
s/want to/want for
...
+For example, to define two sets of credentials used for production
+and test machines, using libvirtd, and a further ESX server for dev:
s/dev/development/
...
+ polkit.addRule(function(action, subject) {
+ if (action.id == "org.libvirt.unix.manage" &&
+ subject.local && subject.active &&; subject.user ==
"fred") {
s/amp;//g
s/; subject/ subject/
...
+
+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
s/libvirt.conf/libvirtd.conf/
All of the nits are pre-existing...please fix them in a trivial patch before
pushing.
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 p.m.
New subject: [libvirt PATCH 2/2] docs: stop mentioning insecure / broken SASL mechanisms
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(a)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
2:08 p.m.
New subject: [libvirt PATCH 2/2] docs: stop mentioning insecure / broken SASL mechanisms
...
+**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.
Can we make ^hits all bold to make it more visible?
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
8:02 a.m.
On Thu, Mar 04, 2021 at 06:10:11PM +0000, Daniel P. Berrangé wrote:
GSSAPI and SCRAM-SHA-256 are the only two SASL mechanisms we
especially want people to be using. Even the latter is a little
questionable due to storing passwords in cleartext on the server.
At what point of the SCRAM-SHA-256 auth process is password handled as clear
text? I mean I tried to look up the issue you mention and couldn't find
anything, quite the contrary, e.g. Postgres says SCRAM-SHA-256 is the only
recommended scheme for password-based auth and storing passwords in clear text
is not possible. Isn't it kind of the point that passwords are never stored in
clear text with this scheme?
https://www.postgresql.org/docs/13/auth-password.html
Erik
11:41 a.m.
On Fri, Mar 05, 2021 at 08:02:49AM +0100, Erik Skultety wrote:
On Thu, Mar 04, 2021 at 06:10:11PM +0000, Daniel P. Berrangé wrote:
> GSSAPI and SCRAM-SHA-256 are the only two SASL mechanisms we
> especially want people to be using. Even the latter is a little
> questionable due to storing passwords in cleartext on the server.
At what point of the SCRAM-SHA-256 auth process is password handled as clear
text? I mean I tried to look up the issue you mention and couldn't find
anything, quite the contrary, e.g. Postgres says SCRAM-SHA-256 is the only
recommended scheme for password-based auth and storing passwords in clear text
is not possible. Isn't it kind of the point that passwords are never stored in
clear text with this scheme?
You can clearly see the passwd in clear text in the file
Add a new user
$ echo "fish food" | saslpasswd2 -a libvirt demo
Look for the password:
$ strings /etc/libvirt/passwd.db | grep fish
fish food
The actual mechanism protocol does send in clear text over the wire.
The storage in clear text on the server side is simply a choice of the
cyrus-sasl impl of this mechanism documented here:
https://www.cyrusimap.org/sasl/sasl/faqs/plaintextpasswords.html
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 :|
noon
On Mon, Mar 08, 2021 at 10:41:55AM +0000, Daniel P. Berrangé wrote:
On Fri, Mar 05, 2021 at 08:02:49AM +0100, Erik Skultety wrote:
> On Thu, Mar 04, 2021 at 06:10:11PM +0000, Daniel P. Berrangé wrote:
> > GSSAPI and SCRAM-SHA-256 are the only two SASL mechanisms we
> > especially want people to be using. Even the latter is a little
> > questionable due to storing passwords in cleartext on the server.
>
> At what point of the SCRAM-SHA-256 auth process is password handled as clear
> text? I mean I tried to look up the issue you mention and couldn't find
> anything, quite the contrary, e.g. Postgres says SCRAM-SHA-256 is the only
> recommended scheme for password-based auth and storing passwords in clear text
> is not possible. Isn't it kind of the point that passwords are never stored in
> clear text with this scheme?
You can clearly see the passwd in clear text in the file
Add a new user
$ echo "fish food" | saslpasswd2 -a libvirt demo
Look for the password:
$ strings /etc/libvirt/passwd.db | grep fish
fish food
The actual mechanism protocol does send in clear text over the wire.
The storage in clear text on the server side is simply a choice of the
cyrus-sasl impl of this mechanism documented here:
https://www.cyrusimap.org/sasl/sasl/faqs/plaintextpasswords.html
So if this is the case, why are we even bothering promoting an insecure
solution, why not promote only GSSAPI for the reasons given? Backcompat?
Erik
12:06 p.m.
On Mon, Mar 08, 2021 at 12:00:03PM +0100, Erik Skultety wrote:
On Mon, Mar 08, 2021 at 10:41:55AM +0000, Daniel P. Berrangé wrote:
> On Fri, Mar 05, 2021 at 08:02:49AM +0100, Erik Skultety wrote:
> > On Thu, Mar 04, 2021 at 06:10:11PM +0000, Daniel P. Berrangé wrote:
> > > GSSAPI and SCRAM-SHA-256 are the only two SASL mechanisms we
> > > especially want people to be using. Even the latter is a little
> > > questionable due to storing passwords in cleartext on the server.
> >
> > At what point of the SCRAM-SHA-256 auth process is password handled as clear
> > text? I mean I tried to look up the issue you mention and couldn't find
> > anything, quite the contrary, e.g. Postgres says SCRAM-SHA-256 is the only
> > recommended scheme for password-based auth and storing passwords in clear text
> > is not possible. Isn't it kind of the point that passwords are never stored
in
> > clear text with this scheme?
>
> You can clearly see the passwd in clear text in the file
>
> Add a new user
>
> $ echo "fish food" | saslpasswd2 -a libvirt demo
>
> Look for the password:
>
> $ strings /etc/libvirt/passwd.db | grep fish
> fish food
>
> The actual mechanism protocol does send in clear text over the wire.
> The storage in clear text on the server side is simply a choice of the
> cyrus-sasl impl of this mechanism documented here:
>
> https://www.cyrusimap.org/sasl/sasl/faqs/plaintextpasswords.html
So if this is the case, why are we even bothering promoting an insecure
solution, why not promote only GSSAPI for the reasons given? Backcompat?
Calling it insecure is a rather absolutist view of security IMHO.
It *is* secure against network attackers, which is the primary risk
factor we're protecting against with our use of SASL.
To compromise the passwords requires the attacker to first compromise
the root account on the virt host. Anything is possible, but IMHO that
danger doesn't justify eliminating the SCRAM auth mechanism.
If we only promote GSSAPI, then the result is likely to be that people
run with no authentication at all, or make their own ill informed worse
choices.
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 :|
1291
days inactive
1295
days old
8 comments
2 participants
participants (2)
-
Daniel P. Berrangé -
Erik Skultety