qmail-authuser - user authentication
qmail-authuser [ program maildirname | [-s authsocket [-x service=authmethod]] ] subprogram [ args ]
qmail-authuser
is a versatile authentication PAM for SMTP, POP3 and IMAP
services providing four different operation modes depending
on the input of the configuration file
/var/qmail/users/authuser and the given arguments. It
can be used as substitude for the authentication modules
checkpassword, cmd5checkpw, checkvpw
(vmailmgr), and vchkpw (vpopmail) supporting the same
arguments on call.
Native mode:
qmail-authuser reads /var/qmail/users/authuser and uses the information as local authentication database.
System mode:
qmail-authuser accesses the Unix /etc/password file (or it’s shadow companion) as authentication source.
Virtual user mode:
qmail-authuser calls either the virtual domain auth handler vchkpw or checkvpw.
Dovecot mode:
qmail-authuser queries dovecot as authentication provider.
qmail-authuser
can be used for
authentication only:
qmail-authuser is called as a PAM typically by qmail-smtpd and verifies the user’s credentials (userid/password) as given by the client. subprogram is typically true.
mailbox interrogation:
Called by qmail-popup or bincimap-up, upon successfull authentication qmail-authuser switches to the home directory of userid and hands over operations to program provided as qmail-pop3d or bincimpad.
Note: maildirname has to start with ´mail´ or ´mbox´ irrespective of case.
qmail-authuser can be called by qmail-smtpd, qmail-popup, or bincimap-up while following the checkpassword’s interface specification and enabling LOGIN, PLAIN, and CRAM-MD5 authentication for SMTP as well as USER and APOP for POP3 and LOGIN and PLAIN for IMAP.
The information supplied on descriptor 3 is an authuser name terminated by \0, a password or response terminated by \0, and a challenge for CRAM-MD5 or APOP authentication terminated by \0. There must be at most 512 bytes of data before end of file.
In case authuser and password match, qmail-authuser calls pathexec to run subprogram with the given arguments and perhaps setting up the user environment. The use of program is required and can be expressed as /bin/true or /usr/bin/true for compliance reasons.
/var/qmail/users/authuser contains pairs of authuser and password tokens separated by a colon (":"). Both tokens may include white spaces (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 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 treat both parts independently. Domain specific authentication may be considered using the @domain part within the authuser token. However, as an abbreviation, this may be provided simply as @, telling qmail-authuser to consider 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 as identity provider.
More specific authuser tokens have precedence over less specific, irrespectively of their order. System mode has precedence over virtual user mode. Particular users and domains can be disabled from authentication prepending the name with a ´!´ overruling acceptance: !authuser.
Note: Virtual Domain Managers require to include the domain within authuser in order to identify the domain the user belongs to.
qmail-authuser recalculates the digest using the provided challenge and the passwords from /var/qmail/users/authuser and compares it with response (2nd parameter).
If no challenge is provided, qmail-authuser compares the supplied password with the stored password token in /var/qmail/users/authuser. Thus, qmail-authuser can be used as PAM identity provider for PLAIN, LOGIN, CRAM-MD5 and APOP auth methods.
qmail-authuser may also been used as a replacement for the checkpassword PAM, allowing to evaluate the /etc/passwd and shadow files for the auth methods USER, PLAIN & LOGIN while only considerung the user part in authuser. In this case, qmail-authuser has to be ´sticky´ and running as root.
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.
qmail-authuser can be used as generic authentication PAM sandwiched between bincimap-up and bincimapd.
qmail-authuser is also capabable to connect to a Unix socket created for authentication by Dovecot.
Calling qmail-authuser for POP3 authentication with the option qmail-pop3d together with the format of the mailbox given as maildirname, which is typically Maildir or mbox. The required environment variables USER, HOME, and SHELL for the respective user are evaluated from /etc/passwd. APOP authentication is possible for a given user, if authuser and the password is included in /var/qmail/users/authuser. Upon successful authentication qmail-authuser changes to $HOME.
The first character X of the password token is used to indicate the password’s query and storage method. The following cases may be considered:
(1a)
authuser:clearpwd
(1b) authuser:%pwdhash
(1c) !authuser:
(1d) !example.com:
(2a) authuser:?
(2b) *:?
(3a) authuser:+
(3b) @domain:+
(3c) @:+
(3d) authuser:&
(3e) @domain:&
(3f) @:&
(4a) authuser:=
(4b) @domain:=
(4c) @:=
(1) Local query/storage: Here, together with the authuser plaintext (1a) or hashed passwords (1b) may be provisioned in the /var/qmail/users/authuser control file. In case of %pwdhash, the password is stored as MD5, SHA1, or SHA256 hash prepended with the ´%´. If the plaintext password is given as password this means that the following password is taken literally though allwowing a leading ´%´. An authuser or domain prefixed with a ! exclamation mark (1c/1d) is excluded for further password checking, thus is disabled. This mechanism could be used to temporarily prevent dictionary attacks.
(2) Unix system query/storage: In case the password token consists of ’?’, the received authentication information is used to emulate a standard Unix user login taking the userid information as system user account. Therefore, no particular password token is required here. The inclusion of any specific authuser information can be avoided in case ’*’ is used as shortcut within /var/qmail/users/authuser followed by ’?’ as password token. Now, the received userid and password is taken from the Unix system for authentication (crypt).
(3) Virtual domain query/storage: Alternatively, qmail-authuser may call either checkvpw once a ’+’ or vchkpw in case ’&’ is given as password token.
(4) Dovecot as Identity Provider: Dovecot can be used as authentication backend in case a ’=’ is included as password token. Assuming doveadm is in the path, a particular auth-qmail listener (socket) is tested by doveadm with the arguments ´auth test -a´ provided the socket is available via ´-s authsocket´.
The definition of the auth socket needs to be included in Dovecot’s control file in the following way:
service auth {
unix_listener /var/run/dovecot/auth-qmail {
mode = 0600
user = qmaild
group = nofiles
}
}
Reversely, this socket has to be specified as calling argument for qmail-authuser providing -s /var/run/dovecot/auth-sqmail together with an additional executable (true). The name of the auth socket can be freely chosen.
A particular authentication method can be specified by means of -x service=authmethod in the call of qmail-authuser. Check the documentation for particular authentication methods, typically available as smtp and pop3.
Note: All authentication storage and query mechanism can be used concurrently, depending on the settings of the authuser and password token in /var/qmail/users/authuser.
qmail-authuser is invoked in the environment of qmail-smtpd, qmail-popup, or bincimap-up which is typically run as user qmaild. qmail-authuser is typically owned by root and belonging to group sqmail. It is suid’ed for root.
The file /var/qmail/users/authuser shall be qmaild owned and belonging to the group sqmail and SHOULD NOT be readble by the world.
Since the given authuser token is visible in the email, it could be typically chosen as user@domain making it usable for virtual domain managers and allowing a common password for ESMTP/IMAP4/POP3 services.
The included password token shall solely be used for ESMTP/IMAP4/POP3 authentication and should possess enough entropy.
A sticky and root-owned qmail-authuser is a potential security risk.
Instead of plaintext passwords, additionally MD5, SHA1, or SHA256 hashes of the passwords may be used. However, in spite of rainbow tables this requires none-trivial passwords.
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 or otherwise are an 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.
In case the provided authuser or userid does not exist, or the digest and the response, or the passwords differ, or the account is disabled qmail-authuser exits 1. If qmail-authuser is misused, it may instead exit 2. In case /var/qmail/users/authuser is not readeable, qmail-authuser exits 110. If there is a temporary problem checking the password, qmail-authuser exits 111.
Note: qmail-authuser is ’silent’, thus produces no output except for the return value given. If the authentication was not successful, qmail-authuser ´sleeps´ for five seconds before exiting.
Upon call, qmail-authuser clears the environment variable USER and sets to the userid irrespective 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 MD5 implementation originates from RSA though now supporting a 64 bit OS as well. SHA1 has been created by Steve Reid, and SHA256 was done by Brad Conte, all released in the Public Domain. Drew Wells receives credits for putting me into the current direction.
qmail-popup(8), qmail-smtpd(8), checkpassword(8), vchkpw(8), checkvpw(8), doveadm(1), doveadm-auth(1).