s/qmail:

Section: Misc. Reference Manual Pages (qmail-authuser)
Updated: 8
Index Return to Main Contents

NAME

qmail-authuser - user authentication

SYNOPSIS

qmail-authuser [ program maildirname | [-s authsocket [-x service=authmethod]] ] subprogram [ args ]

DESCRIPTION

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 SQMAIL/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 SQMAIL/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.

USE CASES

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.

INTERFACE DESCRIPTION

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.

FILES

SQMAIL/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.

AUTHUSER

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.

NATIVE MODE

qmail-authuser recalculates the digest using the provided challenge and the passwords from SQMAIL/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 SQMAIL/users/authuser. Thus, qmail-authuser can be used as PAM identity provider for PLAIN, LOGIN, CRAM-MD5 and APOP auth methods.

SYSTEM MODE

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.

VIRTUAL USER MODE

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.

BINCIMAP MODE

qmail-authuser can be used as generic authentication PAM sandwiched between bincimap-up and bincimapd.

DOVECOT MODE

qmail-authuser is also capabable to connect to a Unix socket created for authentication by Dovecot.

POP3 AND APOP

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 SQMAIL/users/authuser. Upon successful authentication qmail-authuser changes to $HOME.

QUERY AND STORAGE MODES

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 SQMAIL/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 SQMAIL/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 SQMAIL/users/authuser.

SECURITY

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 SQMAIL/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.

PASSWORD HASHES

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.

AUTH METHODS

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.

EXIT CODES

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 SQMAIL/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.

ENVIRONMENT VARIABLES SET

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.

CREDITS

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.

Index

NAME
SYNOPSIS
DESCRIPTION
USE CASES
INTERFACE DESCRIPTION
FILES
AUTHUSER
NATIVE MODE
SYSTEM MODE
VIRTUAL USER MODE
BINCIMAP MODE
DOVECOT MODE
POP3 AND APOP
QUERY AND STORAGE MODES
SECURITY
PASSWORD HASHES
AUTH METHODS
EXIT CODES
ENVIRONMENT VARIABLES SET
CREDITS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 16:40:05 GMT, September 13, 2025