doc/components.html

   1 <HTML><HEAD>
   2 <title>SASL Components</title>
   3 <!-- $Id: components.html,v 1.4 2003/07/15 17:38:57 ken3 Exp $ -->
   4 </HEAD>
   5 <BODY>
   6 <H1>SASL Components</H1>
   7
   8 <p>As the SASL library is a 'glue layer' between many different parts of the
   9 authentication system, there are a lot of different components
  10 that often cause confusion to users of the library who are trying to
  11 configure it for use on their system.  This document will try to provide
  12 some structure to all of these components, though you will also need
  13 to read the <a href=sysadmin.html>System Administration</a> to have a full
  14 understanding of how to install SASL on your system.</p>
  15
  16 <p>The first thing to realize is that there is a difference between SASL,
  17 the protocol, and Cyrus SASL, the library.  The first is a specification
  18 that describes how authentication mechanisms can be plugged into an application
  19 protocol <i>on the wire</i>.  The later is an implementation that aims
  20 to make this easier for application developers to integrate authentication
  21 mechanisms into their application in a generic way.  It is quite possible
  22 to have an application that uses SASL (the specification) without using
  23 Cyrus SASL (the implementation).</p>
  24
  25 <p>The remainder of this document will refer to components of the Cyrus
  26 SASL implementation, though some of these will necessarily have a broader
  27 scope.</p>
  28
  29 <h3>The Application</h3>
  30 The application is a client of the SASL library.  It can be a client or server
  31 application (or both, in the case of a proxy).  It takes care of the
  32 on-the-wire representation of the SASL negotiation, however it performs no
  33 analysis of the exchange itself.  It relies on the judgment of the SASL
  34 library whether authentication has occurred or not.  The application is also
  35 responsible for determining if the authenticated user may authorize as another
  36 user id (For more details on authentication and authorization identities
  37 and their differences, see
  38 <a href=sysadmin.html>Cyrus SASL for System Administrators</a>)</p>
  39
  40 <p>Examples of applications are Cyrus IMAPd, OpenLDAP, Sendmail, Mutt,
  41 sieveshell, cyradm, and many others.</p>
  42
  43 <h3>The SASL Glue Layer</h3>
  44
  45 <p>The first component of the SASL library is affectionately called the
  46 &quot;glue&quot; layer.  It takes care of ensuring that the application and
  47 the mechanisms can work together successfully.  To this end, it does a
  48 variety of basic tasks:</p>
  49
  50 <ul>
  51 <li>Loading of any plugins (more on these below)</li>
  52 <li>Ascertaining necessary security properties from the application to aid
  53 in the choice of mechanism (or to limit the available mechanisms)</li>
  54 <li>Listing of available plugins to the application (mostly used on the server
  55 side)</li>
  56 <li>Choosing the &quot;best&quot; mechanism from a list of available mechanisms
  57 for a particular authentication attempt (client-side)</li>
  58 <li>Routing the authentication (and in the case of a mechanism with a security
  59 layer, encrypted) data packets between the application and the
  60 chosen mechanism.</li>
  61 <li>Providing information about the SASL negotiation back to the application
  62 (authenticated user, requested authorization identity, security strength of
  63 any negotiated security layer, and so on).</li>
  64 </ul>
  65
  66 <p>The Cyrus SASL implementation also provides several other services to
  67 both its plugins and applications.  Some of these are simply general utilities,
  68 such as MIME Base-64 encoding and decoding, and random number generation.
  69 Others are more specific to the task of authentication, such as providing
  70 password verification services.  Such services are capable of taking
  71 a username and a plaintext password and saying &quot;yes&quit; or
  72 &quot;no&quot;.  Details of available password verification services are
  73 discussed below.</p>
  74
  75 <p>Finally, the glue code allows the mechanisms and applications access to
  76 two special types of plugins, Auxiliary Property or &quot;auxprop&quot;
  77 plugins, which provide a simple database interface and can return properties
  78 about the user such as password, home directory, or mail
  79 routing address, and Username Canonicalization, which might provide
  80 site-specific ways to canonicalize a username or perform other tasks.</p>
  81
  82 <p>In the Cyrus SASL Implementation, the glue code is entirely contained
  83 within <tt>libsasl2.so</tt> (or <tt>libsasl2.a</tt>)</p>
  84
  85 <h3>Plugins (General)</h3>
  86
  87 <p>The Cyrus SASL architechure is very modular, using loadable modules for
  88 things such as the mechanism profiles and the database access done by the
  89 auxillary property plugins.  This means that it is easy to limit what
  90 parts are loaded by a given application, and that third parties can write
  91 their own modules to provide services, just by adhering to the API description
  92 in <tt>saslplug.h</tt>.</p>
  93
  94 <h3>Plugins (SASL Mechanisms)</h3>
  95
  96 <p>The simplest types of plugins to understand are those which provide
  97 SASL mechanisms, such as CRAM-MD5, DIGEST-MD5, GSSAPI, PLAIN, SRP, and so on.
  98 These mechanisms take care of both server-side and client-side parts
  99 of the SASL negotiation.  If the given mechanism supports a security layer
 100 (that is, makes guarantees about privacy or integrity of data after the
 101 negotiation is complete), the plugin provides that functionality as well.</p>
 102
 103 <p>SASL mechanisms are generally defined by the IETF standards process,
 104 however, some mechanisms are not (For example, NTLM).  This is in contrast
 105 to the other types of plugins, which provide database and username
 106 canonicalization services to other plugins and thus aren't standardized in
 107 their behavior (they are specific to our implementation).  Password verifiers
 108 are also an implementation detail (though saslauthd makes use of
 109 standards such as PAM and LDAP to perform that verification)</p>
 110
 111 <p>There are several types of mechanisms, in broad strokes we have:</p>
 112 <ul>
 113 <li><b>Password Verification Mechanisms</b> - For example, PLAIN.  These receive a raw password from the remote and then pass it into the glue code for
 114 verification by a password verifier.  These require the existence of an
 115 outside security layer to hide the otherwise plaintext password from people
 116 who might be snooping on the wire.  These mechanisms do not require that
 117 the server have access to a plaintext (or plaintext-equivalent) version
 118 of the password.</li>
 119 <li><b>Shared Secret Mechanisms</b> - For these mechanisms, such as CRAM-MD5,
 120 DIGEST-MD5, and SRP, there is a shared secret between the server and client
 121 (e.g. a password).  However, in this case the password itself does not travel
 122 on the wire.  Instead, the client passes a server a token that proves that
 123 it knows the secret (without actually sending the secret across the wire).
 124 For these mechanisms, the server generally needs a plaintext equivalent of
 125 the secret to be in local storage (not true for SRP).
 126 <li><b>Kerberos Mechanisms</b> - Kerberos mechanisms use a trusted
 127 third party to authenticate the client.  These mechanisms don't require
 128 the server to share any secret information with the client, it is all performed
 129 through the Kerberos protocol.</li>
 130 </ul>
 131
 132 <p>Mechanism plugins are generally contained in a .so file that has a name
 133 similar to the mechanism's name.  Though, in a static compilation they
 134 can also be a part of <tt>libsasl2.a</tt></p>
 135
 136 <h3>Plugins (Auxiliary Property)</h3>
 137
 138 <p>Auxiliary Property (or auxprop) plugins provide a database service for the
 139 glue layer (and through it, to the mechanisms and application).  Cyrus SASL
 140 ships with two auxprop plugins: SASLdb and SQL.  Though they can be use
 141 in much more generic ways, auxprop plugins are mostly only used by
 142 shared secret mechanisms (or by the auxprop password verify) to access the
 143 &quot;userPassword&quot; attribute.  This provides a plaintext copy of the
 144 password that allows for authentication to take place.</p>
 145
 146 <p>Like the mechanism plugins, these are named similarly to the databases
 147 that they implement an interface for.</p>
 148
 149 <h3>Plugins (Username Canonicalization)</h3>
 150
 151 Username Canonicalization plugins are not widely used, however it may be
 152 useful to use as a hook if your site has specific requirements for how userids
 153 are presented to the applications.
 154
 155 <h3>Password Verification Services</h3>
 156
 157 <p>As described above, the password verifiers take a username and plaintext
 158 password, and say either &quot;yes&quot; or &quot;no&quot;.  It is not possible
 159 to use them to verify hashes that might be provided by the shared secret
 160 mechanisms.</p>
 161
 162 <p>Password verifiers are selected using the &quot;pwcheck_method&quot;
 163 SASL option.  There are two main password verifiers provided with Cyrus SASL:</p>
 164 <ul>
 165 <li><b>auxprop</b> - This uses an auxprop plugin to fetch the password and then
 166 compares it with the client-provided copy to make the determination.</li>
 167 <li><b>saslauthd</b> - This calls out to the <tt>saslauthd</tt> daemon, which
 168 also ships with the distribution.  The <tt>saslauthd</tt> daemon has a number
 169 of modules of its own, which allow it to do verification of passwords in
 170 a variety of ways, including PAM, LDAP, against a Kerberos database, and so on.
 171 This is how you would want to, for example, use the data contained in
 172 <tt>/etc/shadow</tt> to authenticate users.</li>
 173 </ul>
 174
 175 <hr>
 176 Back to the <a href=index.html>index</a>.
 177 </BODY>
 178 </HTML>