s/qmail:qmail-ldapam
Section: Maintenance Commands (8)
Index
Return to Main Contents
NAME
qmail-ldapam - recipient validation or
sender authentication via LDAP lookup
SYNOPSIS
qmail-ldapam
[ -a|h|p|s ] subprogram [ args ]
DESCRIPTION
qmail-ldapam
is a LDAP client acting as
validating and/or authenticating
Pluggable Authentication Module
(PAM). It is fed with
an email address
<user@example.com>.
Alternatively with a
userid,
or a
Distinguished Name (DN)
together with the user's
password.
Those values need to be interrogated for example by
qmail-smtpd,
qmail-popup,
or
bincimap-up
upon call.
In case
qmail-ldapam
is calling
subprogram,
this will be invoked upon successful execution.
INTERFACE DESCRIPTION
qmail-ldapam
employs a
checkpassword
compatible API reading structured data from
descriptor 3 with a length of max 512 byte.
The received data is used as binding information
or as attribute values to be compared with entries
in the
LDAP
directory (DIT).
In case of a successful LDAP lookup,
qmail-ldapam
calls
pathexec
to run
subprogram
and perhaps setting up the user environment.
The use of
subprogram
is required and can be expressed as
true
if in the path.
LDAP ACCESS
The LDAP binding and filtering
information needs to be qualified in the file
SQMAIL/control/ldapbind.
Multiple LDAP servers with different binding
requirements and look-up Schemas are supported.
For the purpose of validation only,
a technical LDAP user is required.
qmail-ldapam
does not require a particular
Schema
for LDAP lookups and can be accustomed to
almost any existing
Schema.
USE CASES
qmail-ldapam
can be employed for different scenarios:
- Validation (default)
-
is used in conjunction with
qmail-smtpd
to validate the existence of a SMTP
recipient
as given by
RCPT TO:<localpart@example.com>
against the filter attribute
mail
in the LDAP directory.
For the LDAP binding a particular 'technical'
DN
together with a binding
password
needs to be setup.
- Authentication (-a)
-
works in conjunction with
qmail-smtpd
in
Submission
mode, assuming the provided authentication
information allows a successful binding
against the LDAP directory. User authentication
data are converted into a
DN
X.509 style information, while the Internet
domain parameters are provided in
dc
style, if not already given in this format.
- Homedirectory (-h)
-
is a superset of
Authentication
including to fetch the user's
Home directory
path from the DIT and
chdir
to that. This is the typical scenario for
qmail-popup,
or
bincimap-up.
- ProxyAuth (-p)
-
Authentication is facilitated by means of the given
DN
in
SQMAIL/control/ldapbind
and a
User Attribute
setting up the search scope, while looking for the
UPN.
If found, the
UserPrincipalName
together with the provided
password
is now used for an adjacent bind with the concatinated
CNs
as valid
DN.
Note: The mapping needs to be setup in the LDAP DIT.
Binding is tried for this UPN and thus allowing
authentication.
In case a
Filter
value is provissioned with a directory, e.g.
/home,
the local part of the UPN is used to construct
the user's
home directory
and a
chdir
is attempted.
The
User Attribute
is typically given as
CN
of the
Virtual Address Manager.
Therefore,
Pop Toasters
can be easily realized.
- StartTLS (-s)
-
StartTLS negotiation for
qmail-ldapam
with the LDAP server.
A X.509 CA certificat is typically required.
SMTP RECIPIENT VALIDATION
qmail-ldapam
is called as PAM from
qmail-smtpd's
control file
SQMAIL/control/recipients:
domain|bin/qmail-ldapam /bin/true
*|bin/qmail-ldapam /bin/true
SMTP SENDER AUTHENTICATION
For
qmail-smtpd
typically providing
submission
services
qmail-ldapam
can be invoked in a
qmail-authuser
way:
... qmail-smtpd qmail-ldapam -a /bin/true
Now, the LDAP bindings takes place by
means of the
username
and
password
as supplied to
qmail-smtpd
by the SMTP client.
POP3/IMAP4 HOME DIRECTORIES
For
qmail-pop3d
bincimap-up
the following setup is used
... qmail-popup qmail-ldapam -h qmail-pop3d Maildir
For
bincimap-up
follows:
... bincimap-up -- /PATH/qmail-ldapam -h bincimap Maildir
The user's
home directory
is now fetched from the DIT and subject
of concatination with the user's mail store.
LDAP ATTRIBUTES TO SMTP VERBS MAPPING
Using LDAP, we have to recognize some LDAP concepts:
- Bind
-
is the way to access the LDAP server. This requires typically a
Distinguished Name (DN),
which consistes in particular of a
Common Name (CN)
to be given as
username
with additionally a
password
for authentication.
This may be complemented by a X.509
certificate (and key file). This needs to be issued by a
common CA (Certifcate Authority) also responsible
for the LDAP server's certificate.
The use of those certificates is called 'strong bind'.
- DIT
-
Directory Information Tree
used to store the
Entries
in a hierarchial and searchable manner.
- Entries
-
define a node in the DIT addressable by a
DN
and having several
Attributes
to be suject of filtering operations.
- Realm
-
is well-defined name space in the
LDAP
directory to host
Entries
with
Schema
dependent
Attributes
and identified by their
Distinguished Name,
or their
Relative Distinguished Name (RDN).
This name space can be roughly compared with a
- Domain Component (dc)
-
or (sub)domain in the DNS.
- Filter
-
is the operation fetching
attributes
from the LDAP directory
given the credentials of the binding user (DN).
Filtering is realized by a
comparison
which depends on the LDAP
O.ID
(Object Identifier) attribute and may be
case in-sensitive or perhaps allowing regular expressions.
- Filter attributes are typically
-
- MAIL
-
which is the SMTP recipient or originating address, aka
Rfc822Mail.
- HOMEDIRECTORY
-
to be the ancestor of typically the
Maildir
used for email storage or retrieval required by
POP3
and/or
IMAP4
services.
- In LDAP, the
-
- userPassword
-
attribute for a DN can be stored in the
DIT
in different ways (see below). Rather, it is
always transmitted from the client to the LDAP
server in
plaintext
mode.
- UserPrincipalName
-
is a LDAP attribute like the
CN
but structured like an
RFC822
email address.
UNSUPPORTED AND UNUSED LDAP ATTRIBUTES
qmail-ldapam
does currently not consider other LDAP attributes like
QUOTA,
UID,
or
GID
for a particular user which is given for instance in the
qmail-scheme
for LDAP. Rather, here the basic
InetOrgPerson
and
PosixAccount
Schema attributes are typically employed.
CONFIGURATION AND SETUP
In order to bind to the LDAP server
qmail-ldapam
makes use of
SQMAIL/control/ldapbind
which includes a list of LDAP servers to bind to.
The selection of LDAP servers is based on the
domain part of received user information.
Particular users or domains can be excluded for the lookup
while prefixed with an exclamation mark (!).
Particular LDAP servers can be chosen given the
domain information followed by a colon (:) and the LDAP
binding parameters. A catch-all LDAP server is
simply given by an asterics (*) preceeding the colon
as first character on the line.
!excluded.domain:
my.org:Host;[s]Port|Base:Scope|BindDN|BindPW|Filter:UserAttr|CA|Cert:Keyfile
*:|Base|BindDN|BindPW
The following tokens can be used:
- Host;[s]Port
-
The
host
and
port
for binding
host
can bei either and IPv4/IPv6 address or FQDN.
If no
host
is given, it defaults to
localhost.
port
can be omitted for LDAP, but needs to be specified for
LDAPS
forcing with a first character
s
a
Strong Bind
on the LDAPS port
636
if no other port number is given.
This of course requires an
Client certificate
and a
keyfile.
- Base:Scope
-
The LDAP Base for the lookup. The default
Scope
is a numerical value with default
2 (SUBTREE)
and thus can be omitted. It could also be set to
1 (ONELEVEL).
- BindDN
-
The technical LDAP user's Distinguished Name (DN)
in validation and proxy mode.
- BindPW
-
The password used for binding. Here, it is possible
to provide a file name including the password or a
*
allowing the read the passwords from a file given
the file descriptor 5 upon call.
Several white space separated passwords can be
provided to bind with the different LDAP servers.
This file may not be LF terminated.
- Filter:UserAttr
-
Additional
Filter
to substitute the atttributes
MAIL
and
HOMEDIRECTORY
depending on the flags (-a, -h, and -p).
UserAttr
is used to build up the binding
DN
if it does not default to
CN.
- CA
-
The shared root certificate for the LDAP client and server.
- Cert:Keyfile
-
The X.509 client certificate used for the binding
together with a fitting
keyfile
which however, can not be password protected.
TLS SUPPORT AND STRONG BIND
Calling
qmail-ldapam
with argument
-s
will invoke
StartTLS
on port
389.
One peculiar feature of
OpenLDAP
is to require the called
host
matching its
CN
in the
X.509
certificate provissioned for this LDAP server.
Thus, in
ldapbbind
this name has to be provided as hostname.
Strong Bind
requires a
s
as first character of the port number, a client
certificate,
and a matching
keyfile.
Note: The client's
certificate
must be issued by the server's CA.
SECURITY
qmail-ldapam
- unlike
qmail-authuser-
runs in the jailed environment of
sslserver
or perhaps
tcpserver,
given by the user
qmaild.
For successful operation,
qmail-ldapam
needs to access the public readable
SQMAIL/control/ldapbind.
To un-disclose the
BindPW
an external file holding the
BindDN
user's password can be referenced.
This file can be placed at a location, ie. at
users/ldappwd
and has to be accessible only by the user
qmaild
with file permissons
600.
Alternativeley, if the
BindPW
is given as
*,
now it is read from file descriptor
5
upon start though without the typical
LF character. Given the case
of several LDAP servers to bind to,
individual paswords - separated by a white space -
can be provided.
The technical user for the LDAP
bind shall be restricted by ACLs to
only read particular attributes.
By the same token, all other DN's passwords
shall be protected as well and not visible to
other LDAP user.
LDAP PASSWORD SUPPORT
In the
DIT,
the user attribute
userPassword
is a multi-value field. This means,
that the same password can be stored
in different ways:
plain,
hashed,
hased with salt,or
using the Unix
crypt.
qmail-ldapam
- by default - supplies the LDAP
server with an unencrypted password.
It is the obligation of the LDAP server - the backend -
to apply the given policy protecting the user's
password.
Generation: During setup of the password, a
pseudo-random value is generated acting as
salt
and appending the
password.
This concatenated value is used
as input for typically
N=1000
hashing rounds applying the chosen
hash function.
Finally, the result is
base64
encoded now to be a readable character string.
Storage: Given the
DN
the user's
password
is now stored indicating the method as
prefix in braces (e.g.
{SSHA256}
for the salted SHA-256 function)
followed by the
salt
and the
base64
encoded value
from the applied hash operation.
LOGGING
The
qmail-ldapam
provides some error logging on
FD 4.
In order to be recorded in the usual log written to
FD 1,
this file descriptor needs to be re-directed:
4>&1.
Usually this is facilitated on the calling command line or in a
run
script.
ENVIRONMENT VARIABLES SET
Upon call,
qmail-ldapam
clears the environment variable
USER
and sets to the
userid
irrespectively whether authentication was successful or not.
Since
USER
may be used by other authentication PAMs called in the chain,
additionally
AUTHUSER
is set keeping the original
userid
information for logging purpose.
The content of
USER
and
AUTHUSER
is typically the
DN
which might include the
CN
and/or the
UID
of the user in the LDAP directory.
HOME
is set to the user's home directory, if applicable.
RETURN CODES
If the LDAP binding was successful and
potentially a positive comparision was achieved,
qmail-ldapam
exits
0,
otherwise
1.
If
qmail-ldapam
is misused, it may instead exit 2.
If there is a temporary problem,
qmail-ldapam
exits 111.
In case
qmail-ldapam
can't read
SQMAIL/control/ldapbind
or parameters can't be set, it exits 110.
SEE ALSO
addresses(5),
envelopes(5),
qmail-popup(8),
qmail-smtpd(8),
qmail-recipients(8),
qmail-authuser(8),
qmail-vmailuser(8).
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- INTERFACE DESCRIPTION
-
- LDAP ACCESS
-
- USE CASES
-
- SMTP RECIPIENT VALIDATION
-
- SMTP SENDER AUTHENTICATION
-
- POP3/IMAP4 HOME DIRECTORIES
-
- LDAP ATTRIBUTES TO SMTP VERBS MAPPING
-
- UNSUPPORTED AND UNUSED LDAP ATTRIBUTES
-
- CONFIGURATION AND SETUP
-
- TLS SUPPORT AND STRONG BIND
-
- SECURITY
-
- LDAP PASSWORD SUPPORT
-
- LOGGING
-
- ENVIRONMENT VARIABLES SET
-
- RETURN CODES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 19:23:51 GMT, August 26, 2026