Consulting djbware Publications
≡  

The PAMs: qmail-authuser, qmail-vmailuser, qmail-ldapam, and others

A PAM is a Pluggable Authentication Module which is called on demand to support validation and/or verfication of some user given data, in particular the check-for-existance of email addresses (validation) and the proof ot be an owner of system resource (here: a mailbox) by means of a public and secret identifier, commonly known as user/password scheme.

In s/qmail - as with any other MTA - we have to consider three cases here:

  1. The validation of an email address to exist in the system (for a given domain) and thus, to accept the incoming email or to refuse acceptance.
  2. The verification, that the sender is the owner of a mailbox and posseses credentials to send email to other MTAs.
  3. The verification of a user to retrieve emails from the mail store of the system, typically by means of a POP3 or IMAP4 service.

A part from a PAM, the Cyrus IMAP service has pioneered the concept of a so-called Simple Authentication and Security Layer SASL which is often used as well. Here - depending on the use case - not a separate module is called setting up well-defined minimal access context, but rather a shared library is invoked in the context of the running process. However, SASL allows in addition the use of a PAM.

It is the concept of DJB's security framework to transparently provide verification based solely on PAMs. With may patch SPAMCONTROL for qmail I've extended this concept for validation for qmail-smtpd by means of the RECIPIENT interface being part of s/qmail since then.

For some more backgound about SMTP authentication check my SMTP Authentication tutorial, which is partially used here as repetition.

16.1 The Checkpassword API

As a generalization of the PLAIN authentication method, Dan Bernstein has defined a checkpassword interface to be used in particular for the combination qmail-pop3d and the auxiliary PAM checkpassword.

checkpassword provides a simple, uniform password-checking interface to all root applications. It is suitable for use by applications such as login, ftpd, and pop3d: * checkpassword reads descriptor 3 through end of file and then closes descriptor 3. * There must be at most 512 bytes of data before end of file. * The information supplied on descriptor 3 is a login name terminated by \0, a password terminated by \0, a timestamp terminated by \0, and possibly more data. * There are no other restrictions on the form of the login name, password, and timestamp. * If the password is unacceptable, checkpassword exits 1. * If checkpassword is misused, it may instead exit 2. * If there is a temporary problem checking the password, checkpassword exits 111.

The advantage of the checkpassword interface is to be simply applicable for most authentication methods like CRAM-MD5 and for instance the POP3 APOP mechanism. In case of CRAM-MD5, the provided checkpassword string is:

It should be noted, that checkpassword itself calls another (child-) program, typically qmail-pop3d. For SMTP Authentication this becomes obsolete, however the child program has to be supplied; otherwise the user validation will fail. A common choice is the program true (available as /bin/true or /usr/bin/true) which exits always '0'.

16.2 The qmail-authuser PAM

16.3 The qmail-vmailuser PAM

16.4 The qmail-ldapam

16.5 Any other PAMs

Though Bernstein's checkpassword program is only suited for a local user lookup (via /etc/passwd or shadow passwd) and therefore requires to run under root, its interface definition is widely deployed: