
                                                               _
               _ __   __ _ _ __ ___      _ __ ___   __ _ _ __ (_)
              | '_ \ / _` | '_ ` _ \    | '_ ` _ \ / _` | '_ \| |
              | |_) | (_| | | | | | |   | | | | | | (_| | |_) | |
              | .__/ \__,_|_| |_| |_|___|_| |_| |_|\__,_| .__/|_|
              |_|                  |_____|              |_|





Content
-------

1.0 What is pam_mapi?
2.0 Requirements
3.0 Installation and configuration
4.0 License and copyright
5.0 Configuration options
6.0 Example configurations
7.0 Bugs and reporting
8.0 Contact


1.0 What is pam_mapi?
---------------------

pam_mapi is a PAM module (Pluggable Authentication Modules) for authentication
against a Zarafa server. Applications like Zarafa WebAccess, Zarafa WebApp or
Microsoft Outlook which directly connect to the Zarafa Collaboration Platform
use MAPI in SOAP to do so. If Zarafa is configured to use the DB authentication
plugin, all user information are stored in a MySQL database.

Once IMAP/POP3 is used via the Zarafa Gateway, SMTP gets involved for outbound
e-mails, too. Usually this requires SMTP authentication (to avoid open relays),
but the user information in the MySQL database is unfortunately not accessible
for established SASL daemons. The password is hashed with MD5, but salted with
a non-standard method.

Cyrus SASL expects a plaintext password in the database when using SQL auxprop
plugin, the socalled frost patch does not help, too. And pam_mysql supports MD5
or SHA1 hashed passwords (aside of plaintext), but only without salts.

A solution for this situation can be pam_mapi, so here is a full example:

    +-------------+    +------+    +-------------+    +-------------+
    | SMTP client |--->| SMTP |--->| SMTP server |--->| SASL daemon |----+
    +-------------+    +------+    +-------------+    +-------------+    |
                                                                         |
     +---------------+    +--------------+    +----------+    +-----+    |
     | Zarafa server |<---| MAPI in SOAP |<---| pam_mapi |<---| PAM |<---+
     +---------------+    +--------------+    +----------+    +-----+

Typically, pam_mapi would be used together with Sendmail/Postfix and saslauthd
to verify if the username and password from the SMTP authentication dialog are
valid Zarafa login data to grant or deny relaying of e-mails.

As pam_mapi is a generic PAM module, it could be used for any other PAM related
authentication, e.g. at the Apache Webserver. If it is stacked with pam_unix it
could allow authentication against Linux system and Zarafa users, where a user
only needs to exist in one of the two user databases. However pam_mapi provides
a limited PAM account functionality, because the existence of an account can be
only assured after a succeeded authentication.

Finally, pam_mapi is not limited to the DB authentication plugin, but pam_unix
or pam_ldap should be evaluated - if the Zarafa server is configured to use the
Unix or LDAP authentication plugin.


2.0 Requirements
----------------

- zarafa >= 6.30.0 (with mapi4linux and headers for compiling)
- pam >= 0.77 (including header files for compiling)
- pkgconfig >= 0.15.0 (for compiling)
- gcc-c++ >= 3.0 (for compiling)


3.0 Installation and configuration
----------------------------------

Extract the pam_mapi-X.Y.Z.tar.gz using "tar xvfz <file>" or "gzip -d <file>
&& tar xvf <file>" for example. "X.Y.Z" simply stands for the current version
number of pam_mapi.

After that, change into the directory and type "./configure", "make" and "make
install". Then edit the PAM smtp configuration file (usually "/etc/pam.d/smtp")
and replace the content of this file with the first example from section 6.0.
Ensure that saslauthd(1) is configured to use PAM as authentication mechanism,
restart the daemon and configure your MTA to use SASL - if not already done so.


4.0 License and copyright
-------------------------

pam_mapi is licensed under the new BSD license (no advertising, three clause).
Alternatively, pam_mapi may be distributed under the terms of the GNU General
Public License (GPL), in which case the provisions of the GNU GPL are required
instead of the restrictions of the BSD license. This clause is necessary due
to a potential conflict between the GNU GPL and the restrictions contained in
a BSD-style copyright.

You can get the complete licenses e.g. at http://www.gnu.org/copyleft/gpl.html
and http://www.opensource.org/licenses/BSD-3-Clause.


5.0 Configuration options
-------------------------

The following options can be used in /etc/pam.d/smtp.mapi or within every PAM
configuration file where pam_mapi.so is used.

socket=http://localhost:236/zarafa

    Use the socket http://localhost:236/zarafa for the Zarafa login. This also
    can be HTTPS if the Zarafa server is not running on the same machine. The
    default socket http://localhost:236/zarafa is used, if none has been set.

    Be very careful when specifying the UNIX socket here, because the default
    Zarafa configuration option "local_admin_users" in /etc/zarafa/server.cfg
    contains the root user and saslauthd runs as root user by default, too. In
    this case, any authentication would succeed, even if wrong credentials are
    provided, which could make the SMTP service an open relay.

try_first_pass

    Use the authentication token previously obtained by another module that did
    the conversation with the application. If this token can not be obtained
    then the module will try to converse. This option can be used for stacking
    different modules that need to deal with the authentication tokens.

use_first_pass

    Use the authentication token previously obtained by another module that did
    the conversation with the application. If this token can not be obtained
    then the module will fail. This option can be used for stacking different
    modules that need to deal with the authentication tokens.

debug

    Turns on debugging via syslog(3).


6.0 Example configurations
--------------------------

The most typical usage in /etc/pam.d/smtp when authenticating only against
Zarafa users would be:

    #%PAM-1.0
    auth       required     pam_mapi.so try_first_pass
    account    required     pam_mapi.so

Another common usage in /etc/pam.d/smtp could be authenticating against Linux
system and Zarafa users:

    #%PAM-1.0
    auth       sufficient   pam_mapi.so try_first_pass quiet
    auth       include      password-auth
    account    sufficient   pam_mapi.so
    account    include      password-auth

Keep in mind while editing, that /etc/pam.d/smtp could be a symbolic link at
various Linux systems.


7.0 Bugs and reporting
----------------------

Please report bugs and problems - written in German or English language - to
me at: zarafa@robert-scheck.de


8.0 Contact
-----------

Name     : Robert Scheck
E-Mail   : zarafa@robert-scheck.de
GnuPG-Key: http://www.robert-scheck.de/kontakt/gpg/rsc.gpg
IRC chat : irc.linuxnetz.de, #robert-scheck
