doc/readme.html

   1 <HTML><HEAD>
   2 <title>Cyrus SASLv2 README</title>
   3 <!-- $Id: readme.html,v 1.13 2005/02/16 20:52:05 shadow Exp $ -->
   4 </HEAD>
   5 <BODY>
   6 <H1>Read Me First</H1>
   7
   8 This document offers a general overview of the Cyrus SASL library.
   9 The Cyrus SASL Libray provides applications with an implementation
  10 of the Simple Authentication and Security Layer (RFC2222), and
  11 several authentication mechanisms.  Users interested in the "big picture"
  12 of what is provided by the library should read about
  13 <a href=components.html>Cyrus SASL Components</a>.
  14
  15 <H2>FEATURES</H2>
  16
  17 The following <a href="mechanisms.html">mechanisms</a> are included in
  18 this distribution:
  19 <ul>
  20 <li>ANONYMOUS
  21 <li>CRAM-MD5
  22 <li>DIGEST-MD5
  23 <li>EXTERNAL
  24 <li>GSSAPI (MIT Kerberos 5, Heimdal Kerberos 5 or CyberSafe)
  25 <li>KERBEROS_V4
  26 <li>LOGIN
  27 <li>NTLM (requires OpenSSL libcrypto)
  28 <li>OTP (requires OpenSSL libcrypto)
  29 <li>PLAIN
  30 <li>SRP (work in progress; requires OpenSSL libcrypto)
  31 </ul>
  32
  33 The library also supports storing user secrets in either a hash
  34 database (e.g. Berkeley DB, gdbm, ndbm), LDAP, or in a SQL database
  35 (MySQL, Postgres).
  36
  37
  38 Additionally, mechanisms such as PLAIN and LOGIN
  39 (where the plaintext password is directly supplied by the client)
  40 can perform direct password verification via the saslauthd daemon.  This
  41 allows the use of LDAP, PAM, and a variety of other password verification
  42 routines.
  43
  44 The sample directory contains two programs which provide a reference
  45 for using the library, as well as making it easy to test a mechanism
  46 on the command line.  See <a
  47 href="programming.html">programming.html</a> for more information.<p>
  48
  49 This library is believed to be thread safe IF:
  50 <ul>
  51 <li>you supply mutex functions (see sasl_set_mutex())
  52 <li>you make no libsasl calls until sasl_client/server_init() completes
  53 <li>no libsasl calls are made after sasl_done() is begun
  54 <li>when using GSSAPI, you use a thread-safe GSS / Kerberos 5 library.
  55 </ul>
  56
  57 <H2>TYPICAL UNIX INSTALLATION</H2>
  58
  59 First, if you are upgrading from Cyrus SASLv1, please see <a
  60 href="upgrading.html">upgrading.html</a>.<p>
  61
  62 Please see the file <a href="install.html">install.html</a> for instructions
  63 on how to install this package.<p>
  64
  65 Note that the library can use the environment variable SASL_PATH to locate the
  66 directory where the mechanisms are; this should be a colon-separated
  67 list of directories containing plugins.  Otherwise it will default to the
  68 value of <tt>--with-plugindir</tt> as supplied to <tt>configure</tt> (which
  69 itself defaults to <tt>/usr/local/lib</tt>).
  70
  71 <H2>INSTALLATION ON MAC OS X</H2>
  72 Please read <A HREF="macosx.html">macosx.html</A>
  73
  74 <H2>INSTALLATION ON WINDOWS</H2>
  75 Please read <A HREF="windows.html">windows.html</A>.  This configuration
  76 has not been extensively tested.
  77
  78 <H2>CONFIGURATION</H2>
  79 There are two main ways to configure the SASL library for a given
  80 application.  The first (and typically easiest) is to make use
  81 of the application's configuration files.  Provided the application supports it
  82 (via the <tt>SASL_CB_GETOPT</tt> callback), please refer to that documetation
  83 for how to supply <a href=options.html>SASL options</a>.<p>
  84
  85 Alternatively, Cyrus SASL looks for configuration files in
  86 /usr/lib/sasl/Appname.conf where Appname is settable by the
  87 application (for example, Sendmail 8.10 and later set this to
  88 "Sendmail").<p>
  89
  90 Configuration using the application's configuration files (via
  91 the <tt>getopt</tt> callback) will override those supplied by
  92 the SASL configuration files.<p>
  93
  94 For a detailed guide on configuring libsasl, please look at
  95 <A HREF=sysadmin.html>sysadmin.html</A> and
  96 <A HREF=options.html>options.html</A>
  97
  98 <H2>KNOWN BUGS</H2>
  99 <ul>
 100 <li>libtool doesn't always link libraries together.  In our environment,
 101 we only have static Krb5 libraries; the GSSAPI plugin should link
 102 these libraries in on platforms that support it (Solaris and Linux
 103 among them) but it does not.  It also doesn't always get the runpath
 104 of libraries correct.
 105 <li>Also see our <A HREF=http://bugzilla.andrew.cmu.edu>bugzilla</A>.
 106 </ul>
 107
 108 <H2>AUTHORS</H2>
 109
 110 For any comments/suggestions/bug reports, please contact <a
 111 href="mailto:cyrus-bugs@andrew.cmu.edu">cyrus-bugs@andrew.cmu.edu</a>.
 112 Be sure to include the version of libsasl and your operating system;
 113 messages without this information will not be answered.<p>
 114
 115 Major contributors to the libsasl code can be found in the top-level
 116 file AUTHORS.  Additionally saslauthd has an AUTHORS file that lists
 117 major contributors as well.<p>
 118
 119 People considering doing binary distributions that include saslauthd
 120 should be aware that the code is covered by several slightly different
 121 (but compatible) licenses, due to how it was contributed.  Details can
 122 be found within the source code.<p>
 123
 124 <hr>
 125 Back to the <A href=index.html>index</a>
 126
 127 </body>
 128 </html>
 129