doc/upgrading.html

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