notes/sasl.txt

   1               Using Cyrus SASL Authentication with Subversion
   2               ===============================================
   3
   4
   5 Contents
   6 ========
   7
   8   1. Obtaining and Building the Cyrus SASL Library
   9   2. Building Subversion with Cyrus SASL Support
  10   3. Theory
  11   4. Configuration
  12   5. Compatibility
  13   6. Encryption
  14   7. Known Issues
  15   8. GSSAPI
  16
  17
  18 1. Obtaining and Building the Cyrus SASL Library
  19 ================================================
  20
  21   Subversion 1.5 introduces support for the Cyrus SASL (Simple Authentication
  22   and Security Layer) library for the svn:// protocol and svnserve server.
  23
  24   Only version 2.1.x is supported.  You can get the latest version of the
  25   library from:
  26
  27     ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/
  28
  29   To build Cyrus SASL on Unix-like systems, follow the usual ./configure
  30   && make && make install process.  Cyrus SASL has many ./configure options
  31   to control which authentication mechanisms and password-checking methods
  32   should be built.  On Windows, follow the instructions in the
  33   doc/windows.html file in the Cyrus SASL sources.
  34
  35
  36 2. Building Subversion with Cyrus SASL Support
  37 ==============================================
  38
  39   On Unix, if you have Cyrus SASL installed in one of the standard locations
  40   (/usr or /usr/local), the configure script should automatically detect it.
  41   If the library is installed elsewhere you can use the --with-sasl=PATH
  42   switch to the configure script.
  43
  44   On Windows, once you have built the library, pass --with-sasl=PATH to the
  45   gen-make.py script, where PATH is the directory where Cyrus SASL was built.
  46
  47
  48 3. Theory
  49 =========
  50
  51   From Wikipedia: "SASL is a framework for authentication and data security in
  52   Internet protocols.  It decouples authentication mechanisms from application
  53   protocols, in theory allowing any authentication mechanism supported by SASL
  54   to be used in any application protocol that uses SASL."
  55
  56   In practice, the server sends a list of authentication mechanisms that it
  57   supports.  The client then selects one of these mechanisms based on what the
  58   client supports, and informs the server of its decision.  After that, a
  59   number of messages are exchanged until either authentication succeeds or an
  60   error occurs.  In the latter case, the client is allowed to restart
  61   authentication.
  62
  63   The svn:// protocol has always supported this type of negotiation.  However,
  64   only the CRAM-MD5 and ANONYMOUS mechanisms were implemented.  Cyrus SASL
  65   supports all these, and, in addition, provides a host of other mechanisms
  66   such as DIGEST-MD5, OTP (One-Time Passwords), GSSAPI (used for Kerberos
  67   authentication), NTLM (NT LAN Manager), SRP (Secure Remote Password), and
  68   others.  The exact list of available mechanisms depends on how SASL was
  69   compiled, as many of them either have external dependencies, or are not
  70   built by default.  Also, because each mechanism is actually a shared library
  71   that is dynamically loaded at runtime, many distributions package these
  72   mechanisms separately from the core library.
  73
  74
  75 4. Configuration
  76 ================
  77
  78   On the client side, you don't have to do anything special to enable Cyrus
  79   SASL, it will always be used if you built Subversion with SASL support.  On
  80   the server side, Cyrus SASL will not be used by default because some extra
  81   configuration steps are required.
  82
  83   First, you need to configure how the Cyrus SASL library should authenticate
  84   a client's username and password.  These options are not stored in
  85   svnserve.conf, but in a special configuration file read by Cyrus SASL.  This
  86   file must be named svn.conf, and must be readable by the svnserve process.
  87   Cyrus SASL will look for this file in a known location, usually the same
  88   directory where its plugins are located, i.e. /usr/lib/sasl2.  Some SASL
  89   distributions will look for the file in a different directory, e.g.
  90   /etc/sasl2.
  91
  92   The list of possible options can be found in the doc/options.html file in the
  93   Cyrus SASL sources.  A simple svn.conf might look like this:
  94
  95     pwcheck_method: auxprop
  96     auxprop_plugin: sasldb
  97     mech_list: ANONYMOUS DIGEST-MD5
  98
  99   This tells SASL to use its own password database (usually stored in
 100   /etc/sasldb2) to check user passwords, and restricts the list of
 101   authentication mechanisms to just ANONYMOUS and DIGEST-MD5.
 102
 103   To add usernames and passwords to Cyrus SASL's database, use the saslpasswd2
 104   command, like this:
 105
 106     saslpasswd2 -c -u realm username
 107
 108   For this to work, you need to be root (or a member of the "sasl" group).
 109   Check that you have created the user correctly with sasldblistusers2.
 110
 111   IMPORTANT: The "realm" argument to the saslpasswd2 command must be the same
 112   realm that you specify in the svnserve.conf file.  svnserve will tell SASL
 113   to use that realm when authenticating, and if they do not match,
 114   authentication will fail.  You should avoid realms with spaces in them,
 115   because SASL doesn't like them.
 116
 117   IMPORTANT: If you are using sasldb, svnserve must have read access to the
 118   /etc/sasldb2 file.  If you are going to use the OTP mechanism, you also need
 119   write access.
 120
 121   There are many other ways to configure SASL.  Instead of storing passwords
 122   in a local database, you can use Kerberos, LDAP, you can store passwords in
 123   a SQL database, etc.  Read the SASL documentation for details.
 124
 125   After creating the svn.conf file, you need to tell svnserve to start
 126   using Cyrus SASL for authentication.  To do this, just set "use-sasl" to
 127   "true" in the [sasl] section of the svnserve.conf file.  You should now be
 128   able to authenticate.
 129
 130   On Windows, some additional steps are required.  To tell SASL where to find
 131   its plugins and configuration files, you need to create the following
 132   registry key (using a registry editing tool such as regedit):
 133
 134     [HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library]
 135
 136   and add two keys to it:
 137
 138     "SearchPath": set this to the path where SASL's plugins (the *.dll files)
 139                   are located
 140     "ConfFile":   set this to the path where Cyrus SASL should look for the
 141                   svn.conf file
 142
 143 5. Compatibility
 144 ================
 145
 146   All 1.x clients, with or without Cyrus SASL support, will be able to
 147   authenticate against all 1.x servers that do not have Cyrus SASL enabled.
 148   Note that the CRAM-MD5 and ANONYMOUS mechanisms are actually built into
 149   Subversion, so you'll be able to use them even if the corresponding Cyrus
 150   SASL plugins are missing.
 151
 152   1.x clients without Cyrus SASL support will be able to authenticate against
 153   1.5+ servers with SASL enabled, provided the server allows the CRAM-MD5
 154   and/or ANONYMOUS mechanisms.
 155
 156   1.5+ clients with Cyrus SASL support will be able to authenticate against
 157   1.5+ servers with SASL enabled, provided at least one of the mechanisms
 158   supported by the server is also supported by the client.
 159
 160
 161 6. Encryption
 162 =============
 163
 164   In addition to providing authentication, the Cyrus SASL library can also
 165   provide data confidentiality (a.k.a. encryption).  Not all SASL mechanisms
 166   support encryption (e.g. DIGEST-MD5 does, CRAM-MD5 doesn't).  To control the
 167   level of encryption, you can use two additional svnserve.conf options,
 168   min-encryption and max-encryption.  A value of 0 for either of these means
 169   "no encryption", 1 means "protect data integrity, but not confidentiality",
 170   and values greater than 1 correspond to the desired encryption key length,
 171   in bits.
 172
 173   For example:
 174
 175     min-encryption    max-encryption                   result
 176     --------------    --------------      ---------------------------------
 177           0                 0             encryption is disabled
 178
 179           1                 1             data will be protected against
 180                                           tampering, but will not be encrypted
 181
 182           0                256            allow encryption for those clients
 183                                           that support it, but don't require
 184                                           it
 185
 186          128               256            require at least 128-bit encryption
 187
 188
 189 7. Known Issues
 190 ===============
 191
 192   Cyrus SASL has two authentication mechanisms, PLAIN and LOGIN, that send the
 193   password over the network in plain text.  This would be fine if the
 194   transmission medium was already encrypted with TLS (Transport Layer
 195   Security).  However, the svn:// protocol doesn't support TLS yet, so both
 196   these mechanisms are currently disabled in both the client and the server.
 197
 198   As a consequence, you won't be able to use the saslauthd daemon to
 199   authenticate users, because that method only works with plain text passwords.
 200
 201 8. GSSAPI
 202 =========
 203
 204   The realm in svnserve.conf is your Kerberos authentation realm,
 205   e.g. "EXAMPLE.COM".  Cyrus's GSSAPI implementation does not support
 206   encryption, except for very basic 56-bit DES.  If you leave the encrypt
 207   settings out of your svnserve.conf entirely, you're fine; just don't set
 208   max-encryption higher than 56.
 209
 210   You need a Kerberos principal for each svn server, in the form
 211   "svn/${SERVER_FQDN}@${REALM}", e.g. "svn/svn1.example.com@EXAMPLE>COM".
 212   If you don't store it in /etc/krb5.keytab, you'll need to set the
 213   KRB5_KTNAME environment variable when starting svnserve, e.g.
 214
 215     KRB5_KTNAME=/etc/svn.keytab sudo -u svn svnserve -d -r /svn
 216
 217   This keytab file must also be readable by the svnserve process.
 218
 219   All you need in the svn.conf file is:
 220
 221     mech_list: gssapi