1
Using Cyrus SASL Authentication with Subversion
2
===============================================
8
1. Obtaining and Building the Cyrus SASL Library
9
2. Building Subversion with Cyrus SASL Support
18
1. Obtaining and Building the Cyrus SASL Library
19
================================================
21
Subversion 1.5 introduces support for the Cyrus SASL (Simple Authentication
22
and Security Layer) library for the svn:// protocol and svnserve server.
24
Only version 2.1.x is supported. You can get the latest version of the
27
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/
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.
36
2. Building Subversion with Cyrus SASL Support
37
==============================================
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.
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.
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."
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
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.
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.
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.
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:
95
pwcheck_method: auxprop
96
auxprop_plugin: sasldb
97
mech_list: ANONYMOUS DIGEST-MD5
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.
103
To add usernames and passwords to Cyrus SASL's database, use the saslpasswd2
106
saslpasswd2 -c -u realm username
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.
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.
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
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.
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.
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):
134
[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library]
136
and add two keys to it:
138
"SearchPath": set this to the path where SASL's plugins (the *.dll files)
140
"ConfFile": set this to the path where Cyrus SASL should look for the
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.
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.
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.
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,
175
min-encryption max-encryption result
176
-------------- -------------- ---------------------------------
177
0 0 encryption is disabled
179
1 1 data will be protected against
180
tampering, but will not be encrypted
182
0 256 allow encryption for those clients
183
that support it, but don't require
186
128 256 require at least 128-bit encryption
192
Cyrus SASL has two authentication mechanisms, PLAIN and LOGIN, that send the
193
password over the network in plain text. The svn:// protocol doesn't support
194
TLS yet, so both these mechanisms expose passwords to the network in clear
197
As a consequence, users should take great care to secure the network link
198
by other means, such as by deploying a secure VPN or by using stunnel for
199
SSL encryption (http://stunnel.mirt.net/)
201
In particular, this problem affects users using the saslauthd daemon
202
to authenticate users, because that method only works with plain text
208
The realm in svnserve.conf is your Kerberos authentation realm,
209
e.g. "EXAMPLE.COM". Cyrus's GSSAPI implementation does not support
210
encryption, except for very basic 56-bit DES. If you leave the encrypt
211
settings out of your svnserve.conf entirely, you're fine; just don't set
212
max-encryption higher than 56.
214
You need a Kerberos principal for each svn server, in the form
215
"svn/${SERVER_FQDN}@${REALM}", e.g. "svn/svn1.example.com@EXAMPLE.COM".
216
If you don't store it in /etc/krb5.keytab, you'll need to set the
217
KRB5_KTNAME environment variable when starting svnserve, e.g.
219
KRB5_KTNAME=/etc/svn.keytab sudo -u svn svnserve -d -r /svn
221
This keytab file must also be readable by the svnserve process.
223
All you need in the svn.conf file is:
added
removed
notes/sasl.txt
