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





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 Frequently asked questions
8.0 Bugs and reporting
9.0 Contact


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

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

Once IMAP/POP3 is used via the Kopano or 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 MariaDB/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 |----+
      +-------------+    +------+    +-------------+    +-------------+    |
                                                                           |
   +---------------+                                                       |
   | Kopano server |<---+                                                  |
   +---------------+    |   +--------------+    +----------+    +-----+    |
                        +---| MAPI in SOAP |<---| pam_mapi |<---| PAM |<---+
   +---------------+    |   +--------------+    +----------+    +-----+
   | Zarafa server |<---+
   +---------------+

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 Kopano or 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 Kopano/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 Kopano or Zarafa server is configured
to use the Unix or LDAP authentication plugin.


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

- kopano >= 8.0.0 (with mapi4linux and headers for compiling)
- zarafa >= 6.20.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)
  - gcc-c++ >= 4.8 is required for Kopano Core (due to C++11)


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.

Depending on the Linux distribution running "./configure" is not enough. Most
of the times "./configure --enable-securedir=/lib64/security" (e.g. on x86_64
at Red Hat Enterprise Linux or SuSE Linux Enterprise Server) is required. But
"./configure --enable-securedir=/lib/x86_64-linux-gnu/security" is needed for
Debian Linux on amd64 architecture. If unsure, simply search for the directory
that contains many pam_*.so files.

The exact package names of build-time requirements heavily depend on the Linux
distribution being used. On Red Hat Enterprise Linux the command "yum install
gcc-c++ pam-devel zlib-devel pkgconfig /usr/include/uuid/uuid.h libicu-devel"
can be used as a base. On Debian Linux "apt-get install g++ libpam-dev zlib-dev
pkg-config make uuid-dev libicu-dev" should be suitable. The Kopano and Zarafa
headers and libraries are part of the package kopano-devel/zarafa-devel (RPM)
or kopano-dev/zarafa-dev (DEB). It is available at https://download.kopano.io,
https://download.zarafa.com or even part of the Linux distribution.


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 file or within every PAM
configuration file where pam_mapi.so is used.

socket=http://localhost:236/kopano
socket=http://localhost:236/zarafa

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

    Be very careful when specifying the UNIX socket here, because the default
    Kopano or Zarafa configuration option "local_admin_users" in either the
    /etc/kopano/server.cfg or /etc/zarafa/server.cfg file 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.

service=pop3|imap|mobile|outlook

    Try authentication by using the given service/feature. Since Kopano 8.0.0
    and Zarafa 7.0.0 some features can be enabled and disabled on a per-user
    basis. If e.g. IMAP is disabled for a specific user any IMAP login will
    fail. Using this option the same behaviour can be applied to pam_mapi for
    e.g. SMTP authentication.

    Valid values are values from option "disabled_features" in either the file
    /etc/kopano/server.cfg or /etc/zarafa/server.cfg. Multiple services can be
    listed using a pipe character and behave like a digital logic OR gate. So
    service=pop3|imap will permit authentication if either the feature POP3 or
    IMAP has been enabled for this user.

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.

quiet

    Do not treat MAPI_E_LOGON_FAILED authentication failures as errors that
    need to be logged to syslog(3). This option can be used for stacking
    different modules, because the existence of an account can be only assured
    after a succeeded authentication due to limited PAM account functionality.

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 (mostly independent of the Linux distribution):

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

Since Kopano 8.0.0 and Zarafa 7.0.0 some features can be enabled and disabled
on per-user basis. Previous configuration would pass authentication even if
e.g. IMAP is disabled for a specific user. By adding the service option one of
the given features has to be enabled to pass authentication:

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

Another common usage in /etc/pam.d/smtp could be authenticating against Linux
system and Kopano/Zarafa users. However this configuration depends heavily on
the used Linux distribution. Fortunately in many cases the following two lines
simply have to be added (before the existing lines):

    auth       sufficient   pam_mapi.so try_first_pass quiet
    account    sufficient   pam_mapi.so

On Red Hat Enterprise Linux 5 (and derivates such as CentOS) the authentication
against Linux system and Kopano/Zarafa users looks like this:

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

The same configuration for Red Hat Enterprise Linux 6 and 7 (including CentOS):

    #%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 Frequently asked questions
------------------------------

The "undefined symbol: _Z15HrOpenECSessionPP12IMAPISessionPKwS3_PKcjS5_S5_S5_"
message is shown if pam_mapi was built using Zarafa < 7.2.0 but pam_mapi.so is
used with Zarafa >= 7.2.0 (e.g. after a Zarafa update). The Zarafa 7.2.0 beta 2
introduces an API and ABI incompatibility which can not be catched by packaging
mechanisms in RPM and DEB due a missing change of the soname version in Zarafa.

"M4LMsgServiceAdmin::ConfigureMsgService() MSGServiceEntry failed 80040111" is
shown or gets written to the logs if a MAPI login fails. This message is part
of the new logging mechanism in Zarafa >= 7.2.0 and is unfortunately directly
thrown by the libmapi library and can't (yet?) be avoided without changing the
libmapi library itself.

The "libmapi.so.0: cannot open shared object file: No such file or directory"
message is shown if pam_mapi was built with an earlier version of Zarafa 7.2.x
but pam_mapi.so is used with a later version of Zarafa 7.2.x now (e.g. after a
Zarafa update). While changes of soname version during a stable release series
are highly questionable, this change can be catched by packaging mechanisms in
RPM and DEB, thus this error message is only shown with non-packaged builds.

If pam_mapi was built using Kopano < 8.2.0 but pam_mapi.so is used with Kopano
>= 8.2.0 now (e.g. after a Kopano update), the error message "undefined symbol:
_Z15HrOpenECSessionP8ECLoggerPP12IMAPISessionPKcS5_PKwS7_S5_jS5_S5_S5_" will be
shown. Kopano 8.2.0 introduces an API and ABI incompatibility which can not be
catched by packaging mechanisms in RPM and DEB due a missing change of soname
version in Kopano.


8.0 Bugs and reporting
----------------------

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


9.0 Contact
-----------

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