File: README_authlib.html.in

package info (click to toggle)
courier-authlib 0.58-4%2Betch3
links: PTS
area: main
in suites: etch
size: 16,212 kB
ctags: 1,896
sloc: ansic: 21,550; sh: 14,071; makefile: 866; perl: 842; cpp: 284
file content (2612 lines) | stat: -rw-r--r-- 50,484 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML
><HEAD
><link rel='stylesheet' type='text/css' href='manpage.css'>
  <!-- $Id: README_authlib.sgml,v 1.3 2005/07/05 12:25:08 mrsam Exp $ -->
  <!-- Copyright 1998 - 2004 Double Precision, Inc.  See COPYING for -->
  <!-- distribution information. -->
<meta name="MSSmartTagsPreventParsing" content="TRUE">
<link rel="icon" href="icon.gif" type="image/gif" />
<TITLE
>Courier Authentication Library</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="AUTHLIB"
></A
>Courier Authentication Library</H1
><P
>This library is used for two purposes:</P
><P
>1. Read the name of a mail account.
Determine the local account's home directory, and system userid and
groupid.</P
><P
>2. Read an account name, and a password.
If valid, determine the account's home directory, system userid, and
groupid.</P
><P
>The term "authentication" is used in the following documentation to refer
to either one of these two functions.
The library contains several alternative authentication modules to choose
from, described below.</P
><P
>The configuration file <TT
CLASS="FILENAME"
>@authdaemonrc@</TT
> contains several
settings.  The most important of them are:</P
><P
></P
><UL
><LI
><P
>A list of authentication modules to activate.
By default, this list includes all available authentication modules,
even if some are not actually installed at the moment.
When the authentication library is set up, only those authentication
modules that can be supported by the operating system will be installed.
Some of the listed modules may not actually be there,
however that's not a problem.
Any unavailable authentication modules will be ignored.
Also, on some platforms certain authentication modules are installed by
optional sub-packages.
Installing the sub-package is the only action needed to make use of it.</P
><P
>The only time the list of authentication modules need to be adjusted is
when an available authentication module must be disabled for some reason.
This should only be needed in the most unusual circumstances.</P
></LI
><LI
><P
>Number of authentication processes.
The default setting is to start five authentication processes, which should be
sufficient for normal usage.
Try increasing this setting if its taking too long to log into an account,
and you have determined that this is not due to a bottleneck in the whatever
authentication database you're using (LDAP, MySQL, or PostgreSQL).</P
><P
>An authentication request must be completed within thirty seconds, otherwise
it gets rejected.
When authentication requests come in faster than all five authentication
processes can get to them, delays build up, and the timer is ticking.
If all the activity maxes out the CPU or I/O bandwidth,
nothing can be done about it, short
of getting another server.  However if there's plenty of available CPU and
I/O, increasing the number of processes will do the trick.</P
></LI
></UL
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN20"
>The <TT
CLASS="LITERAL"
>authpwd</TT
> authentication module</A
></H2
><P
>This modules obtains account information and passwords from the
<TT
CLASS="FILENAME"
>/etc/passwd</TT
> file.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This module doesn't actually read the <TT
CLASS="FILENAME"
>/etc/passwd</TT
>
file, it uses the C library's getpw() functions.
The C library implementation could use any mechanism to obtain the equivalent
information.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN28"
>The <TT
CLASS="LITERAL"
>authshadow</TT
> authentication module</A
></H2
><P
>This module is a version of the <TT
CLASS="LITERAL"
>authpwd</TT
> module that
reads passwords
from <TT
CLASS="FILENAME"
>/etc/shadow</TT
> (the C library's getsp()
functions).</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN34"
>The <TT
CLASS="LITERAL"
>authpam</TT
> authentication module</A
></H2
><P
>This modules uses the system's PAM library
(pluggable authentication modules) for authentication.
This is, essentially, a way to use existing PAM modules for authentication.
Note, however, that the authenticated account's home directory, userid and
groupid are still read from the <TT
CLASS="FILENAME"
>/etc/passwd</TT
> file,
since PAM functionality is limited to validating account passwords.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Not all PAM modules are compatible with Courier's authentication library.
PAM modules that make use of PAM's session functions, or authentication token
functions, like <TT
CLASS="LITERAL"
>pam_krb5</TT
> will not work with Courier.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Additional configuration steps will be required to set up
the PAM library to authenticate Courier's services.
Courier's IMAP and POP3 servers, for example, require that the
<SPAN
CLASS="QUOTE"
>"imap"</SPAN
> and <SPAN
CLASS="QUOTE"
>"pop3"</SPAN
> PAM service to be
configured.</P
><P
>The specific configuration steps differ from system to system.
Consult the system documentation for more information.
It might be tempting to throw in a towel and use
<TT
CLASS="LITERAL"
>authshadow</TT
> or <TT
CLASS="LITERAL"
>authpwd</TT
>
if you cannot figure out how to install PAM support,
however that is not advisable.
It is highly recommended to use
<TT
CLASS="FILENAME"
>authpam</TT
> wherever the PAM library is available.</P
><P
>The exact configuration procedure depends on the PAM implementation.
Most PAM libraries use configuration files in the
<TT
CLASS="FILENAME"
>/etc/pam.d</TT
> directory.
Therefore, it will be necessary to install the configuration files
<TT
CLASS="FILENAME"
>/etc/pam.d/imap</TT
> and
<TT
CLASS="FILENAME"
>/etc/pam.d/pop3</TT
>.  Similarly, Courier's webmail
server, SqWebMail, uses <TT
CLASS="FILENAME"
>/etc/pam.d/webmail</TT
>, and
its optional calendar component uses <TT
CLASS="FILENAME"
>/etc/pam.d/webmail</TT
>.
Courier-MTA's authenticated SMTP component uses the
<TT
CLASS="FILENAME"
>/etc/pam.d/smtp</TT
> service.</P
><P
>In nearly all cases all these configuration files will specify an
identical PAM library configuration for all services.
The exact configuration details are site-specific.
Here's an example of a PAM configuration file for a recent version of the
most common PAM library:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN58"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>auth       required     pam_nologin.so
auth       required     pam_stack.so service=system-auth
account    required     pam_stack.so service=system-auth
session    required     pam_stack.so service=system-auth</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Again, the actual configuration is site specific.
Examine the contents of existing configuration files in
<TT
CLASS="FILENAME"
>/etc/pam.d</TT
> for similar services (if there's
<TT
CLASS="FILENAME"
>/etc/pam.d/ppp</TT
>
it's often a good example to follow) in order
to derive the correct setup for Courier.</P
><P
>Older PAM libraries use a single configuration file, usually
<TT
CLASS="FILENAME"
>/etc/pam.conf</TT
>.
Append Courier-specific PAM settings to this configuration file, again
using settings for existing services as a guide.
For example:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN65"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>imap  auth    required        pam_unix.so      try_first_pass
imap  account required        pam_unix.so
imap  session required        pam_permit.so
pop3  auth    required        pam_unix.so      try_first_pass
pop3  account required        pam_unix.so</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Some PAM libraries use
<TT
CLASS="FILENAME"
>pam_pwdb.so</TT
> instead of
<TT
CLASS="FILENAME"
>pam_unix.so</TT
>; consult the PAM library's
documentation for more information.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN70"
>The <TT
CLASS="LITERAL"
>authpipe</TT
> authentication module</A
></H2
><P
>This is a generic plug-in module that runs an external script,
or a program, in response to authentication requests.</P
><P
>The external program reads from stdin and writes to stdout. It
can be persistent and handle many authentication requests. Only one request
will be sent to it at a time; each authdaemon process starts its own copy of
the external script.</P
><P
>The location of the external program is set by the
<TT
CLASS="LITERAL"
>--with-pipeprog</TT
> configure option,
which defaults to
<TT
CLASS="FILENAME"
>@sysconfdir@/authlib/authProg</TT
>. A sample program
is included in the courier-authlib source.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN78"
>The <TT
CLASS="LITERAL"
>authpipe</TT
> protocol</A
></H3
><P
>authpipe uses the same protocol as authdaemon clients use to communicate
with authdaemond.</P
><P
>There are four possible requests: <TT
CLASS="LITERAL"
>PRE</TT
>,
<TT
CLASS="LITERAL"
>AUTH</TT
>, <TT
CLASS="LITERAL"
>PASSWD</TT
> and
<TT
CLASS="LITERAL"
>ENUMERATE</TT
>. Apart from <TT
CLASS="LITERAL"
>AUTH</TT
>, each
request is a single line terminated by newline.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>PRE . <VAR
CLASS="REPLACEABLE"
>authservice</VAR
> <VAR
CLASS="REPLACEABLE"
>username</VAR
> <I
CLASS="EMPHASIS"
>&#60;newline&#62;</I
></DT
><DD
><P
>Look up data for an account.
      <VAR
CLASS="REPLACEABLE"
>authservice</VAR
> identifies the service the
      user is trying to use - e.g. pop3, imap, webmail etc.</P
><P
>If the account exists, return the account
      data as a series of ATTR=value newline-terminated lines, followed by a
      period on a line of its own. Valid attributes are:
      </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="SCREEN"
>      USERNAME=username         -- system account which owns mailbox (name)
      UID=uid                   -- system account which owns mailbox (numeric uid)
      GID=gid                   -- numeric groupid
      HOME=homedir              -- home directory
      ADDRESS=addr              -- e-mail address
      NAME=name                 -- full name
      MAILDIR=maildir           -- Maildir relative to home directory
      QUOTA=quota               -- quota string: maxbytesS,maxfilesC
      PASSWD=cryptpasswd        -- encrypted password
      PASSWD2=plainpasswd       -- plain text password
      OPTIONS=acctoptions       -- option1=val1,option2=val2,...
      .
      </PRE
></TD
></TR
></TABLE
><P
>      Of these, it is mandatory to return ADDRESS, HOME, GID, and either UID
      or USERNAME; the others are optional.
      </P
><P
>If the account is not known, return <TT
CLASS="LITERAL"
>FAIL</TT
><I
CLASS="EMPHASIS"
><TT
CLASS="LITERAL"
>&#60;newline&#62;</TT
></I
>.
      If there is a temporary failure, such as a database being down, authProg
      should terminate (thereby closing stdin/stdout) without sending any
      response. authdaemon will restart the pipe module for the next
      request, thus ensuring it is properly reinitialized.
      </P
></DD
><DT
>AUTH <VAR
CLASS="REPLACEABLE"
>len</VAR
><I
CLASS="EMPHASIS"
>&#60;newline&#62;</I
><VAR
CLASS="REPLACEABLE"
>len-bytes</VAR
></DT
><DD
><P
>    Validate a login attempt. The AUTH line is followed by
    <I
CLASS="EMPHASIS"
>len-bytes</I
> of authentication data, which does not
    necessarily end with a newline. The currently defined authentication
    requests are:
    </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="SCREEN"
>    login \n username \n password [\n]         -- plaintext login
    cram-md5 \n challenge \n response [\n]     -- base-64 encoded challenge and response
    cram-sha1 \n challenge \n response [\n]    -- ditto
    cram-sha256 \n challenge \n response [\n]  -- ditto
    </PRE
></TD
></TR
></TABLE
><P
>    In the case of success, return the complete set of
    account parameters in the same format as PRE, ending with a period on 
    a line of its own. In the case of failure (e.g. username does not exist,
    password wrong, unsupported authentication type), return
    <TT
CLASS="LITERAL"
>FAIL</TT
><I
CLASS="EMPHASIS"
><TT
CLASS="LITERAL"
>&#60;newline&#62;</TT
></I
>.
    If there is a temporary failure, such as a database being down, authProg
    should terminate without sending any response.
    </P
><P
>    Note: if the user provides a plaintext password and authenticates
    successfully, then you can return it as PASSWD2 (plain text password)
    even if the database contains an encrypted password. This is useful
    when using the POP3/IMAP proxy functions of courier-imap.
    </P
></DD
><DT
>PASSWD <VAR
CLASS="REPLACEABLE"
>service</VAR
><I
CLASS="EMPHASIS"
>&#60;tab&#62;</I
>
      <VAR
CLASS="REPLACEABLE"
>username</VAR
><I
CLASS="EMPHASIS"
>&#60;tab&#62;</I
>
      <VAR
CLASS="REPLACEABLE"
>oldpasswd</VAR
><I
CLASS="EMPHASIS"
>&#60;tab&#62;</I
>
      <VAR
CLASS="REPLACEABLE"
>newpasswd</VAR
><I
CLASS="EMPHASIS"
>&#60;tab&#62;</I
>
      <I
CLASS="EMPHASIS"
>&#60;newline&#62;</I
></DT
><DD
><P
>Request a password change for the given account: validate that
      the oldpassword is correct, and if so, change it to the newpassword.
      </P
><P
>Reply: the string
      for success, or <TT
CLASS="LITERAL"
>FAIL</TT
><I
CLASS="EMPHASIS"
><TT
CLASS="LITERAL"
>&#60;newline&#62;</TT
></I
> for
      a data error (e.g. no such account, old password wrong, new password not
      acceptable). In the case of a temporary failure, such as a database
      being down, authProg should terminate without sending any response.
      </P
></DD
><DT
>ENUMERATE <I
CLASS="EMPHASIS"
>&#60;newline&#62;</I
></DT
><DD
><P
>    Return a list of all accounts, one per line in the following format,
    ending with a period on a line of its own:
    </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="SCREEN"
>    username \t uid \t gid \t homedir \t maildir \t options \n
    .
    </PRE
></TD
></TR
></TABLE
><P
>    If your module does not support the ENUMERATE command then return just
    a period on a line of its own (which will still allow enumeration data
    from other modules to be returned). In the case of a temporary failure,
    such as a database being down or an error occuring mid-way through
    returning account data, authProg should terminate before sending
    the terminating period.
    </P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN142"
>The <TT
CLASS="LITERAL"
>authuserdb</TT
> authentication module</A
></H2
><P
>This module
uses a GDBM or a DB-based
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
> database.
This module also incorporates userdb-based challenge-response authentication
implementation that was done by a separate <TT
CLASS="LITERAL"
>authcram</TT
> module
in previous versions of the Courier authentication library.</P
><P
><TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
> is a plain file that
can be edited with any text editor.
The file contains a list of account names, and their pertinent information.
<TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
> may alternatively be a
directory containing plain text files, which are effectively concatenated
together to form the actual list of accounts.
The <B
CLASS="COMMAND"
>makeuserdb</B
> script compiles the account information
into a GDBM or DB database file, which can be quickly looked up.</P
><P
><TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
> is loosely equivalent in
function to <TT
CLASS="FILENAME"
>/etc/passwd</TT
> and
<TT
CLASS="FILENAME"
>/etc/shadow</TT
>, and contain analous information: account
name, its numeric userid and groupid, home directory, and passwords.
<TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
> also contains additional
Courier-specific metadata, such as account quotas and other account-specific
settings.
<TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
> files can also be
maintained by custom-written Perl scripts, instead of being edited
by hand.</P
><P
><TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
>
allows creation of virtual mail accounts that do not have a corresponding
login account -- virtual mail accounts that can share the same, reserved,
system userid.
<TT
CLASS="FILENAME"
>@sysconfdir@/authlib/userdb</TT
>
can also be used to completely supersede
<TT
CLASS="FILENAME"
>/etc/passwd</TT
>.
With many accounts it can be quite a drain to have to continuously linearly
scan <TT
CLASS="FILENAME"
>/etc/passwd</TT
> in order to look up an account.
Instead, a fast database lookup can retrieve the same information from the
database file.
Review the included manual pages, starting with
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
>, for more information.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN170"
>A brief <TT
CLASS="LITERAL"
>userdb</TT
> primer</A
></H3
><P
><TT
CLASS="LITERAL"
>userdb</TT
> is a way to implement many virtual mailboxes - many
mailboxes that do not have to have a separate system userid allocated for
each one, and there is no system login associated with each mailbox.
<TT
CLASS="LITERAL"
>userdb</TT
> uses a database for mapping virtual addresses to physical
maildirs. It should be scalable to thousands of mailboxes. It can also be
used to replace linear searches of <TT
CLASS="FILENAME"
>/etc/passwd</TT
> with a database
lookup, see
<A
HREF="pw2userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>pw2userdb</SPAN
>(8)</SPAN
></A
>.</P
><P
>Note - you still MUST use some valid system userid and groupid that is
shared by all virtual mailboxes. Instead of allocating a single userid and
groupid per each mailbox, the same userid and groupid is used for all of
them.</P
><P
>This is a rough overview of using userdb. For additional information, read
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
>
and
<A
HREF="makeuserdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>makeuserdb</SPAN
>(8)</SPAN
></A
>. All the scripts will
be installed in <TT
CLASS="FILENAME"
>@sbindir@</TT
>, so look for them there.</P
><P
>The best way to describe how <TT
CLASS="LITERAL"
>userdb</TT
> works is to try to create
one virtual mail account. As mentioned before, virtual mailboxes still need
one system account to be used for uid/gid purposes. Let's call this system
account "vmail".</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN194"
>A simple userdb setup</A
></H3
><P
>This approach should be used if you do not have many virtual mailboxes.
It's very simple, but quickly becomes cumbersome if you administer many
virtual mailboxes.</P
><P
>Create an empty <TT
CLASS="FILENAME"
>@userdb@</TT
> file:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN199"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># cp /dev/null @userdb@
# chmod 700 @userdb@</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
><TT
CLASS="FILENAME"
>@userdb@</TT
> must have 700 permissions,
since it will contain passwords.</P
><P
>Now, run the script <B
CLASS="COMMAND"
>pw2userdb</B
>, as root.
This script converts the
contents of <TT
CLASS="FILENAME"
>/etc/passwd</TT
>
to the <TT
CLASS="FILENAME"
>@userdb@</TT
> format
(including the contents of <TT
CLASS="FILENAME"
>/etc/shadow</TT
>,
this is why permissions
on <TT
CLASS="FILENAME"
>@userdb@</TT
> must be 700). This script is usually used
where you
want to convert a very large <TT
CLASS="FILENAME"
>/etc/passwd</TT
> to
<TT
CLASS="FILENAME"
>@userdb@</TT
>. <TT
CLASS="LITERAL"
>userdb</TT
> applications can now
use a fast
<TT
CLASS="LITERAL"
>userdb</TT
> database instead of a linear scan
of <TT
CLASS="FILENAME"
>/etc/passwd</TT
>
in order to look up system accounts. However, you probably don't want to
use this feature right now, so what you want to do is take the output
of <B
CLASS="COMMAND"
>pw2userdb</B
>, and find the entry for the vmail account
that you
created earlier. Look for a line that starts with 'vmail' followed by tab,
followed by familiar fields from <TT
CLASS="FILENAME"
>/etc/passwd</TT
>. Save the
output of
<B
CLASS="COMMAND"
>pw2userdb</B
> in a temporary file, edit it, and remove
everything
except the line containing vmail, and the very next line, which is a special
entry that maps vmail's userid back to the vmail record.</P
><P
>Here's what you might find in the output of
<B
CLASS="COMMAND"
>pw2userdb</B
>:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN219"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>vmail   uid=1012|gid=1012|home=/home/vmail|systempw=*
1012=   vmail</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>The actual numerical values and the home directory location may vary.
Save
these two lines as <TT
CLASS="FILENAME"
>@userdb@</TT
>, and set the permissions on
<TT
CLASS="FILENAME"
>@userdb@</TT
> to 700:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN224"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>$ chmod 700 <TT
CLASS="FILENAME"
>@userdb@</TT
></PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Now, with that out of the way, let's really create a virtual account. In
this example we'll create a virtual mailbox for 'john@example.com'.</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN228"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># su vmail
$ cd ~vmail
$ mkdir john-example
$ maildirmake john-example/Maildir
$ exit
#</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>You may need to specify a full path to your <B
CLASS="COMMAND"
>maildirmake</B
>
program. The end result is that you created
<TT
CLASS="FILENAME"
>$HOME/john-example</TT
> in vmail's account, which
can be thought of as a <SPAN
CLASS="QUOTE"
>"virtual home directory"</SPAN
> for
<SPAN
CLASS="QUOTE"
>"john@example.com"</SPAN
>, that contains the account's maildir
mailbox.</P
><P
>Now, let's connect the dots here, and create an entry in
<TT
CLASS="FILENAME"
>@userdb@</TT
> for <TT
CLASS="FILENAME"
>john@example.com</TT
>:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN238"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># userdb "john@example.com" set home=/home/vmail/john-example \
                                uid=UUU gid=GGG</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>This command runs the script named <TT
CLASS="FILENAME"
>userdb</TT
> , which is
installed, by default in <TT
CLASS="FILENAME"
>@sbindir@</TT
>. Replace UUU and
GGG with the userid and groupid of the vmail account. If you now look in
<TT
CLASS="FILENAME"
>@userdb@</TT
>, you will see that a new record for
<SPAN
CLASS="QUOTE"
>"john@example.com"</SPAN
>
has been appended to the end of the file.</P
><P
>One more detail: we need to set the IMAP password for this
mailbox:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN246"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># userdbpw | userdb "john@example.com" set imappw</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>On most modern Linux and BSD distributions, you can specify the -md5
option to <B
CLASS="COMMAND"
>userdbpw</B
>, in order to use MD5 password hashes,
instead of crypt. The traditional password function allows passwords only
up to 8 characters long; everything in excess is ignored.
The newer MD5 passwords, now supported by most modern systems, allow
longer passwords.</P
><P
>Use "<TT
CLASS="LITERAL"
>systempw</TT
>" instead of
"<TT
CLASS="LITERAL"
>imappw</TT
>" if you would like to use the same password for the POP3
server, and for all other services.
The "<TT
CLASS="LITERAL"
>imappw</TT
>" field is only checked by the IMAP server.
If not
defined, "<TT
CLASS="LITERAL"
>systempw</TT
>" is used instead. The field
<TT
CLASS="LITERAL"
>pop3pw</TT
>
is checked only by Courier's POP3 server. If it is
not defined the POP3 server will check <TT
CLASS="LITERAL"
>systempw</TT
> too.</P
><P
>Finally, compile the database:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN258"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># makeuserdb</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>This command creates the actual database, <TT
CLASS="FILENAME"
>@userdb@.dat</TT
> and
<TT
CLASS="FILENAME"
>@userdb@shadow.dat</TT
> from the plain text file
<TT
CLASS="FILENAME"
>@userdb@</TT
>. Courier will now start accepting logins to this
mailbox. Adding and removing mailboxes can be done while Courier is
running.</P
><P
>Courier reads <TT
CLASS="FILENAME"
>@userdb@.dat</TT
> and
<TT
CLASS="FILENAME"
>@userdb@shadow.dat</TT
> only. The plain text source,
<TT
CLASS="FILENAME"
>@userdb@</TT
> is not read by Courier itself. Changes take
effect
only when <B
CLASS="COMMAND"
>makeuserdb</B
> runs.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN269"
>Large virtual domain farm</A
></H3
><P
>The previous approach used a single flat file, <TT
CLASS="FILENAME"
>@userdb@</TT
>.
This
will work for up to a couple of hundred accounts.
An slightly different approach can scale to thousands of
domains and mailboxes.</P
><P
>Instead of creating a <TT
CLASS="FILENAME"
>@userdb@</TT
> file, create a
subdirectory:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN275"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># mkdir @userdb@
# chmod 700 @userdb@</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Now, create <TT
CLASS="FILENAME"
>@userdb@/default</TT
>, containing pw2userdb's
output
for the vmail account, as previously described.</P
><P
>This time, you probably want to create all mailboxes for the same domain
in a separate subdirectory:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN280"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># su - vmail
$ cd ~vmail
$ mkdir -p domains/example-com
$ mkdir domains/example-com/john
$ maildirmake domains/example-com/john
$ exit</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>The idea is that all the maildirs for <TT
CLASS="LITERAL"
>@example.com</TT
> will
now be found
in <TT
CLASS="FILENAME"
>~vmail/domains/example-com</TT
>. All maildirs for
<TT
CLASS="LITERAL"
>domain.org</TT
> will be in
<TT
CLASS="FILENAME"
>~vmail/domains/domain.org</TT
>. The actual layout and naming
conventions are entirely up to you to define.</P
><P
>Here's how configure <TT
CLASS="FILENAME"
>@userdb@</TT
>:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN289"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>$ userdb "example-com/john@example.com" set \
             home=/home/vmail/domains/example-com/john \
             uid=UUU gid=GGG</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>This creates the file <TT
CLASS="FILENAME"
>@userdb@/example-com</TT
> (the first
parameter to the <B
CLASS="COMMAND"
>userdb</B
> command), and appends a record named
"john@example.com". You will store all <TT
CLASS="LITERAL"
>userdb</TT
> entries for
<TT
CLASS="LITERAL"
>@example.com</TT
> in the file
<TT
CLASS="FILENAME"
>@userdb@/example-com</TT
>. All
entries for <TT
CLASS="LITERAL"
>@domain.org</TT
> will be maintained in
<TT
CLASS="FILENAME"
>@userdb@/domain-org</TT
>, and so on.</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN299"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>$ userdbpw | userdb "example-com/john@example.com" set imappw</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>This sets the IMAP access password for this account. Finally:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN302"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>$ makeuserdb</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN304"
>Beyond <TT
CLASS="LITERAL"
>userdb</TT
></A
></H3
><P
><TT
CLASS="LITERAL"
>userdb</TT
> is a simple, straightforward solution that scales
to a couple of thousand of mail accounts, depending on the hardware.
Beyond that, one of database-based modules will need to be used,
such as
<TT
CLASS="LITERAL"
>authldap</TT
>,
<TT
CLASS="LITERAL"
>authmysql</TT
>,
<TT
CLASS="LITERAL"
>authpgsql</TT
>.
Since <TT
CLASS="LITERAL"
>userdb</TT
> is maintained as plain text files that
are easily parsed by a script, migrating data from userdb will not be
difficult.</P
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN313"
>The <TT
CLASS="LITERAL"
>authvchkpw</TT
> authentication module</A
></H2
><P
>This module uses
the <TT
CLASS="LITERAL"
>vpopmail/vchkpw</TT
> library for authentication.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN318"
>The <TT
CLASS="LITERAL"
>authmysql</TT
> authentication module</A
></H2
><P
>This module reads
the list of mail accounts and passwords from a table in a
MySQL database.
The <TT
CLASS="FILENAME"
>@authmysqlrc@</TT
> configuration file defines the
particular details regarding the MySQL database and the schema of the
mail account table.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN323"
>The <TT
CLASS="LITERAL"
>authpgsql</TT
> authentication module</A
></H2
><P
>This module reads
the list of mail accounts and passwords from a table in a
PostgreSQL database.
The <TT
CLASS="FILENAME"
>@authpgsqlrc@</TT
> configuration file defines the
particular details regarding the PostgreSQL database and the schema of the
mail account table.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN328"
>The <TT
CLASS="LITERAL"
>authldap</TT
> authentication module</A
></H2
><P
>This module reads
the list of mail accounts and passwords from an LDAP directory.
The <TT
CLASS="FILENAME"
>@authldaprc@</TT
> configuration file defines the
particular details regarding the LDAP directory layout.</P
><P
>A suggested LDAP schema can be found in the file
<TT
CLASS="FILENAME"
>authldap.schema</TT
>, 
which is included in Courier authentication library's source code, and
may be installed on your system.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN335"
><TT
CLASS="LITERAL"
>authcustom</TT
></A
></H2
><P
>This is a do-nothing module where custom authentication code
can be added.
This authentication module is just a stub that doesn't really do anything.
It's purpose is to serve as a placeholder where custom authentication code
can be easily implement.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN339"
>Account options</A
></H2
><P
>The authentication library has a facility for keep arbitrary
<SPAN
CLASS="QUOTE"
>"name=value"</SPAN
>-type settings,
called <SPAN
CLASS="QUOTE"
>"options"</SPAN
>, for individual accounts. This feature is
only available with
<TT
CLASS="LITERAL"
>userdb</TT
>,
<TT
CLASS="LITERAL"
>LDAP</TT
>, <TT
CLASS="LITERAL"
>MySQL</TT
>, and
<TT
CLASS="LITERAL"
>PostgresSQL</TT
>
modules. Individual account options are not supported with
system-based authentication modules (password/shadow files, or PAM).</P
><P
>See the
<A
HREF="auth_generic.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>auth_generic</SPAN
>(3)</SPAN
></A
>
for a description of option names used by various Courier packages.
Other applications can make up names for their own settings, and
use them in the same way.</P
><P
>Account options are specified via the authentication modules in the
following manner:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>userdb</TT
></DT
><DD
><P
>Use the <B
CLASS="COMMAND"
>userdb</B
> command to set a field called
"<TT
CLASS="LITERAL"
>options</TT
>". Example:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN362"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>userdb user1@example.com set options=disableimap=1,sharedgroup=44
makeuserdb</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>The option text string here is
"<TT
CLASS="LITERAL"
>disableimap=1,sharedgroup=44</TT
>".
It specifies two options.</P
></DD
><DT
><TT
CLASS="LITERAL"
>LDAP</TT
></DT
><DD
><P
>Account options are defined by the <TT
CLASS="LITERAL"
>LDAP_AUXOPTIONS</TT
>
setting in the <TT
CLASS="FILENAME"
>authldaprc</TT
> configuration file.
<TT
CLASS="LITERAL"
>LDAP_AUXOPTIONS</TT
> consists of a comma-separated list of
"<TT
CLASS="LITERAL"
>attribute=setting</TT
>". "attribute" is the name of an LDAP
attribute, and "setting" is the corresponding account setting name. The
value of the attribute becomes the value of the setting. Unless you
value your sanity, the names of LDAP attributes should be the same as
the actual setting names (in which case "=setting" may be dropped and
<TT
CLASS="LITERAL"
>LDAP_AUXOPTIONS</TT
> becomes a simple comma-separated list of
supported settings), but they don't have to be.</P
><P
><TT
CLASS="LITERAL"
>LDAP_AUXOPTIONS</TT
> is nothing more than a simple mapping
of LDAP attributes to account settings. A <TT
CLASS="LITERAL"
>LDAP_AUXOPTIONS</TT
>
of "shared=sharedgroup,disableimap" means that the LDAP attribute
called "shared" contains the "sharedgroup" setting, as described
previously; and an LDAP attribute of disableimap contains the setting
of the same name.</P
></DD
><DT
><TT
CLASS="APPLICATION"
>MySQL</TT
>, and <TT
CLASS="APPLICATION"
>PostgreSQL</TT
></DT
><DD
><P
>Account options are defined by <TT
CLASS="LITERAL"
>MYSQL_AUXOPTIONS_FIELD</TT
>
or <TT
CLASS="LITERAL"
>POSTGRESQL_AUXOPTIONS_FIELD</TT
>, in its corresponding
configuration file. In the most simplest case, add a character field to
the database, and put the field name into the
<TT
CLASS="LITERAL"
>MYSQL_AUXOPTIONS_FIELD</TT
> or
<TT
CLASS="LITERAL"
>POSTGRESQL_AUXOPTIONS_FIELD</TT
> configuration file setting.
For each account, the character field should contain the literal option
string. Yes, you'll just put "shared=sharedgroup,disableimap"
literally, in that field.</P
><P
>Fortunately, there is a cleaner way to do this, which avoid driving
a database designer batty. Keep in mind that the contents of
<TT
CLASS="LITERAL"
>MYSQL_AUXOPTIONS_FIELD</TT
>/<TT
CLASS="LITERAL"
>POSTGRESQL_AUXOPTIONS_FIELD</TT
>
are simply inserted directly into the SQL query that fetches the
account information. Both MySQL and PostgreSQL have a rich SQL that can
be used to manufacture a suitable option string from plain,
garden-variety, database fields. That is, you may define individual
table fields like "disableimap", and "disablepop3", then provide a
suitable (albeit ugly) SQL fragment that combines them together into
the expected option string. An example of such an SQL string is
provided in the comments portion of the configuration file.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>When using the alternative custom query option, the option string
        is the last field that the custom SQL query should return.</P
></TD
></TR
></TABLE
></DIV
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN394"
>Running <B
CLASS="COMMAND"
>authtest</B
></A
></H2
><P
>The <B
CLASS="COMMAND"
>authtest</B
> command may be used to verify that the
authentication library is working:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN399"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>authtest userid
authtest userid password
authtest userid password newpassword
authenumerate</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Running
<B
CLASS="COMMAND"
>authtest</B
>
with one argument should display the selected account's
home directory, userid, groupid,
and other related data.
The second argument to
<B
CLASS="COMMAND"
>authtest</B
>,
if supplied, specifies the account's password.
The two argument form of
<B
CLASS="COMMAND"
>authtest</B
>
validates the password, and displays an indication whether the given
password is valid, or not.
The three argument form of the
<B
CLASS="COMMAND"
>authtest</B
>
command attemps to change the account's password.
The second argument is the old password, the third argument is the
new password.</P
><P
>See <A
HREF="README.authdebug.html"
TARGET="_top"
><TT
CLASS="FILENAME"
>README.authdebug.html</TT
></A
> for more information.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN409"
>Changing account passwords</A
></H3
><P
>For the virtual domain modules (<TT
CLASS="LITERAL"
>authldap</TT
>,
<TT
CLASS="LITERAL"
>authmysql</TT
>, <TT
CLASS="LITERAL"
>authpgsql</TT
> and friends) changing the
login is a no-brainer. The tricky situation is when SqWebMail uses system
passwords to log in (the <TT
CLASS="LITERAL"
>authpwd</TT
>, <TT
CLASS="LITERAL"
>authshadow</TT
>, or
<TT
CLASS="LITERAL"
>authpam</TT
> authentication module). Different systems use different
ways to keep login passwords. Many systems use the traditional
<TT
CLASS="FILENAME"
>/etc/passwd</TT
> and <TT
CLASS="FILENAME"
>/etc/shadow</TT
> files. Other systems
use a binary database; other systems use NIS. And on some systems the
password file lookup library is a wrapper that goes against an external LDAP
directory, or a database. For maximum compatibility, SqWebMail changes login
passwords by running the <B
CLASS="COMMAND"
>passwd</B
> command. This is the traditinal
*nix command that changes login passwords. <B
CLASS="COMMAND"
>passwd</B
> is an
interactive command. It's normally run from a terminal.
 SqWebMail uses an
<B
CLASS="COMMAND"
>expect</B
> script - as mentioned in
the introduction - to answer interactive
prompts from <B
CLASS="COMMAND"
>passwd</B
>. The <B
CLASS="COMMAND"
>expect</B
> script expects to
get a plain, garden-variety, <B
CLASS="COMMAND"
>passwd</B
> command, which acts
something like this:</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN426"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>     # passwd
     Changing password for luser
     (current) UNIX password:         (old password typed here)
     New UNIX password:               (new password typed here)
     Retype new UNIX password:        (new password retyped here)
     passwd: all authentication tokens updated successfully
     #</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><P
>Systems that use a <B
CLASS="COMMAND"
>passwd</B
> command with very different prompts
may find that the default <B
CLASS="COMMAND"
>expect</B
> script will fail. In which case
it will be necessary to tweak the <B
CLASS="COMMAND"
>expect</B
> script to match the
prompts from the system's <B
CLASS="COMMAND"
>passwd</B
> command.</P
><P
>Modern systems use a <B
CLASS="COMMAND"
>passwd</B
> command that rejects "bad"
passwords - passwords that are based on dictionary words, are too short, or
are obvious for other reasons. When testing the ability to change
system passwords be sure to use randomly-generated gibberish for the test
passwords. Otherwise, the default <B
CLASS="COMMAND"
>expect</B
> script will
actually be
working, but you won't be the wiser. For security reasons, the actual
messages from <B
CLASS="COMMAND"
>passwd</B
> will not be shown by.</P
><P
>The <B
CLASS="COMMAND"
>expect</B
> script is installed as
<TT
CLASS="FILENAME"
>/usr/local/libexec/courier-authlib/authsystem.passwd</TT
>
(assuming default options to the <B
CLASS="COMMAND"
>configure</B
> script).</P
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN441"
>Authentication internals</A
></H2
><P
>The following structure describes an authentication module:</P
><A
NAME="AEN444"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN445"
></A
><P
><B
>Example 1. struct authstaticinfo</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct authstaticinfo {
	const char *auth_name;
	int (*auth_func)(const char *, const char *, char *, int,
			 int (*)(struct authinfo *, void *),
			 void *);
	int (*auth_prefunc)(const char *, const char *,
			    int (*)(struct authinfo *, void *),
			    void *);
	void (*auth_cleanupfunc)();
	int (*auth_changepwd)(const char *, /* service */
			      const char *, /* userid */
			      const char *, /* oldpassword */
			      const char *); /* new password */

	void (*auth_idle)();
	/* Not null - gets called every 5 mins when we're idle */

	void (*auth_enumerate)( void(*cb_func)(const char *name,
					       uid_t uid,
					       gid_t gid,
					       const char *homedir,
					       const char *maildir,
					       void *void_arg),
				void *void_arg);
	} ;</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
>An authentication module is a shared library that defines a single function
called
<SPAN
CLASS="QUOTE"
>"courier_auth_<VAR
CLASS="REPLACEABLE"
>NAME</VAR
>_init"</SPAN
>, where
<SPAN
CLASS="QUOTE"
>"NAME"</SPAN
> is the name of the authentication module.
The shared library does not need to export any other symbols, this is the
only function that needs to be exported.
The function returns a pointer to the <CODE
CLASS="STRUCTNAME"
>authstaticinfo</CODE
>
structure.
For example, the relevant code from the <TT
CLASS="LITERAL"
>authmysql</TT
> module is:</P
><A
NAME="AEN454"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN455"
></A
><P
><B
>Example 2. authmysql</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static struct authstaticinfo authmysql_info={
	"authmysql",
	auth_mysql,
	auth_mysql_pre,
	auth_mysql_cleanup,
	auth_mysql_changepw,
	auth_mysql_cleanup,
	auth_mysql_enumerate};


struct authstaticinfo *courier_authmysql_init()
{
	return &#38;authmysql_info;
}</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
><TT
CLASS="FUNCTION"
>auth_func</TT
> points to a function that handles an
authentication request.  The function is invoked as follows:</P
><A
NAME="AEN460"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN461"
></A
><P
><B
>Example 3. auth_func</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int result=auth_func(const char *service, const char *authtype,
			const char *authdata,
			int (*callback_func)(struct authinfo *, void *),
			void *callback_arg);</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
><SPAN
CLASS="QUOTE"
>"service"</SPAN
> is the name of the service being authenticated,
such as <SPAN
CLASS="QUOTE"
>"<TT
CLASS="LITERAL"
>imap</TT
>"</SPAN
> or
<SPAN
CLASS="QUOTE"
>"<TT
CLASS="LITERAL"
>pop3</TT
>"</SPAN
>.
<SPAN
CLASS="QUOTE"
>"authtype"</SPAN
> defines the authentication format,
and <SPAN
CLASS="QUOTE"
>"authdata"</SPAN
> is the actual authentication request.</P
><P
>Two authentication formats are defined at this time.
The <SPAN
CLASS="QUOTE"
>"authtype"</SPAN
> string is set to one of the following
strings:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="QUOTE"
>"login"</SPAN
></DT
><DD
><P
>Tradition userid/password authentication.
<TT
CLASS="LITERAL"
>authdata</TT
> points to a string that consists of:
the userid; a newline character; the password; a final newline
character.</P
></DD
><DT
><SPAN
CLASS="QUOTE"
>"cram-md5"</SPAN
>, or <SPAN
CLASS="QUOTE"
>"cram-sha1"</SPAN
></DT
><DD
><P
>Challenge/response authentication.
<TT
CLASS="LITERAL"
>authdata</TT
> points to a string that consists of:
the base64-encoded challenge; a newline character;
the base64-encoded response string; and a final newline
character.  Furthermore, the base64-encoded response string consists of:
the login ID, a space character, and the response as a hexadecimal
string (yes, base64-encoding of the response string is not strictly
necessary).</P
></DD
></DL
></DIV
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Not all authentication modules may implement all authentication formats.
An authentication module that does not implement a particular authentication
format should handle it the same way as an invalid login ID.</P
></TD
></TR
></TABLE
></DIV
><P
>The authentication function should return a negative value if the login ID
is invalid. The authentication library will try the next authentication
module.</P
><P
>The authentication function should return a positive value if the login ID
is valid, but the password is invalid. The authentication library will not
try any more authentication modules.</P
><P
>Otherwise, the authentication module should call the
<TT
CLASS="FUNCTION"
>callback_func</TT
> function, and return the same value that's
returned by this function.</P
><P
>The authentication module should pass through <TT
CLASS="LITERAL"
>callback_arg</TT
>
to the callback function as a second argument.
The first argument is a pointer to the
<CODE
CLASS="STRUCTNAME"
>authinfo</CODE
> structure, which is described in detail
in the
<A
HREF="auth_generic.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>auth_generic</SPAN
>(3)</SPAN
></A
>
manual page.
The authentication module is responsible for allocating this structure.
After the callback function returns this structure can be deallocated.
The authentication module initializes the following fields:</P
><P
><TT
CLASS="FUNCTION"
>auth_pre_func</TT
> points to a function that obtains
account information.  The function is invoked as follows:</P
><A
NAME="AEN503"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN504"
></A
><P
><B
>Example 4. auth_pre_func</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int auth_pre_func(const char *user, const char *service,
                  int (*callback)(struct authinfo *, void *), void *arg);</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
>This function does the same thing as <SPAN
CLASS="QUOTE"
>"auth_func"</SPAN
> except that
the password is not actually verified.
If the account exists, the callback function is invoked with the
same callback arguments.</P
><P
><TT
CLASS="FUNCTION"
>auth_cleanup_func</TT
> points to a function that will be
invoked just before the authentication module is uninstalled, giving it
the opportunity for some last-minute cleanup.</P
><P
><TT
CLASS="FUNCTION"
>auth_idle</TT
> points to a function that will be
invoked when no authentication requests are received for a couple of minutes,
giving the authentication module an opportunity to close any database
connections, so that they do not get shut down by the server, for inactivity,
resulting in an error the next time an authentication request is
received.</P
><P
><TT
CLASS="FUNCTION"
>auth_changepwd</TT
> points to a function that will be
invoked to change a password on an account, as follows.</P
><A
NAME="AEN515"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN516"
></A
><P
><B
>Example 5. auth_changepwd</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int auth_changepwd(const char *service, const char *user,
			const char *oldpw, const char *newpw);</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
><TT
CLASS="LITERAL"
>service</TT
> is the name of the service whose password is to
be changed (such as <SPAN
CLASS="QUOTE"
>"imap"</SPAN
> or <SPAN
CLASS="QUOTE"
>"pop3"</SPAN
>).
<TT
CLASS="FUNCTION"
>auth_changepwd</TT
> should return 0 if the password was
changed succesfully, a negative value if <TT
CLASS="LITERAL"
>user</TT
> is invalid
(the next authentication module will be tried), or a positive value if
the password change request failed (no more modules will be tried).</P
><P
><TT
CLASS="FUNCTION"
>auth_enumerate</TT
> points to a function that enumerates
the list of all login IDs known to the authentication module.
The first argument <TT
CLASS="FUNCTION"
>auth_enumerate</TT
> is a callback
function. <TT
CLASS="FUNCTION"
>auth_enumerate</TT
> invokes the callback
function once for each login ID, supplying the login ID, the userid,
groupid, home directory and maildir as arguments.
The last argument to the callback function is passed through from the
second argument to <TT
CLASS="FUNCTION"
>auth_enumerate</TT
>.</P
><P
>After enumerating all login IDs <TT
CLASS="FUNCTION"
>auth_enumerate</TT
> calls
the callback function one last time, with a NULL pointer for the login ID,
then returns.  If an error is encountered while enumerating the login IDs,
<TT
CLASS="FUNCTION"
>auth_enumerate</TT
> terminates without invoking
the callback function with a NULL login ID.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN533"
>FILES</A
></H2
><P
><TT
CLASS="FILENAME"
> @authdaemonrc@</TT
> - <B
CLASS="COMMAND"
>authdaemond</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @authldaprc@</TT
> - <B
CLASS="COMMAND"
>authldap</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @authmysqlrc@</TT
> - <B
CLASS="COMMAND"
>authmysql</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @authpgsqlrc@</TT
> - <B
CLASS="COMMAND"
>authpgsql</B
> configuration file</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN547"
>SEE ALSO</A
></H2
><P
><A
HREF="courier.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>courier</SPAN
>(8)</SPAN
></A
>,
 
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
></P
></DIV
></DIV
></BODY
></HTML
>