doc/options.html

   1 <HTML><HEAD>
   2 <title>Options for Cyrus SASL</title>
   3 <!-- $Id: options.html,v 1.30 2005/02/16 20:52:05 shadow Exp $ -->
   4 </HEAD>
   5 <BODY>
   6 <h1>Options for Cyrus SASL</h1>
   7
   8 <p>This document contains information on what options are used by the
   9 Cyrus SASL library and bundled mechanisms.  The most commonly used
  10 options (and those that are therefore most commonly misunderstood
  11 are <b>pwcheck_method</b> and <b>auxprop_plugin</b>.  Please ensure
  12 that you have configured these correctly if things don't seem to
  13 be working right.  Additionally, <b>mech_list</b> can be an easy
  14 way to limit what mechanisms a given application will use.</p>
  15
  16 <TABLE BORDER WIDTH=95%>
  17 <TR><TH>Option</TH><TH>Used By</TH><TH>Description</TH><TH>Default</TH></TR>
  18 <TR>
  19 <TD>authdaemond_path</TD><TD>SASL Library</TD>
  20 <TD>Path to Courier-IMAP authdaemond's unix socket.
  21 Only applicable when pwcheck_method is set to authdaemond.</TD><TD>/dev/null</TD>
  22 </TR>
  23 <TR>
  24 <TD>auto_transition</TD><TD>SASL Library</TD>
  25 <TD>When set to 'yes' or 'noplain',
  26 and when using an auxprop plugin, automatically transition
  27 users to other mechs when they do a successful plaintext
  28 authentication.  When set to 'noplain', only non-plaintext secrets
  29 will be written.  <I>Note that the only mechs (as currently
  30 implemented) which don't use plaintext secrets are
  31 OTP and SRP.</I></TD><TD>no</TD>
  32 </TR>
  33 <TR>
  34 <TD>auxprop_plugin</TD><TD>Auxiliary Property Plugin</TD>
  35 <TD>Name of auxiliary plugin to use, you may specify a space-separated
  36 list of plugin names, and the plugins will be queried in order</TD>
  37 <TD>(null) - querys all plugins</TD>
  38 </TR>
  39 <TR>
  40 <TD>canon_user_plugin</TD><TD>SASL Library</TD>
  41 <TD>Name of canon_user plugin to use</TD><TD>INTERNAL</TD>
  42 </TR>
  43 <TR>
  44 <TD>keytab</TD><TD>GSSAPI</TD> <TD>Location of keytab
  45 file</TD><TD><tt>/etc/krb5.keytab</tt> (system dependant)</TD>
  46 </TR>
  47 <TR>
  48 <TD>ldapdb_uri</TD><TD>LDAPDB plugin</TD>
  49 <TD>ldap server uri, you can specify a space-separated list of URIs -
  50 ldapi:// or ldaps://ldap1/ ldaps://ldap2/</TD>
  51 <TD>none</TD>
  52 </TR>
  53 <TR>
  54 <TD>ldapdb_id</TD><TD>LDAPDB plugin</TD>
  55 <TD>ldap SASL authentication id</TD>
  56 <TD>none</TD>
  57 </TR>
  58 <TR>
  59 <TD>ldapdb_mech</TD><TD>LDAPDB plugin</TD>
  60 <TD>ldap SASL mechanism for authentication</TD>
  61 <TD>none</TD>
  62 </TR>
  63 <TR>
  64 <TD>ldapdb_pw</TD><TD>LDAPDB plugin</TD>
  65 <TD>ldap password for SASL authentication id</TD>
  66 <TD>none</TD>
  67 </TR>
  68 <TR>
  69 <TD>ldapdb_rc</TD><TD>LDAPDB plugin</TD>
  70 <TD>The filename specified here will be put into the server's LDAPRC
  71 environment variable, and libldap-specific config options may be set
  72 in that ldaprc file.  The main purpose behind this option is to allow
  73 a client TLS certificate to be configured, so that SASL/EXTERNAL may
  74 be used between the SASL server and the LDAP server. This is the most
  75 optimal way to use this plugin when the servers are on separate machines.</TD>
  76 <TD>none</TD>
  77 </TR>
  78 <TR>
  79 <TD>ldapdb_starttls</TD><TD>LDAPDB plugin</TD>
  80 <TD>Use StartTLS.  This option may be set to 'try' or 'demand'.
  81 When set to "try" any failure in StartTLS is ignored.
  82 When set to "demand" then any failure aborts the connection.</TD>
  83 <TD>none</TD>
  84 </TR>
  85 <TR>
  86 <TD>log_level</TD><TD>SASL Library</TD>
  87 <TD><b>Numeric</b> Logging Level (see <TT>SASL_LOG_*</TT> in <tt>sasl.h</tt>
  88 for values and descriptions</TD>
  89 <TD>1 (SASL_LOG_ERR)</TD>
  90 </TR>
  91 <TR>
  92 <TD>mech_list</TD><TD>SASL Library</TD>
  93 <TD>Whitespace separated list of mechanisms to allow (e.g. 'plain
  94 otp').  Used to restrict the mechanisms to a subset of the installed
  95 plugins.</TD><TD>(use all available plugins)</TD>
  96 </TR>
  97 <TR>
  98 <TD>ntlm_server</TD><TD>NTLM (server)</TD>
  99 <TD>Name of server (WinNT, Win2K, Samba, etc) to which authentication
 100 will be proxied.</TD>
 101 <TD>(null) - perform authentication internally</TD>
 102 </TR>
 103 <TR>
 104 <TD>ntlm_v2</TD><TD>NTLM (client)</TD>
 105 <TD>Send NTLMv2 responses to the server.</TD>
 106 <TD>no (send NTLMv1)</TD>
 107 </TR>
 108 <TR>
 109 <TD>opiekeys</TD><TD>OTP (with OPIE)</TD>
 110 <TD>Location of the opiekeys file</TD><TD><tt>/etc/opiekeys</tt></TD>
 111 </TR>
 112 <TR>
 113 <TD>otp_mda</TD><TD>OTP (w/o OPIE)</TD>
 114 <TD>Message digest algorithm for one-time passwords, used by sasl_setpass
 115 (possible values: 'md4', 'md5', 'sha1')</TD><TD><tt>md5</tt></TD>
 116 </TR>
 117 <TR>
 118 <TD>plugin_list</TD><TD>SASL Library</TD>
 119 <TD>Location of Plugin list (Unsupported)</TD><TD><i>none</i></TD>
 120 </TR>
 121 <TR>
 122 <TD>pwcheck_method</TD><TD>SASL Library</TD>
 123 <TD>Whitespace separated list of mechanisms used to verify passwords,
 124 used by sasl_checkpass (possible values: 'auxprop', 'saslauthd',
 125 'pwcheck', 'authdaemond' [if compiled with <tt>--with-authdaemond</tt>])
 126 and 'alwaystrue' [if compiled with <tt>--enable-alwaystrue</tt>])
 127 </TD><TD>auxprop</TD>
 128 </TR>
 129 <TR>
 130 <TD>reauth_timeout</TD><TD>DIGEST-MD5</TD>
 131 <TD>Length in time (in minutes) that authentication info will be
 132 cached for a fast reauth.  A value of 0 will disable reauth.</TD>
 133 <TD>0</TD>
 134 </TR>
 135 <TR>
 136 <TD>saslauthd_path</TD><TD>SASL Library</TD>
 137 <TD>Path to saslauthd run directory (<b>including</b> the "/mux" named pipe)</TD>
 138 <TD>system dependant (generally won't need to be changed)</TD>
 139 </TR>
 140 <TR>
 141 <TD>sasldb_path</TD><TD>sasldb plugin</TD>
 142 <TD>Path to sasldb file</TD><TD><tt>/etc/sasldb2</tt> (system dependant)</TD>
 143 <TR>
 144 <TD>sql_engine</TD><TD>SQL plugin</TD>
 145 <TD>Name of SQL engine to use (possible values: 'mysql', 'pgsql', 'sqlite').</TD>
 146 <TD><tt>mysql</tt></TD>
 147 </TR>
 148 <TR>
 149 <TD>sql_hostnames</TD><TD>SQL plugin</TD>
 150 <TD>Comma separated list of SQL servers (in host[:port] format).</TD>
 151 <TD><i>none</i> (engine dependent)</TD>
 152 </TR>
 153 <TR>
 154 <TD>sql_user</TD><TD>SQL plugin</TD>
 155 <TD>Username to use for authentication to the SQL server.</TD>
 156 <TD><i>none</i> (engine dependent)</TD>
 157 </TR>
 158 <TR>
 159 <TD>sql_passwd</TD><TD>SQL plugin</TD>
 160 <TD>Password to use for authentication to the SQL server.</TD>
 161 <TD><i>none</i> (engine dependent)</TD>
 162 </TR>
 163 <TR>
 164 <TD>sql_database</TD><TD>SQL plugin</TD>
 165 <TD>Name of the database which contains the auxiliary properties.</TD>
 166 <TD><i>none</i> (engine dependent)</TD>
 167 </TR>
 168 <TR>
 169 <TD>sql_select</TD><TD>SQL plugin</TD>
 170 <TD>SELECT statement to use for fetching properties.  This option is
 171 <b>required</b> in order to use the SQL plugin.</TD>
 172 <TD><i>none</i></TD>
 173 </TR>
 174 <TR>
 175 <TD>sql_insert</TD><TD>SQL plugin</TD>
 176 <TD>INSERT statement to use for creating properties for new users.</TD>
 177 <TD><i>none</i></TD>
 178 </TR>
 179 <TR>
 180 <TD>sql_update</TD><TD>SQL plugin</TD>
 181 <TD>UPDATE statement to use for modifying properties.</TD>
 182 <TD><i>none</i></TD>
 183 </TR>
 184 <TR>
 185 <TD>sql_usessl</TD><TD>SQL plugin</TD>
 186 <TD>When set to 'yes', 'on', '1' or 'true', a secure connection will
 187 be made to the SQL server.</TD>
 188 <TD><tt>no</tt></TD>
 189 </TR>
 190 <TR>
 191 <TD>srp_mda</TD><TD>SRP</TD>
 192 <TD>Message digest algorithm for SRP calculations
 193 (possible values: 'md5', 'sha1', 'rmd160')</TD><TD><tt>sha1</tt></TD>
 194 </TR>
 195 <TR>
 196 <TD>srvtab</TD><TD>KERBEROS_V4</TD>
 197 <TD>Location of the srvtab file</TD><TD><tt>/etc/srvtab</tt> (system
 198 dependant)</TD>
 199 </TR>
 200 </TABLE>
 201
 202 <h2>Notes on SQL auxprop options</h2>
 203
 204 <p>The <tt>sql_insert</tt> and <tt>sql_update</tt> options are
 205 optional and are only needed if you wish to allow the SASL library
 206 (e.g., saslpasswd2) and plugins (e.g., OTP) to write properties to the
 207 SQL server.  If used, both statements MUST be provided so that
 208 properties can be added, changed and deleted.
 209 <font color=red>NOTE: The columns for writable properites MUST accept NULL values.</font>
 210
 211 <p>The SQL statements provided in the <tt>sql_select</tt>,
 212 <tt>sql_insert</tt> and <tt>sql_update</tt> options can contain
 213 arguments which will be substituted with the appropriate values.  The
 214 valid arguments are:
 215
 216 <DL compact>
 217 <DT><tt>%u</tt> <DD>Username whose properties are being fetched/stored.
 218
 219 <DT><tt>%p</tt> <DD>Name of the property being fetched/stored.  This could
 220      technically be anything, but SASL authentication will try
 221      userPassword and cmusaslsecretMECHNAME (where MECHNAME is the
 222      name of a SASL mechanism).
 223
 224 <DT><tt>%r</tt> <DD>Realm to which the user belongs.  This could be the
 225      kerberos realm, the FQDN of the computer the SASL application is
 226      running on or whatever is after the @ on a username.  (read the
 227      realm documentation).
 228
 229 <DT><tt>%v</tt> <DD>Value of the property being stored (INSERT or
 230      UPDATE only!). This could technically be anything depending on
 231      the property itself, but is generally a userPassword.
 232 </DL>
 233
 234 <font color=red>NOTE: DO NOT put quotes around the entire SQL
 235 statement, but each individual %u, %r and %v argument MUST be
 236 quoted.</font>
 237
 238
 239 <h3>Examples:</h3>
 240
 241 <pre>
 242      <tt>sql_select: SELECT %p FROM user_table WHERE username = '%u' and realm = '%r'</tt>
 243 </pre>
 244
 245      would send the following statement to SQL for user "bovik" and
 246      the default realm for the machine "madoka.surf.org.uk":
 247
 248 <pre>
 249      <tt>SELECT userPassword FROM user_table WHERE username = 'bovik' and
 250      realm = 'madoka.surf.org.uk';</tt>
 251
 252
 253 </pre>
 254
 255 <pre>
 256      <tt>sql_insert: INSERT INTO user_table (username, realm, %p) VALUES ('%u', '%r', '%v')</tt>
 257
 258 </pre>
 259
 260    would generate the following statement to SQL for user "bovik" in
 261    realm "madoka.surf.org.uk" with userPassword "wert":
 262
 263 <pre>
 264      <tt>INSERT INTO user_table (username, realm, userPassword) VALUES
 265      ('bovik', 'madoka.surf.org.uk', 'wert');</tt>
 266
 267
 268 </pre>
 269
 270 <p>Note that all substitutions do not have to be used. For instance,
 271 <pre>
 272      <tt>SELECT password FROM auth WHERE username = '%u'</tt>
 273 </pre>
 274 is a valid value for <tt>sql_select</tt>.
 275
 276 <h2>Notes on LDAPDB auxprop options</h2>
 277
 278 <p>
 279 </p>
 280
 281 <p>Unlike other LDAP-enabled plugins for other services that are common
 282 on the web, this plugin does not require you to configure DN search
 283 patterns to map usernames to LDAP DNs. This plugin requires SASL name
 284 mapping to be configured on the target slapd. This approach keeps the
 285 LDAP-specific configuration details in one place, the slapd.conf, and
 286 makes the configuration of remote services much simpler.</p>
 287
 288 <p>This plugin is not for use with slapd itself. When OpenLDAP is
 289 built with SASL support, slapd uses its own internal auxprop module.
 290 By default, without configuring anything else, slapd will fail to load
 291 the ldapdb module when it's present. This is as it should be. If you
 292 don't like the "auxpropfunc: error -7" message that is sent to syslog
 293 by slapd, you can stop it by creating /usr/lib/sasl2/slapd.conf with:
 294
 295     <pre>auxprop_plugin: slapd</pre>
 296
 297 which will force the SASL library to ignore all other auxprop modules.</p>
 298
 299 <h3>Examples:</h3>
 300
 301 <pre>
 302 ldapdb_uri: ldap://ldap.example.com
 303 ldapdb_id: root
 304 ldapdb_pw: secret
 305 ldapdb_mech: DIGEST-MD5
 306 </pre>
 307
 308 <p>The LDAP server must be configured to map the SASL authcId "root" into a DN
 309 that has proxy authorization privileges to every account that is allowed to
 310 login to this server. (See the OpenLDAP Admin Guide section 10 for
 311 details.)</p>
 312
 313 <pre>
 314 ldapdb_uri: ldapi://
 315 ldapdb_mech: EXTERNAL
 316 </pre>
 317
 318 <p>This configuration assumes an LDAP server is on the same server that is
 319 using SASL and the underlying OS is *NIX based (ldapi:// requires UNIX domain
 320 sockets).  This is fast and secure, and needs no username or password to be
 321 stored.  The slapd.conf will need to map these usernames to LDAP DNs:
 322
 323 <pre>
 324 sasl-regexp uidNumber=(.*)\\+gidNumber=(.*),cn=peercred,cn=external,cn=auth
 325     ldap:///dc=example,dc=com??sub?(&(uidNumber=$1)(gidNumber=$2))
 326 </pre>
 327
 328 <pre>
 329 sasl-regexp uid=(.*),cn=external,cn=auth
 330     ldap:///dc=example,dc=com??sub?(uid=$1)
 331 </pre>
 332
 333 </p>
 334
 335 <hr>
 336 Back to the <A href=index.html>index</a>
 337
 338 </body>
 339 </html>
 340