SYNOPSIS

       qmail-authuser [ -s authsocket ] subprogram [ args ] 



DESCRIPTION

       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
       providing 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. by \0.  There must be at most 512
       bytes of data before end of file.  qmail-authuser calls by default a
       secondary program, typically provided as true.



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.

       The file /var/qmail/users/authuser shall be root owned and belong to
       group sqmail.



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 consider both parts
       independently.  Domain specific authentication can be triggered
       including the information @domain as 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 for authentication.

       More specific authuser tokens have precedence over less specific,
       irrespectively of their order.  Particular users and domains can be
       disabled 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, (3) virtual domain users, and (4) Dovecot users alltogether.

NATVIE USE

       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
       password with the stored password token in /var/qmail/users/authuser.
       Thus, qmail-authuser can be used as local identity provider for PLAIN,
       LOGIN, and C/R 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.
       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.



ALTERNATE USE

       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 is also capabable to connect to a Unix socket created
       for authentication by Dovecot.


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
       considered:

         (1a) authuser:clearpwd
         (1b) authuser:%pwdhash
         (2a) authuser:?
         (2b) authuser:!
         (2c) *:?
         (2d) *:!
         (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 following the '%'.  If
       the plaintext password 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
       standard 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
       with the provided authuser and password.
   
       (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: Dovecat can be used as authentication
       backend in case a = is included as password token. Assuming doveadm is
       in the path, a particular qmail-auth listener (socket) is tested
       by doveadm with the arguments auth test -a provided the socket is
       available via -s authsocket togther with the provided authuser and 
       password.

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


       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.



EXIT CODES

       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.



SECURITY

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



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.

SEE ALSO

       qmail-popup(8),   qmail-smtpd(8),   checkpassword(8),  vchkpw(8),   check-
       vpw(8).



                                       8              s/qmail:(qmail-authuser)

Man(1) output converted with man2html