Using Cyrus SASL Authentication with Subversion =============================================== Contents ======== 1. Obtaining and Building the Cyrus SASL Library 2. Building Subversion with Cyrus SASL Support 3. Theory 4. Configuration 5. Compatibility 6. Encryption 7. Known Issues 8. GSSAPI 1. Obtaining and Building the Cyrus SASL Library ================================================ Subversion 1.5 introduces support for the Cyrus SASL (Simple Authentication and Security Layer) library for the svn:// protocol and svnserve server. Only version 2.1.x is supported. You can get the latest version of the library from: ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/ To build Cyrus SASL on Unix-like systems, follow the usual ./configure && make && make install process. Cyrus SASL has many ./configure options to control which authentication mechanisms and password-checking methods should be built. On Windows, follow the instructions in the doc/windows.html file in the Cyrus SASL sources. 2. Building Subversion with Cyrus SASL Support ============================================== On Unix, if you have Cyrus SASL installed in one of the standard locations (/usr or /usr/local), the configure script should automatically detect it. If the library is installed elsewhere you can use the --with-sasl=PATH switch to the configure script. On Windows, once you have built the library, pass --with-sasl=PATH to the gen-make.py script, where PATH is the directory where Cyrus SASL was built. 3. Theory ========= From Wikipedia: "SASL is a framework for authentication and data security in Internet protocols. It decouples authentication mechanisms from application protocols, in theory allowing any authentication mechanism supported by SASL to be used in any application protocol that uses SASL." In practice, the server sends a list of authentication mechanisms that it supports. The client then selects one of these mechanisms based on what the client supports, and informs the server of its decision. After that, a number of messages are exchanged until either authentication succeeds or an error occurs. In the latter case, the client is allowed to restart authentication. The svn:// protocol has always supported this type of negotiation. However, only the CRAM-MD5 and ANONYMOUS mechanisms were implemented. Cyrus SASL supports all these, and, in addition, provides a host of other mechanisms such as DIGEST-MD5, OTP (One-Time Passwords), GSSAPI (used for Kerberos authentication), NTLM (NT LAN Manager), SRP (Secure Remote Password), and others. The exact list of available mechanisms depends on how SASL was compiled, as many of them either have external dependencies, or are not built by default. Also, because each mechanism is actually a shared library that is dynamically loaded at runtime, many distributions package these mechanisms separately from the core library. 4. Configuration ================ On the client side, you don't have to do anything special to enable Cyrus SASL, it will always be used if you built Subversion with SASL support. On the server side, Cyrus SASL will not be used by default because some extra configuration steps are required. First, you need to configure how the Cyrus SASL library should authenticate a client's username and password. These options are not stored in svnserve.conf, but in a special configuration file read by Cyrus SASL. This file must be named svn.conf, and must be readable by the svnserve process. Cyrus SASL will look for this file in a known location, usually the same directory where its plugins are located, i.e. /usr/lib/sasl2. Some SASL distributions will look for the file in a different directory, e.g. /etc/sasl2. The list of possible options can be found in the doc/options.html file in the Cyrus SASL sources. A simple svn.conf might look like this: pwcheck_method: auxprop auxprop_plugin: sasldb mech_list: ANONYMOUS DIGEST-MD5 This tells SASL to use its own password database (usually stored in /etc/sasldb2) to check user passwords, and restricts the list of authentication mechanisms to just ANONYMOUS and DIGEST-MD5. To add usernames and passwords to Cyrus SASL's database, use the saslpasswd2 command, like this: saslpasswd2 -c -u realm username For this to work, you need to be root (or a member of the "sasl" group). Check that you have created the user correctly with sasldblistusers2. IMPORTANT: The "realm" argument to the saslpasswd2 command must be the same realm that you specify in the svnserve.conf file. svnserve will tell SASL to use that realm when authenticating, and if they do not match, authentication will fail. You should avoid realms with spaces in them, because SASL doesn't like them. IMPORTANT: If you are using sasldb, svnserve must have read access to the /etc/sasldb2 file. If you are going to use the OTP mechanism, you also need write access. There are many other ways to configure SASL. Instead of storing passwords in a local database, you can use Kerberos, LDAP, you can store passwords in a SQL database, etc. Read the SASL documentation for details. After creating the svn.conf file, you need to tell svnserve to start using Cyrus SASL for authentication. To do this, just set "use-sasl" to "true" in the [sasl] section of the svnserve.conf file. You should now be able to authenticate. On Windows, some additional steps are required. To tell SASL where to find its plugins and configuration files, you need to create the following registry key (using a registry editing tool such as regedit): [HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library] and add two keys to it: "SearchPath": set this to the path where SASL's plugins (the *.dll files) are located "ConfFile": set this to the path where Cyrus SASL should look for the svn.conf file 5. Compatibility ================ All 1.x clients, with or without Cyrus SASL support, will be able to authenticate against all 1.x servers that do not have Cyrus SASL enabled. Note that the CRAM-MD5 and ANONYMOUS mechanisms are actually built into Subversion, so you'll be able to use them even if the corresponding Cyrus SASL plugins are missing. 1.x clients without Cyrus SASL support will be able to authenticate against 1.5+ servers with SASL enabled, provided the server allows the CRAM-MD5 and/or ANONYMOUS mechanisms. 1.5+ clients with Cyrus SASL support will be able to authenticate against 1.5+ servers with SASL enabled, provided at least one of the mechanisms supported by the server is also supported by the client. 6. Encryption ============= In addition to providing authentication, the Cyrus SASL library can also provide data confidentiality (a.k.a. encryption). Not all SASL mechanisms support encryption (e.g. DIGEST-MD5 does, CRAM-MD5 doesn't). To control the level of encryption, you can use two additional svnserve.conf options, min-encryption and max-encryption. A value of 0 for either of these means "no encryption", 1 means "protect data integrity, but not confidentiality", and values greater than 1 correspond to the desired encryption key length, in bits. For example: min-encryption max-encryption result -------------- -------------- --------------------------------- 0 0 encryption is disabled 1 1 data will be protected against tampering, but will not be encrypted 0 256 allow encryption for those clients that support it, but don't require it 128 256 require at least 128-bit encryption 7. Known Issues =============== Cyrus SASL has two authentication mechanisms, PLAIN and LOGIN, that send the password over the network in plain text. The svn:// protocol doesn't support TLS yet, so both these mechanisms expose passwords to the network in clear text. As a consequence, users should take great care to secure the network link by other means, such as by deploying a secure VPN or by using stunnel for SSL encryption (http://stunnel.mirt.net/) In particular, this problem affects users using the saslauthd daemon to authenticate users, because that method only works with plain text passwords. 8. GSSAPI ========= The realm in svnserve.conf is your Kerberos authentation realm, e.g. "EXAMPLE.COM". Cyrus's GSSAPI implementation does not support encryption, except for very basic 56-bit DES. If you leave the encrypt settings out of your svnserve.conf entirely, you're fine; just don't set max-encryption higher than 56. You need a Kerberos principal for each svn server, in the form "svn/${SERVER_FQDN}@${REALM}", e.g. "svn/svn1.example.com@EXAMPLE.COM". If you don't store it in /etc/krb5.keytab, you'll need to set the KRB5_KTNAME environment variable when starting svnserve, e.g. KRB5_KTNAME=/etc/svn.keytab sudo -u svn svnserve -d -r /svn This keytab file must also be readable by the svnserve process. All you need in the svn.conf file is: mech_list: gssapi