mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 17:34:18 +03:00
b1c81567c7
The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
359 lines
15 KiB
XML
359 lines
15 KiB
XML
<?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>
|
|
|
|
<ol>
|
|
<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 Phyp server
|
|
over SSH</li>
|
|
<li><code>esx</code> - used for connections to an ESX or
|
|
VirtualCenter server</li>
|
|
<li><code>xen</code> - used for connections to a Xen Enterprise
|
|
sever using XenAPI</li>
|
|
</ol>
|
|
|
|
<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
|
|
local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
|
|
Policy files should have a unique name ending with .pkla. Using reverse DNS
|
|
naming works well. Information on the options available can be found by
|
|
reading the pklocalauthority man page. The two libvirt daemon actions
|
|
available 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, 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>
|
|
<p>
|
|
Further examples of PolicyKit setup can be found on the
|
|
<a href="http://wiki.libvirt.org/page/SSHPolicyKitSetup">wiki page</a>.
|
|
</p>
|
|
<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 rquired to enable plain password auth. This is done by
|
|
editting <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@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,eg:
|
|
</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@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@EXAMPLE.COM":
|
|
Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
|
|
Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
|
|
|
|
kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM
|
|
Entry for principal libvirt/foo.example.com@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@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@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@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 setup
|
|
to authenticate against Kerberos.
|
|
</p>
|
|
</body>
|
|
</html>
|