File: authlib.html.in

package info (click to toggle)
courier 0.47-4sarge5
links: PTS
area: main
in suites: sarge
size: 32,680 kB
ctags: 12,265
sloc: ansic: 164,045; cpp: 23,863; sh: 19,569; perl: 7,225; makefile: 4,192; yacc: 316; sed: 16
file content (1972 lines) | stat: -rw-r--r-- 38,031 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML
><HEAD
><link rel='stylesheet' type='text/css' href='manpage.css'>
  <!-- $Id: authlib.sgml,v 1.2 2004/07/12 22:55:59 mrsam Exp $ -->
  <!-- Copyright 1998 - 2001 Double Precision, Inc.  See COPYING for -->
  <!-- distribution information. -->
<meta name="MSSmartTagsPreventParsing" content="TRUE">
<link rel="icon" href="icon.gif" type="image/gif" />
<TITLE
>authlib</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AUTHLIB"
></A
>authlib</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN10"
></A
><H2
>Name</H2
>authlib&nbsp;--&nbsp;Courier Authentication Library</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN13"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>authpam</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authpwd</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authshadow</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authuserdb</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authvchkpw</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authcram</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authmysql</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authpgsql</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authldap</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authdaemon</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authcustom</B
> {<VAR
CLASS="REPLACEABLE"
>command</VAR
>} [<VAR
CLASS="REPLACEABLE"
>arg</VAR
>...]</P
><P
><B
CLASS="COMMAND"
>authdaemond</B
> [start | stop | restart]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN86"
></A
><H2
>DESCRIPTION</H2
><P
>This library is used for two purposes:</P
><P
>1. Read an E-mail address that is supposed to be for a local account.
Determine the local account's home directory, and system userid and
groupid.</P
><P
>2. Read a login id 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 implementations,
that may be selected at runtime.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>authdaemon</TT
></DT
><DD
><P
>authenticates through a background daemon proxy.
This is now the installation default.
Unless otherwise specified, the <TT
CLASS="LITERAL"
>authdaemon</TT
>
module will always be installed.
<TT
CLASS="LITERAL"
>authdaemon</TT
> is installed instead of the other
authentication modules.
Those modules are instead compiled into a separate executable program,
<TT
CLASS="LITERAL"
>authdaemond</TT
> that is initialized at system start, and runs
in the background.
The <TT
CLASS="LITERAL"
>authdaemon</TT
> authentication module forwards the
authentication requests to <TT
CLASS="LITERAL"
>authdaemond</TT
>, which forwards
the authentication request to the real authentication module, and the
result of the request is eventually returned back to the application.
Because the real authentication process runs as a persistent background
process, it is possible for the authentication process to open and hold
permanent connections to the back-end authentication database (be it an
LDAP directory, a MySQL or a PostgreSQL server), instead of connecting
and disconnecting for every request.
Obviously, this tremendously improves the authentication performance.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authpam</TT
></DT
><DD
><P
>authenticates using the system's PAM library
(pluggable authentication module).
This is, essentially, a way to use existing PAM modules for authentication
functionality.
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
></DD
><DT
><TT
CLASS="LITERAL"
>authpwd</TT
></DT
><DD
><P
>authenticates from the
<TT
CLASS="FILENAME"
>/etc/passwd</TT
> file.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authshadow</TT
></DT
><DD
><P
>like <TT
CLASS="LITERAL"
>authpwd</TT
> except passwords
are read from <TT
CLASS="FILENAME"
>/etc/shadow</TT
>.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authuserdb</TT
></DT
><DD
><P
>authenticates against the
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
> database.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authvchkpw</TT
></DT
><DD
><P
>supports existing <TT
CLASS="LITERAL"
>vpopmail/vchkpw</TT
>
virtual domains.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authcram</TT
></DT
><DD
><P
>authenticates against the
<A
HREF="userdb.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>userdb</SPAN
>(8)</SPAN
></A
> database using the
challenge/response authentication mechanism (CRAM), instead of the traditional
userid/password.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authmysql</TT
></DT
><DD
><P
>authenticates against a list of mail accounts
stored in an external 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 list table.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authpgsql</TT
></DT
><DD
><P
>authenticates against a list of mail accounts
stored in an external 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 list table.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authldap</TT
></DT
><DD
><P
>authenticates against a list of mail accounts
stored in an external LDAP directory.
The <TT
CLASS="FILENAME"
>@authldaprc@</TT
> configuration file defines the
particular details regarding the LDAP directory layout.</P
></DD
><DT
><TT
CLASS="LITERAL"
>authcustom</TT
></DT
><DD
><P
>this is a stub 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 added.</P
></DD
></DL
></DIV
><P
>This is a complete list of available authentication modules.
The actual installed authentication modules are determined by the resources
on the server.
For example, the <TT
CLASS="LITERAL"
>authmysql</TT
> authentication module will
be installed only if the system provides MySQL support libraries.</P
><DIV
CLASS="REFSECT2"
><A
NAME="AEN171"
></A
><H3
><TT
CLASS="LITERAL"
>authdaemon</TT
> authentication module</H3
><P
>The following command must be executed from the system startup script
in order for the <TT
CLASS="LITERAL"
>authdaemon</TT
> module to work (and remember
that <TT
CLASS="LITERAL"
>authdaemon</TT
> is installed by default:</P
><A
NAME="AEN177"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN178"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>@libexecdir@/authlib/authdaemond start</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
></BLOCKQUOTE
><P
>"<B
CLASS="COMMAND"
>authdaemond stop</B
>" should also be added to the system
shutdown script.</P
><P
>The <TT
CLASS="FILENAME"
>@authdaemonvar@</TT
> subdirectory must be created in
advance.
This directory will have the filesystem socket used for
interprocess communication between
<TT
CLASS="LITERAL"
>authdaemon</TT
> and <TT
CLASS="LITERAL"
>authdaemond</TT
>.
It goes without saying that
the underlying filesystem for <TT
CLASS="FILENAME"
>@authdaemonvar@</TT
> must support
filesystem domain sockets. This pretty much excludes all network filesystems,
so this directory should reside on a local disk.</P
><P
><TT
CLASS="FILENAME"
>@authdaemonvar@</TT
>
MUST NOT HAVE any world-readable, executable
or writable permissions!  Under NO circumstances should this be allowed to
happen.  The exact permissions and ownership of
<TT
CLASS="FILENAME"
>@authdaemonvar@</TT
> varies.  For the standalone versions of
<SPAN
CLASS="PRODUCTNAME"
>Courier-IMAP</SPAN
> and
<SPAN
CLASS="PRODUCTNAME"
>SqWebMail</SPAN
>,
<TT
CLASS="FILENAME"
>@authdaemonvar@</TT
> should be owned by root, and have no
group or
world permissions.
For the <SPAN
CLASS="PRODUCTNAME"
>Courier mail server</SPAN
>,
<TT
CLASS="FILENAME"
>@authdaemonvar@</TT
>
should be owned by the userid that Courier is installed under, and it must be
readable and writable by the Courier user and group (but no world
permissions).</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN195"
></A
><H3
>Configuring <TT
CLASS="LITERAL"
>authdaemond</TT
></H3
><P
>The <TT
CLASS="FILENAME"
>@authdaemonrc@</TT
> configuration file sets several
operational parameters for the <TT
CLASS="FILENAME"
>authdaemond</TT
> process. See
the comments in the
default file installed for more information. Currently,
<TT
CLASS="FILENAME"
>@authdaemonrc@</TT
> sets two parameters: number of daemon
processes,
and authentication modules/process that will be used.</P
><P
>Although <TT
CLASS="FILENAME"
>authdaemond</TT
> might include several
authentication modules, not all of them may be used.
This makes it possible to install the same
<B
CLASS="COMMAND"
>authdaemond</B
> build on multiple
systems with different authentication needs. The default module list specified
in <TT
CLASS="FILENAME"
>@authdaemonrc@</TT
> would be a list of all the available
authentication modules.</P
><P
><B
CLASS="COMMAND"
>@libexecdir@/authlib/authdaemond</B
> is actually a very short
shell script that executes the real <B
CLASS="COMMAND"
>authdaemond</B
> program.
The available programs are <B
CLASS="COMMAND"
>authdaemond.plain</B
>,
<B
CLASS="COMMAND"
>authdaemond.ldap</B
>,
<B
CLASS="COMMAND"
>authdaemond.mysql</B
>, and
<B
CLASS="COMMAND"
>authdaemond.pgsql</B
>.
The "plain" program contains all the authentication modules except for
<TT
CLASS="LITERAL"
>authldap</TT
>,
<TT
CLASS="LITERAL"
>authmysql</TT
>, and
<TT
CLASS="LITERAL"
>authpgsql</TT
>.
The "ldap" program includes all the authentication modules in "plain",
plus <TT
CLASS="LITERAL"
>authldap</TT
>
Ditto for the "mysql" and "pgsql" processes.</P
><P
>This arrangement allows convenient creation of pre-configured binary
packages.
The <B
CLASS="COMMAND"
>authdaemond</B
> shell script runs
<B
CLASS="COMMAND"
>authdaemond.plain</B
> only if none of the other processes
are installed on the system.
First, it checks if 
<B
CLASS="COMMAND"
>authdaemond.ldap</B
>,
<B
CLASS="COMMAND"
>authdaemond.mysql</B
>, or
<B
CLASS="COMMAND"
>authdaemond.pgsql</B
> is installed.
If not, <B
CLASS="COMMAND"
>authdaemond.plain</B
> is brought up.
This makes it possible to prepare a basic binary package that provides
only basic authentication services and does not require either LDAP,
MySQL, or PostgreSQL runtime support on the server.
If either of these authentication requirements are needed, a separate
binary sub-package will load the appropriate <B
CLASS="COMMAND"
>authdaemond</B
>
process.</P
><P
>Note that it is not possible to use both LDAP and MySQL, for example,
authentication at the same time.
That's because their support is in different
<B
CLASS="COMMAND"
>authdaemond</B
> processes, and only one
<B
CLASS="COMMAND"
>authdaemond</B
> process can run at the same time.
If both (or all three non-plain processes) are installed, the
<B
CLASS="COMMAND"
>authdaemond</B
> script picks either the first one it finds,
or whatever is explicitly specified in the
<TT
CLASS="FILENAME"
>@authdaemonrc@</TT
> configuration file.</P
><P
>The number of <B
CLASS="COMMAND"
>authdaemond</B
> processes is also set in this
configuration file.  The more processes that are started, the more
authentication requests can be handled.  If
<B
CLASS="COMMAND"
>authdaemon</B
> does not
receive an answer within a moderate amount of time, it will declare an
authentication failure, and abort. Try increasing the number of processes if
you start seeing random authentication failures.  However, that should only be
used as a stop-gap measure.  If the default number of
<B
CLASS="COMMAND"
>authdaemond</B
>
processes proves to be insufficient, it is far more likely that more resources
are needed for the server: more RAM, a faster disk, or a faster CPU, at least
in the humble opinion of the author. Increasing the number of processes should
only be used as a stop-gap measure, until a more thorough analysis on the
bottleneck can be made.</P
><A
NAME="AEN234"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN235"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>@libexecdir@/authlib/authdaemond restart</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
></BLOCKQUOTE
><P
>Run the above command after making any changes to
<TT
CLASS="FILENAME"
>@authdaemonrc@</TT
>.
"<B
CLASS="COMMAND"
>authdaemond restart</B
>"
is required for any changes to take effect.</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN240"
></A
><H2
>AUTHENTICATION PROTOCOL</H2
><P
>The rest of this documentation describes the internal protocol used by
this authentication library.
It is only of interest to developers who wish to extend the authentication
library to support a custom authentication module,
or a derived extension to an existing module.</P
><P
>The original implementation of this authentication library used small,
self-contained, binary programs, named for their authentication module:
<TT
CLASS="LITERAL"
>authldap</TT
>,
<TT
CLASS="LITERAL"
>authpam</TT
>, and others.
Later, the <TT
CLASS="LITERAL"
>authdaemon</TT
> module came about, which wrapped
the other authentication modules into a separate background daemon
process, which communicated with the <TT
CLASS="LITERAL"
>authdaemon</TT
> module.
The <TT
CLASS="LITERAL"
>authdaemon</TT
> module is now always enabled by default,
but it is still possible to build and install each authentication module
as a self-contained binary program.
Note, however, that applications such as
<A
HREF="http://www.courier-mta.org/sqwebmail/"
TARGET="_top"
><TT
CLASS="APPLICATION"
>SqWebMail</TT
></A
>,
and
<A
HREF="http://www.courier-mta.org/"
TARGET="_top"
><TT
CLASS="APPLICATION"
>Courier</TT
></A
>
link directly with all the authentication modules, and will not use external
modules for authentication.</P
><P
><TT
CLASS="LITERAL"
>authdaemon</TT
> came about as a direct result of technical
issues that prevented <TT
CLASS="APPLICATION"
>SqWebMail</TT
> and
<TT
CLASS="APPLICATION"
>Courier</TT
> from using external binary modules.
<TT
CLASS="LITERAL"
>authdaemond</TT
> is really nothing more than
a simple application that
links directly with the authentication modules, and talks to the
<TT
CLASS="LITERAL"
>authdaemon</TT
> authentication module that follows this
authentication protocol.</P
><DIV
CLASS="REFSECT2"
><A
NAME="AEN259"
></A
><H3
>Stand-alone authentication modules</H3
><P
>This section describes the authentication protocol for self-contained
authentication modules.
Although the default configuration no longer uses self-contained modules,
the stand-alone protocol serves as a foundation for the protocol used by
authentication modules as part of the <TT
CLASS="LITERAL"
>authdaemond</TT
>
authentication process, or when they are linked directly with the application
that uses this authentication library.</P
><P
>Here's the typical way that stand-alone authentication modules are used:</P
><P
>1. A list of authentication modules are read from a configuration file.
Multiple authentication modules could be available, but not all of them
are required in most situations.</P
><P
>2. The application executes the following command:</P
><A
NAME="AEN266"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN267"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>LOGIN AUTHMODULE1 AUTHMODULE2 ... APP</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
></BLOCKQUOTE
><P
><TT
CLASS="LITERAL"
>LOGIN</TT
> is a full pathname to an application that reads
the authentication information, such as the userid and a password.
Arguments to <TT
CLASS="LITERAL"
>LOGIN</TT
> are full pathnames to each
authentication module (if there are more than one), followed by a full
pathname to the main application.</P
><P
>3. <TT
CLASS="LITERAL"
>LOGIN</TT
> reads the userid and password, then runs
the program specified by its first argument, which is the first
authentication module.
The remaining arguments are passed to the new process.
The mechanism by which the authentication information is passed to the
authentication module is described later.</P
><P
>4. Each authentication module reads the authentication information, and
determines if the previous authentication module succesfully processed
the authentication request.
If not, the module attempts to authenticate it itself.
In any event, the module runs the next program specified by its first
argument, and the remaining arguments are passed along to the next
program.
If any previous authentication module succesfully processed the
authentication request, the next program is run immediately without
any further processing.</P
><P
>5. Eventually, <TT
CLASS="LITERAL"
>APP</TT
> runs,
<TT
CLASS="LITERAL"
>APP</TT
> reads the authentication information and
determines whether any authentication module managed to succesfully
process the authentication request.
If so, <TT
CLASS="LITERAL"
>APP</TT
> runs normally.
Otherwise, <TT
CLASS="LITERAL"
>APP</TT
> runs <TT
CLASS="LITERAL"
>LOGIN</TT
> with its
original arguments in order to return an error message ("Password invalid",
or something similar) and read the next authentication request.</P
><P
>Daisy-chaining authentication modules, in this fashion, makes it possible
to have hybrid systems that use multiple authentication modules.
Example: using <TT
CLASS="LITERAL"
>authpam</TT
> to authenticate system accounts,
and <TT
CLASS="LITERAL"
>authmysql</TT
> to authentication virtual mailboxes without
a corresponding system account.</P
><P
>Here's a more detailed description of the overall process:</P
><DIV
CLASS="REFSECT3"
><A
NAME="AEN285"
></A
><H4
>The <TT
CLASS="LITERAL"
>LOGIN</TT
> process</H4
><P
>The <TT
CLASS="LITERAL"
>LOGIN</TT
> process checks if the <TT
CLASS="LITERAL"
>AUTHARGC</TT
>
environment variable is set.  If not, this is the first time the
<TT
CLASS="LITERAL"
>LOGIN</TT
> process comes up, and <TT
CLASS="LITERAL"
>LOGIN</TT
>
displays the initial login prompt.  Additionally, the command line arguments
to <TT
CLASS="LITERAL"
>LOGIN</TT
> are 
literal copied to the <TT
CLASS="LITERAL"
>AUTHARGC</TT
>
and <TT
CLASS="LITERAL"
>AUTHARGVn</TT
> environment variables.
That is: the number of command line arguments is saved in
<TT
CLASS="LITERAL"
>AUTHARGC</TT
>; the zeroth command line argument is saved in
<TT
CLASS="LITERAL"
>AUTHARGV0</TT
>; the remaining command line arguments are saved
in <TT
CLASS="LITERAL"
>AUTHARGV1</TT
>, <TT
CLASS="LITERAL"
>AUTHARGV2</TT
>,
and so on.</P
><P
>After obtaining the authentication information (such as the userid and
password), <TT
CLASS="LITERAL"
>LOGIN</TT
> creates a pipe, and arranges for the
output end of the pipe to be located on file descriptor #3.
The <TT
CLASS="LITERAL"
>LOGIN</TT
> process forks; the original process then
executes the first authentication module, in the manner described earlier;
the child process writes the authentication record to the pipe, then
terminates.</P
><P
>The authentication record is a chunk of data in the following
format:</P
><A
NAME="AEN304"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
>	    <SAMP
CLASS="COMPUTEROUTPUT"
><VAR
CLASS="REPLACEABLE"
>SERVICE</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
><VAR
CLASS="REPLACEABLE"
>AUTHTYPE</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
><VAR
CLASS="REPLACEABLE"
>AUTHDATA</VAR
></SAMP
>
	  </P
></BLOCKQUOTE
><P
>Each occurence of <SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
> represents an ASCII linefeed
character (#10).
"<TT
CLASS="LITERAL"
>SERVICE</TT
>" identifies the service that originates the
authentication request, such as "imap", or "webmail".
Authentication module may use this identifier, or ignore it.</P
><P
>"<TT
CLASS="LITERAL"
>AUTHTYPE</TT
>" identifies the format of the authentication
request.
Everything after the second <SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
> is an opaque blob
of data, whose format is determined by <TT
CLASS="LITERAL"
>AUTHTYPE</TT
>.</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
>There's a theoretical upper limit on the maximum size of the authentication
record. It is high enough not to matter in most situations
(the total number of characters allowed cannot be
more than 8189 characters on a typical GNU/Linux system).</P
></TD
></TR
></TABLE
></DIV
><P
>The following <TT
CLASS="LITERAL"
>AUTHTYPE</TT
> formats are currently defined:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>login</TT
></DT
><DD
><P
>A typical userid/password authentication request. <TT
CLASS="LITERAL"
>AUTHDATA</TT
> contains the following data:
<VAR
CLASS="REPLACEABLE"
>userid</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
><VAR
CLASS="REPLACEABLE"
>password</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
>.</P
></DD
><DT
><TT
CLASS="LITERAL"
>cram-md5</TT
></DT
><DD
><P
>Specifies the <TT
CLASS="LITERAL"
>CRAM-MD5</TT
>
authentication request.
<TT
CLASS="LITERAL"
>AUTHDATA</TT
> contains the following data:
<VAR
CLASS="REPLACEABLE"
>challenge</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
><VAR
CLASS="REPLACEABLE"
>response</VAR
><SPAN
CLASS="TOKEN"
>&#60;NEWLINE&#62;</SPAN
>.
The "<SPAN
CLASS="TOKEN"
>challenge</SPAN
>" and "<SPAN
CLASS="TOKEN"
>response</SPAN
>" strings are
base64-encoded.</P
></DD
><DT
><TT
CLASS="LITERAL"
>cram-sha1</TT
></DT
><DD
><P
>Specifies the <TT
CLASS="LITERAL"
>CRAM-SHA1</TT
>
authentication request, instead of CRAM-MD5, and uses the same format for
<TT
CLASS="LITERAL"
>AUTHDATA</TT
>.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT3"
><A
NAME="AEN354"
></A
><H4
>The authentication module</H4
><P
>The first thing an authentication module does is check if the environment
variable <TT
CLASS="LITERAL"
>AUTHENTICATED</TT
> is set to a non-empty string.
If so, it means that a previous authentication module has handled the
authentication request, so this module simply runs the next program,
specified by the first argument to this authentication module.</P
><P
>Otherwise, the authentication module reads the authentication record from
file descriptor #3, and determines whether it wants to try this
authentication record.
If not, the module creates a new pipe, arranges the output of the pipe
to be on file descriptor #3, forks, the parent process runs the next
authentication module, and the child process writes the authentication
record to the pipe, then exits.</P
><P
>There are two ways to handle an authentication request:
1) Use the <TT
CLASS="LITERAL"
>AUTHARGC</TT
> and <TT
CLASS="LITERAL"
>AUTHARGVn</TT
>
variables to restart the entire authentication process - this is used
in the event it is determined that the authentication request must be
failed, or 2) run the next daisy-changed module, in the manner described
previously, when it is determined that another authentication module can
attempt to try to handle this request.</P
><P
>The following action occurs when
the authentication module succesfully validates an authentication request:</P
><P
>1. The authenticated login ID is saved in the <TT
CLASS="LITERAL"
>AUTHENTICATED</TT
>
environment variable.</P
><P
>2. The process's userid and groupid are reset to the corresponding
userid and groupid of the authenticated login id, and the current directory
is set to the process's defined home directory.</P
><P
>3. Some additional environment variables may also be initialized:
<TT
CLASS="LITERAL"
>AUTHFULLNAME</TT
> - the login ID's full name;
<TT
CLASS="LITERAL"
>MAILDIR</TT
> - the login ID's default maildir mailbox;
<TT
CLASS="LITERAL"
>MAILDIRQUOTA</TT
> - the requested maildir quota.</P
></DIV
><DIV
CLASS="REFSECT3"
><A
NAME="AEN370"
></A
><H4
>The application process</H4
><P
>Eventually, <TT
CLASS="LITERAL"
>APP</TT
> runs.
The process closes file descriptor #3 (if it's open, and ignores the error
if file descriptor #3 does not exist).
If the <TT
CLASS="LITERAL"
>AUTHENTICATED</TT
> environment variable is set,
it must mean that an authentication module was able to handle this
authentication request, so <TT
CLASS="LITERAL"
>APP</TT
> starts up and runs normally.
Otherwise the
original command is reconstructed from the
<TT
CLASS="LITERAL"
>AUTHARGC</TT
> and <TT
CLASS="LITERAL"
>AUTHARGVn</TT
>
variables, and the initial login process runs again.</P
></DIV
><DIV
CLASS="REFSECT3"
><A
NAME="AEN378"
></A
><H4
>Library functions</H4
><P
>This authentication library provides several convenient functions which
can be used to quickly create a compliant login process, and its
corresponding application.
The login process should be structured as follows:</P
><A
NAME="AEN381"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN382"
></A
><P
><B
>Example 1. A sample LOGIN process</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int main(int argc, char **argv)
{
   if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT))
   {
      /* Print initial greeting here */
   }
   else
   {
      /* Error: invalid userid/password */
   }

   /* read userid and password */

   authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA);
}</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
>The <TT
CLASS="FUNCTION"
>authmoduser</TT
> function takes care of copying
the command line parameters to their corresponding environment variables,
and checking whether or not this is the initial time this process runs,
or if it is running again after a failed authentication process.
<TT
CLASS="LITERAL"
>TIMEOUT</TT
> specifies the absolute login timeout,
<TT
CLASS="FUNCTION"
>authmoduser</TT
> quietly terminates the process if it
runs due to a failed authentication request and at least
<TT
CLASS="LITERAL"
>TIMEOUT</TT
> seconds have elapsed since the first time
<TT
CLASS="FUNCTION"
>authmoduser</TT
> was run.
<TT
CLASS="LITERAL"
>ERR_TIMEOUT</TT
> specifies the number of seconds that
<TT
CLASS="FUNCTION"
>authmoduser</TT
> will sleep after a failed
authentication request.</P
><P
>The <TT
CLASS="LITERAL"
>SERVICE</TT
>, <TT
CLASS="LITERAL"
>AUTHTYPE</TT
>, and
<TT
CLASS="LITERAL"
>AUTHDATA</TT
> arguments to <TT
CLASS="FUNCTION"
>authmod</TT
>
are null-terminated character strings that form the authentication request.
<TT
CLASS="FUNCTION"
>authmod</TT
> takes care of setting up the pipe to the
first authentication module, and runs it.</P
><P
>The application process is even simpler:</P
><A
NAME="AEN400"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN401"
></A
><P
><B
>Example 2. A sample APP process</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int main(int argc, char **argv)
{
const char *loginid=authmodclient();

   /* Application begins normally */

}</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
>The <TT
CLASS="FUNCTION"
>authmodclient</TT
> function returns the authenticated
login ID.
If the authentication request failed, <TT
CLASS="FUNCTION"
>authmodclient</TT
>
reruns the original login process, and doesn't return.</P
></DIV
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN407"
></A
><H3
>Inside an authentication modules</H3
><P
>An authentication module needs to define the following structure:</P
><A
NAME="AEN410"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN411"
></A
><P
><B
>Example 3. struct authstaticinfo</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct authstaticinfo {
        const char *auth_name;
        char * (*auth_func)(const char *, const char *, char *, int,
                        void (*)(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 */
        } ;</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
><TT
CLASS="FUNCTION"
>auth_func</TT
> points to a function that handles the
authentication request.
If succesful, <TT
CLASS="FUNCTION"
>auth_func</TT
> is responsible for resetting
the userid and groupid, changing to the authentication account's home
directory, and setting up the necessary environment variables.
The first three arguments to <TT
CLASS="FUNCTION"
>auth_func</TT
> will be
<TT
CLASS="LITERAL"
>SERVICE</TT
>, <TT
CLASS="LITERAL"
>AUTHTYPE</TT
>, and
<TT
CLASS="LITERAL"
>AUTHDATA</TT
>.
The next argument is a boolean flag which is non-zero if the authentication
code is being called in the context of a stand-alone authentication module,
or zero if the authentication code is called directly by an application.
The fifth argument points is a callback function pointer, which
may be NULL.
If it's not null, <TT
CLASS="FUNCTION"
>auth_func</TT
> should not reset
the userid, groupid, or the home directory of this process, but
should instead initialize the <CODE
CLASS="STRUCTNAME"
>authinfo</CODE
>
structure, which is defined as follows:</P
><A
NAME="AEN423"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN424"
></A
><P
><B
>Example 4. struct authinfo</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct authinfo {
        const char *sysusername;
        const uid_t *sysuserid;
        gid_t sysgroupid;
        const char *homedir;

        const char *address;	/* The E-mail address */
        const char *fullname;	/* gecos, etc... */
        const char *maildir;
        const char *quota;

        const char *passwd;
        const char *clearpasswd;        /* For authldap */

        unsigned staticindex;   /* When statically-linked functions are
                                ** called, this holds the index of the
                                ** authentication module in authstaticlist */

        } ;</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
>The
<CODE
CLASS="STRUCTFIELD"
>passwd</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>clearpasswd</CODE
>, and
<CODE
CLASS="STRUCTFIELD"
>staticindex</CODE
> fields are not used by
<TT
CLASS="FUNCTION"
>auth_func</TT
>.
Either <CODE
CLASS="STRUCTFIELD"
>sysusername</CODE
> or
<CODE
CLASS="STRUCTFIELD"
>sysuserid</CODE
> must be a non-NULL pointer.
<CODE
CLASS="STRUCTFIELD"
>sysuserid</CODE
> specifies an explicit userid,
otherwise <CODE
CLASS="STRUCTFIELD"
>sysusername</CODE
> is looked up in the
password file.</P
><P
>The last argument to <TT
CLASS="FUNCTION"
>auth_func</TT
> is an opaque
pointer that gets passed as the second argument to the callback
function.</P
><P
><TT
CLASS="FUNCTION"
>auth_func</TT
>
should return a pointer to the authenticated loginid, in dynamic memory
(the memory should be <TT
CLASS="FUNCTION"
>free()</TT
>ed after user.
A NULL return indicates an authentication failure.
The authentication module should set <SPAN
CLASS="SYMBOL"
>errno</SPAN
> to
<TT
CLASS="LITERAL"
>EPERM</TT
> in the event that it the next authentication module
should have a chance to process the authentication request, or use
any other <SPAN
CLASS="SYMBOL"
>errno</SPAN
> value to immediately fail the authentication
request, and rerun the original login process.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN444"
></A
><H3
>Linked authentication modules</H3
><P
>The <TT
CLASS="FUNCTION"
>auth_prefunc</TT
>,
<TT
CLASS="FUNCTION"
>auth_cleanupfunc</TT
>,
and <TT
CLASS="FUNCTION"
>auth_changepwd</TT
> functions are not used by
stand-alone modules, but when the authentication module is directly
linked with an application.</P
><P
><TT
CLASS="FUNCTION"
>auth_prefunc</TT
> verifies that the requested userid
exists.
No passwords are validated, the first two arguments to
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> are the userid, and
<TT
CLASS="LITERAL"
>SERVICE</TT
>.
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> should initialize an
<CODE
CLASS="STRUCTNAME"
>authinfo</CODE
> structure, and run the
callback function, the third argument to
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
>.
The callback function receives the fourth argument to
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> as an opaque pointer.</P
><P
><TT
CLASS="FUNCTION"
>auth_prefunc</TT
> should come back with the callback
function's return code, if the requested userid was found.
Otherwise,
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> should return a non-zero integer.
A positive integer should be return in the event that this authentication
request should be stopped, and a negative itneger if another authentication
module can be tried.
An application that links against this authentication library will run
each configured authentication module's
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
>,
until some module is able to process the requested userid, or until
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> comes back with a non-zero positive
return code.</P
><P
><TT
CLASS="FUNCTION"
>auth_func</TT
> or
<TT
CLASS="FUNCTION"
>auth_prefunc</TT
> might allocate some internal resources,
which should be freed by calling
<TT
CLASS="FUNCTION"
>auth_cleanupfunc</TT
>.</P
><P
>The <TT
CLASS="FUNCTION"
>auth_changepwd</TT
>
function is called to implement the change password functionality.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN469"
></A
><H3
>Other authentication library function</H3
><P
>This authentication library contains several functions and macros that
can be helpful in building authentication modules.</P
><A
NAME="AEN472"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN473"
></A
><P
><B
>Example 5. Turning <TT
CLASS="FUNCTION"
>auth_func</TT
> into a module</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define MODULE  auth_func
#include        "mod.h"</PRE
></TD
></TR
></TABLE
></DIV
></BLOCKQUOTE
><P
><TT
CLASS="FILENAME"
>mod.h</TT
> contains template code that reads an authentication
request from the previous authentication module, call
<TT
CLASS="FUNCTION"
>auth_func</TT
>, in such a manner, and appropriately
run the next module in the authentication chain.</P
><P
>The <TT
CLASS="FILENAME"
>auth.h</TT
> header file also declares several useful
functions that authentication-related code may find convenient.</P
><DIV
CLASS="REFSECT3"
><A
NAME="AEN482"
></A
><H4
>Building <B
CLASS="COMMAND"
>authdaemond</B
></H4
><P
>This authentication library builds alternate versions of the
<B
CLASS="COMMAND"
>authdaemond</B
> background process.
Some authentication modules have dependencies on external libraries,
such as
<TT
CLASS="LITERAL"
>authldap</TT
>,
<TT
CLASS="LITERAL"
>authmysql</TT
>, and
<TT
CLASS="LITERAL"
>authpgsql</TT
>.
The authentication library prepares separate versions of
<B
CLASS="COMMAND"
>authdaemond</B
> for each authentication module with a
dependency.
Each one of these <B
CLASS="COMMAND"
>authdaemond</B
> versions will also include
all other authentication modules that do not have dependencies.</P
><P
>The authentication module configuration for each
<B
CLASS="COMMAND"
>authdaemond</B
>
is set in the
<TT
CLASS="FILENAME"
>authdaemond.versions</TT
> file.
A new authentication module will have to be added to
<TT
CLASS="FILENAME"
>authdaemond.versions</TT
> (potentially creating another
<B
CLASS="COMMAND"
>authdaemond</B
> build).
The <TT
CLASS="FILENAME"
>configure</TT
> script must be run after making any
changes to <TT
CLASS="FILENAME"
>authdaemond.versions</TT
>.</P
></DIV
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN499"
></A
><H2
>FILES</H2
><P
><TT
CLASS="FILENAME"
> @sysconfdir@/authmodulelist</TT
> - list of authentication
modules read by applications that directly link with
<TT
CLASS="FILENAME"
>authlib</TT
></P
><P
><TT
CLASS="FILENAME"
> @sysconfdir@/authdaemonrc</TT
> - <B
CLASS="COMMAND"
>authdaemond</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @sysconfdir@/authldaprc</TT
> - <B
CLASS="COMMAND"
>authldap</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @sysconfdir@/authmysqlrc</TT
> - <B
CLASS="COMMAND"
>authmysql</B
> configuration file</P
><P
><TT
CLASS="FILENAME"
> @sysconfdir@/authpgsqlrc</TT
> - <B
CLASS="COMMAND"
>authpgsql</B
> configuration file</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN516"
></A
><H2
>SEE ALSO</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
></BODY
></HTML
>