SYNOPSIS

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

DESCRIPTION

       qmail-authuser is a versatile authentication PAM for SMTP and/or POP3
       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 programs
       checkpassword, cmd5checkpw, checkvpw, and vchkpw 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.

USAGE

       qmail-authuser can be called by qmail-smtpd and/or qmail-popup 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.

       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 subprogram is required and can be expressed as
       /bin/true or /usr/bin/true for compliance reasons.

FILES

       /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.
       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 is belonging to.

NATIVE MODE

       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.

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.

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
       /var/qmail/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
         (2a) authuser:?
         (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 '%'.

       (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.

SECURITY

       qmail-authuser is invoked in the environment of qmail-smtpd or
       qmail-popup which is typically run as user qmaild.  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.

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

EXIT CODES

       In case the provided authuser or userid does not exist, or the digest
       and the response, or the passwords differ, 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.

CREDITS

       The MD5 implmentation originates from RSA though now supporting a 64
       bit OS. 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.

SEE ALSO

       qmail-popup(8), qmail-smtpd(8), checkpassword(8), vchkpw(8),
       checkvpw(8), doveadm(1), doveadm-auth(1).



                                       8              s/qmail:(qmail-authuser)