From eskultet at redhat.com Mon Mar 8 08:06:25 2021 Content-Type: multipart/mixed; boundary="===============2851461657635045457==" MIME-Version: 1.0 From: Erik Skultety To: devel at lists.libvirt.org Subject: Re: [libvirt PATCH 1/2] docs: convert auth page into RST format Date: Mon, 08 Mar 2021 14:06:18 +0100 Message-ID: In-Reply-To: 20210304181013.10329-2-berrange@redhat.com --===============2851461657635045457== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, Mar 04, 2021 at 06:10:12PM +0000, Daniel P. Berrang=C3=A9 wrote: > Signed-off-by: Daniel P. Berrang=C3=A9 > --- > 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 @@ > - > - > - > - > -

Connection authentication

> -

> - 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 app= ly > - fine grained access control to the operat= ions > - performed by a client. > -

> - > -

Client configuration

> - > -

> - When connecting to a remote hypervisor which requires authenticati= on, > -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=3D/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=3Dvalue1
> -credname2=3Dvalue2
> -
> -    
> -      For example, to define two sets of credentials used for production
> -      and test machines, using libvirtd, and a further ESX server for de=
v:
> -    
> -> -[credentials-test]
> -authname=3Dfred
> -password=3D123456
> -
> -[credentials-prod]
> -authname=3Dbar
> -password=3Dletmein
> -
> -[credentials-dev]
> -username=3Djoe
> -password=3Dhello
> -
> -[credentials-defgrp]
> -username=3Ddefuser
> -password=3Ddefpw
> -
> -    
> -      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=3D$CREDENTIALS
> -
> -    
> -      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=3Dtest
> -
> -[auth-libvirt-test2.example.com]
> -credentials=3Dtest
> -
> -[auth-libvirt-demo3.example.com]
> -credentials=3Dtest
> -
> -[auth-libvirt-prod1.example.com]
> -credentials=3Dprod
> -
> -[auth-libvirt-default]
> -credentials=3Ddefgrp
> -
> -[auth-esx-dev1.example.com]
> -credentials=3Ddev
> -
> -[auth-esx-default]
> -credentials=3Ddefgrp
> -
> -
> -    
> -      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 independen=
tly.
> -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 f=
or
> -the UNIX domain socket is done using traditional file user/group ownersh=
ip
> -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 w=
ill
> -be open access (mode 0777) to allow any user to connect.
> -
> -    
> -To allow non-root users greater access, the libvirtd.conf f=
ile
> -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 a=
re
> -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 applica=
tion
> -will be required to identify itself with PolicyKit. The default policy f=
or the
> -RW daemon socket will require any application running in the current des=
ktop
> -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 soc=
ket.
> -
> -    
> -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. T=
he
> -two libvirt actions are named org.libvirt.unix.manage for f=
ull
> -management access, and org.libvirt.unix.monitor for read-on=
ly
> -access.
> -
> -    
> -As an example, creating /etc/polkit-1/rules.d/80-libvirt-manage.ru=
les
> -with the following gives the user fred full management acce=
ss
> -when accessing from an active local session:
> -    
> -polkit.addRule(function(action, subject) {
> -  if (action.id =3D=3D "org.libvirt.unix.manage" &&
> -      subject.local && subject.active && subject.user =
=3D=3D "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/<=
/code>.
> -Compatibility with this older format is provided by  -href=3D"https://pagure.io/polkit-pkla-compat">polkit-pkla-compat. As=
 an
> -example, this gives the user fred full management access:
> -    

> -[Allow fred libvirt management permissions]
> -Identity=3Dunix-user:fred
> -Action=3Dorg.libvirt.unix.manage
> -ResultAny=3Dyes
> -ResultInactive=3Dyes
> -ResultActive=3Dyes
> -    SASL pluggable authentication
> -
> -    
> -Libvirt integrates with the cyrus-sasl library to provide a pluggable au=
thentication
> -system using the SASL protocol. SASL can be used in combination with lib=
virtd's TLS
> -or TCP socket listeners. When used with the TCP listener, the SASL mecha=
nism is
> -rqeuired to provide session encryption in addition to authentication. On=
ly a very
> -few SASL mechanisms are able to do this, and of those that can do it, on=
ly the
> -GSSAPI plugin is considered acceptably secure by modern standards:
> -    
> -
> -    
> -      GSSAPI
> -      This is the current default mechanism to use with libv=
irtd.
> -        It uses the Kerberos v5 authentication protocol underneath, and =
assuming
> -        the Kerberos client/server are configured with modern ciphers (A=
ES),
> -        it provides strong session encryption capabilities.
> -
> -      DIGEST-MD5
> -      This was previously set as the default mechanism to use with l=
ibvirtd.
> -        It provides a simple username/password based authentication mech=
anism
> -        that includes session encryption.
> -        RFC 6331, ho=
wever,
> -        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-f=
orced
> -        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-sa=
sl
> -        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 au=
thentication
> -        and session encryption. Kerberos v4 protocol has been obsolete s=
ince 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 shou=
ld
> -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<=
/code>
> -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 a=
ppname 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 comman=
d 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 re=
quired
> -in these scenarios - only the plain TCP listener needs encryption
> -
> -    
> -Some operating systems do not install the SASL kerberos plugin by defaul=
t. It
> -may be necessary to install a sub-package such as cyrus-sasl-gssap=
i.
> -To check whether the Kerberos plugin is installed run the pluginvi=
ewer
> -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_CREDENT=
IALS|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.exampl=
e.com(a)EXAMPLE.COM
> -Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, e=
ncryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/r=
oot/libvirt-foo-example.tab.
> -Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, e=
ncryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-f=
oo-example.tab.
> -Entry for principal libvirt/foo.example.com(a)EXAMPLE.COM with kvno 4, e=
ncryption 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, e=
ncryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvi=
rt-foo-example.tab.
> -
> -kadmin.local: quit
> -
> -# scp /root/libvirt-foo-example.tab root(a)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 ma=
y 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/auth.rst b/docs/auth.rst
> new file mode 100644
> index 0000000000..506e6b5c13
> --- /dev/null
> +++ b/docs/auth.rst
> @@ -0,0 +1,350 @@
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D
> +Connection authentication
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D
> +
> +.. 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 `_ to the operations
> +performed by a client.
> +
> +Client configuration
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +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=3D/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 =3D=3D "org.libvirt.unix.manage" &&
> +         subject.local && subject.active &&; subject.user =3D=3D=
 "fred") {

s/amp;//g
s/; subject/ subject/


...
> +
> +As noted above, the DIGEST-MD5 mechanism is considered obsolete and shou=
ld
> +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 


--===============2851461657635045457==--