qmail-authuser subprogram [ args ... ]
qmail-authuser is a versatile authentication PAM. In it's native use,
it accesses a local database or the Unix /etc/password file (or it's
shadow companion). In qmail-authuser's alternate use, it may call a
virtual domain auth handler.
qmail-authuser follows checkpassword's interface specification provid-
ing LOGIN, PLAIN, and CRAM-MD5 authentication for SMTP as well as USER
and APOP for POP3 in addition with the required environment settings.
The information supplied on descriptor 3 is a authuser name terminated
by \0, a password or response terminated by \0, and a challenge for
CRAM-MD5 authentication terminated by \0. There must be at most 512
bytes of data before end of file.
/var/qmail/users/authuser contains pairs of authuser and password
tokens separated by a colon (":"). Both tokens may include white spa-
ces (if supported by the OS) and may use special characters for certain
actions. The provided password token should have a significant length
(> 2 characters).
Lines starting with the '#' sign are regarded as comment. Trailing
empty spaces in lines are removed prior of evaluation.
The file /var/qmail/users/authuser shall be root owned and belong to
The authuser token is the public part of the identity and may include a
composit information, typically the userid and the domain respectively,
described as userid@domain. qmail-authuser may consider both parts
independently. Domain specific authentication can be triggered includ-
ing the information @domain as authuser token. However, as an abbrevia-
tion, this may be provided simply as @, telling qmail-authuser to con-
sider all unspecified authusers solely and transparently as 'virtual
users'. On the other hand, the authuser token may be wildcarded as *.
Now, qmail-authuser is instructed to query the local Unix system for
More specific authuser tokens have precedence over less specific, irre-
spectively of their order. Particular users and domains can be dis-
abled from authentication prepending the name with a '!', which has
precedence over acceptance: !authuser.
qmail-authuser support thus (1) local email users, (2) Unix system
users, and (3) virtual domain users alltogether.
qmail-authuser recalculates the MD5 digest using the provided plain
challenge and the passwords from /var/qmail/users/authuser and compares
it with response (2nd parameter). If they are the same, qmail-authuser
uses pathexec to run subprogram with the given arguments and perhaps
setting up the user environment. The use of subprogram is required and
can be expressed as /bin/true or /usr/bin/true for compliance reasons.
If no challenge is provided, qmail-authuser compares the supplied pass-
word with the stored password token in /var/qmail/users/authuser.
Thus, qmail-authuser can be used as a generic checkpassword program for
PLAIN & LOGIN auth methods.
qmail-authuser may also been used as a replacement for the checkpass-
word PAM, allowing to evaluate the /etc/passwd and shadow files for the
auth methods USER, PLAIN & LOGIN. In this case, qmail-authuser has to
be 'sticky' and running as root. Depending on the provided password
token, the Unix environment will be evaluated and setup.
qmail-authuser includes the call of both vpopmail's vchkpw and
vmailmgr's checkvpw (which need to be in the path) and transfers the
received authentication information transparently to those.
QUERY AND STORAGE METHODS
The first character X of the password token is used to indicate the
password's query and storage method. The following cases may be con-
(1) Local query/storage: Here, together with the authuser plaintext
(1a) or hashed passwords (1b) may be provided in the
/var/qmail/users/authuser control file. In case of %pwdhash, the pass-
word is stored as MD5 hash following the '%'. If the plaintext pass-
word is given as password this means, that the following password is
taken literally and may include a leading '%',
(2) Unix system query/storage: In case the password token consists of
?, the received authentication information is used to trigger a stan-
dard Unix login user query taking the userid information as system user
account. Therefore, no particular password token is required here. If
instead ! is used, additionally, the Unix user environment will be
evaluated and setup according to the checkpassword implementation,
allowing qmail-authuser to be used for qmail-popup and qmail-pop3d ser-
vices. The inclusion of any specific authuser information can be
avoided in case * is used as shortcut within /var/qmail/users/authuser
followed by either ? or ! as password token. Now, the received userid
and password is fed automatically to the Unix system for authentica-
(3,4) Virtual domain query/storage: Alternatively, qmail-authuser may
call either checkvpw once a + or vchkpw in case & is given as password
All authentication storage and query mechanism can be used concur-
rently, depending on the settings of the authuser and password token in
In case the provided authuser or userid does not exist, or the MD5
digest and the response, or the passwords differ, qmail-authuser exits
1. If qmail-authuser is misused, it may instead exit 2. If there is a
temporary problem checking the password, qmail-authuser exits 111.
qmail-authuser is invoked in the environment of qmail-smtpd or qmail-
popup which is typically run as user qmaild. Therefore,
/var/qmail/users/authuser shall be readable only by this user. The
included password token shall solely be used for SMTP/POP3 authentica-
tion and should possess enough entropy.
A sticky and root-owned qmail-authuser is a potential security risk.
Instead of plaintext passwords, additionally MD5 hashes of the pass-
words may be used. However, in spite of rainbow tables this requires
none-trival passwords. Currenty, qmail-authuser only supports MD5
hashed passwords having 32 hex characters length. Other methods, like
SHA1 and SHA256, may be supported in the future but don't solve the
problem of rainbow tables to reverse the hash.
In case hashed passwords or the UNIX passwords are used, only the auth
methods USER, PLAIN, and LOGIN are working. Those methods are only
secure on encrypted connections and otherwise are easy victim of an
eavesdropper. Challenge/Response methods - like CRAM-MD5 and APOP -
require having access to the plain-text passwords. For vchkpw C/R is
possible querying the local 'vpopmail' database.
qmail-popup(8), qmail-smtpd(8), checkpassword(8), vchkpw(8), check-
Man(1) output converted with