1<HTML><HEAD> 2<title>Upgrading from Cyrus SASLv1 to Cyrus SASLv2</title> 3<!-- $Id: upgrading.html,v 1.6 2006/01/20 20:15:07 snsimon Exp $ --> 4</HEAD> 5<BODY> 6<H1>Upgrading from Cyrus SASLv1 to Cyrus SASLv2</H1> 7 8This document covers issues with upgrading from SASLv1 to SASLv2. 9To upgrade: 10 11<ul> 12<li> Install Cyrus SASL v2 as normal according to <a 13href="install.html">the installation guide</a>. This will overwrite 14some manpages, but will not affect your current applications. Do NOT 15attempt to make it use the same directories, otherwise old Cyrus SASLv1 16applications will no longer function.</li> 17 18<li> Install your new Cyrus SASL v2 applications. Applications that 19use Cyrus SASLv1 will <em>not</em> use the Cyrus SASL v2 20infrastructure (and vice-versa). 21 22<li> If you used <tt>/etc/sasldb</tt> for authentication, you'll need 23to take the following steps to convert to using <tt>/etc/sasldb2</tt> 24with Cyrus SASL v2: 25 <ol> 26 <li> run <tt>utils/dbconverter-2</tt> after installation.</li> 27 <li> change the <tt>pwcheck_method</tt> in any config files to 28 <tt>auxprop</tt></li> 29 <li> (optional) add <tt>auxprop_plugin</tt> to the config files, 30 set to <tt>sasldb</tt></li> 31 </ol> 32 33<li> If you used <tt>passwd</tt>, <tt>shadow</tt>, <tt>pam</tt>, 34<tt>kerberos_v4</tt> or <tt>sia</tt> as your <tt>pwcheck_method</tt> 35in libsasl v1, you'll need to convert to using 36<tt>saslauthd</tt>. Arrange to start <tt>saslauthd -a 37<i>method</i></tt> on boot. Change <tt>pwcheck_method</tt> in any 38configuration files to <tt>saslauthd</tt>.</li> 39 40<li> If you used <tt>pwcheck</tt> with libsasl v1, you can either 41continue to use <tt>pwcheck</tt> with libsasl v1 or you can switch to 42<tt>saslauthd</tt>, which offers more flexibility and a potentially 43much more efficient implementation.</li> 44 45<li> If you are continuing to use some libsasl v1 applications, read 46onwards to understand the ramifications.</li> 47 48<li> If you want to learn how to port applications from libsasl v1 to 49libsasl v2, you should read <A HREF=appconvert.html>this document</A>. 50</ul> 51 52<h2><A NAME="overview">Backwards Compatibility</A></h2> 53 54Cyrus SASLv2 is completely incompatible with applications that use 55Cyrus SASLv1. This means that applications are unable to 56simultaneously link both versions of the library, and developers are 57encouraged to instead develop or upgrade their applications to link 58against the new libsasl.<p> 59 60Likewise, the format for the sasldb database has been completely 61revamped. See <A HREF="#db">here</A> for a discussion of the relevant 62upgrade issues related to sasldb. All new passwords stored in the 63sasldb database will be in plaintext, meaning that a compromised 64sasldb will compromise all services with the same passwords. (This 65situation isn't significantly worse, cryptographicly speaking, than 66the old method and allows the database to be easy to transition to 67another format, when the need arises.) Mechanisms requiring a more 68secure password database backend (e.g. SRP) should implement their own 69or use alternate property names within sasldb.<P> 70 71<h2><A NAME="coexist">Coexistence with SASLv1</A></h2> 72 73The two library versions and the associated utilities should be able 74to coexist on the same system. The man pages will be unable to 75coexist (but luckily the new manpages are much better!). The libsasl 76v2-specific utilities have had a "2" appended to their name for this 77purpose (e.g. <tt>saslpasswd2</tt>, <tt>sasldblistusers2</tt>). The 78new-style sasldb now defaults to the name <tt>/etc/sasldb2</tt>, but 79this is configurable. 80 81<h2><A NAME="db">Database Upgrades</A></h2> 82 83While there does not seem to be any conflict with the keys stored in 84the database, it is not recommended for both versions of the library 85to use the same database file. Included in the utils directory is a 86program called <tt>dbconverter-2</tt> which will allow you to convert 87from the old-format database to the new format. Note that if you continue to 88run older applications that rely on Cyrus SASLv1, the databases for SASLv1 89and SASLv2 will not automatically be kept in sync.<p> 90 91<hr> 92Back to the <A href=index.html>index</a> 93 94</body> 95</html> 96 97