Courier Authentication Library

This modules obtains account information and passwords from the /etc/passwd file.

This module is a version of the authpwd module that reads passwords from /etc/shadow (the C library's getsp() functions).

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 /etc/passwd file, since PAM functionality is limited to validating account passwords.

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

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

This is a generic plug-in module that runs an external script, or a program, in response to authentication requests.

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.

The location of the external program is set by the --with-pipeprog configure option, which defaults to /usr/local/etc/authlib/authProg. A sample program is included in the courier-authlib source.

authpipe uses the same protocol as authdaemon clients use to communicate with authdaemond (with the exception of optional authentication metadata whose forwarding is not implemented at this time).

There are four possible requests: PRE, AUTH, PASSWD and ENUMERATE. Apart from AUTH, each request is a single line terminated by newline.

This module uses a GDBM or a DB-based userdb(8) database. This module also incorporates userdb-based challenge-response authentication implementation that was done by a separate authcram module in previous versions of the Courier authentication library.

/usr/local/etc/authlib/userdb is a plain file that can be edited with any text editor. The file contains a list of account names, and their pertinent information. /usr/local/etc/authlib/userdb may alternatively be a directory containing plain text files, which are effectively concatenated together to form the actual list of accounts. The makeuserdb script compiles the account information into a GDBM or DB database file, which can be quickly looked up.

/usr/local/etc/authlib/userdb is loosely equivalent in function to /etc/passwd and /etc/shadow, and contain analous information: account name, its numeric userid and groupid, home directory, and passwords. /usr/local/etc/authlib/userdb also contains additional Courier-specific metadata, such as account quotas and other account-specific settings. /usr/local/etc/authlib/userdb files can also be maintained by custom-written Perl scripts, instead of being edited by hand.

/usr/local/etc/authlib/userdb 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. /usr/local/etc/authlib/userdb can also be used to completely supersede /etc/passwd. With many accounts it can be quite a drain to have to continuously linearly scan /etc/passwd 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 userdb(8), for more information.

# cp /dev/null /usr/local/etc/authlib/userdb
# chmod 700 /usr/local/etc/authlib/userdb

vmail   uid=1012|gid=1012|home=/home/vmail|systempw=*
1012=   vmail

$ chmod 700 /usr/local/etc/authlib/userdb

# su vmail
$ cd ~vmail
$ mkdir john-example
$ maildirmake john-example/Maildir
$ exit
#

# userdb "john@example.com" set home=/home/vmail/john-example \
                                uid=UUU gid=GGG

# userdbpw | userdb "john@example.com" set imappw

# makeuserdb

# mkdir /usr/local/etc/authlib/userdb
# chmod 700 /usr/local/etc/authlib/userdb

# su - vmail
$ cd ~vmail
$ mkdir -p domains/example-com
$ mkdir domains/example-com/john
$ maildirmake domains/example-com/john
$ exit

$ userdb "example-com/john@example.com" set \
             home=/home/vmail/domains/example-com/john \
             uid=UUU gid=GGG

$ userdbpw | userdb "example-com/john@example.com" set imappw

$ makeuserdb

This module reads the list of mail accounts and passwords from a table in a MySQL/MariaDB database. The /usr/local/etc/authlib/authmysqlrc configuration file defines the particular details regarding the database and the schema of the mail account table.

This module reads the list of mail accounts and passwords from a table in a PostgreSQL database. The /usr/local/etc/authlib/authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account table.

This module reads the list of mail accounts and passwords from a table in a SQLite database file. The /usr/local/etc/authlib/authsqliterc configuration file defines the particular details regarding the SQLite database file and the schema of the mail account table.

This module reads the list of mail accounts and passwords from an LDAP directory. The /usr/local/etc/authlib/authldaprc configuration file defines the particular details regarding the LDAP directory layout.

A suggested LDAP schema can be found in the files authldap.schema and authldap.ldif, which is included in Courier authentication library's source code, and may be installed on your system.

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.

The authentication library has a facility for keep arbitrary “name=value”-type settings, called “options”, for individual accounts. This feature is only available with userdb, LDAP, MySQL, SQLite and PostgresSQL modules. Individual account options are not supported with system-based authentication modules (password/shadow files, or PAM).

See auth_generic_meta(3) 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.

Account options are specified via the authentication modules in the following manner:

The following options are recognized by the various Courier packages:

The authtest command may be used to verify that the authentication library is working:

authtest userid
authtest userid password
authtest userid password newpassword
authenumerate

Running authtest with one argument should display the selected account's home directory, userid, groupid, and other related data. The second argument to authtest, if supplied, specifies the account's password. The two argument form of authtest validates the password, and displays an indication whether the given password is valid, or not. The three argument form of the authtest command attemps to change the account's password. The second argument is the old password, the third argument is the new password.

See README.authdebug.html for more information.

     # 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
     #

The following structure describes an authentication module:

An authentication module is a shared library that defines a single function called “courier_auth_NAME_init”, where “NAME” 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 authstaticinfo structure. For example, the relevant code from the authmysql module is:

auth_func points to a function that handles an authentication request. The function is invoked as follows:

“service” is the name of the service being authenticated, such as “imap” or “pop3”. “authtype” defines the authentication format, and “authdata” is the actual authentication request.

Two authentication formats are defined at this time. The “authtype” string is set to one of the following strings:

The authentication function should return a negative value if the login ID is invalid. The authentication library will try the next authentication module.

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.

Otherwise, the authentication module should call the callback_func function, and return the same value that's returned by this function.

The authentication module should pass through callback_arg to the callback function as a second argument. The first argument is a pointer to the authinfo structure, which is described in detail in the auth_generic_meta(3) 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:

auth_pre_func points to a function that obtains account information. The function is invoked as follows:

This function does the same thing as “auth_func” except that the password is not actually verified. If the account exists, the callback function is invoked with the same callback arguments.

auth_cleanup_func points to a function that will be invoked just before the authentication module is uninstalled, giving it the opportunity for some last-minute cleanup.

auth_idle 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.

auth_changepwd points to a function that will be invoked to change a password on an account, as follows.

service is the name of the service whose password is to be changed (such as “imap” or “pop3”). auth_changepwd should return 0 if the password was changed succesfully, a negative value if user 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).

auth_enumerate points to a function that enumerates the list of all login IDs known to the authentication module. The first argument auth_enumerate is a callback function. auth_enumerate 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 auth_enumerate.

After enumerating all login IDs auth_enumerate 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, auth_enumerate terminates without invoking the callback function with a NULL login ID.

/usr/local/etc/authlib/authdaemonrc - authdaemond configuration file

/usr/local/etc/authlib/authldaprc - authldap configuration file

/usr/local/etc/authlib/authmysqlrc - authmysql configuration file

/usr/local/etc/authlib/authsqliterc - authsqlite configuration file

/usr/local/etc/authlib/authpgsqlrc - authpgsql configuration file

courier(8), userdb(8)