              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