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