.TH s/qmail: qmail-authuser 8

.SH "NAME"
qmail-authuser \- user authentication
.SH "SYNOPSIS"
.B qmail-authuser
[
.I qmail-pop3d maildirname
|
.I -s authsocket [-x service=authmethod]
]
.I subprogram [ args ]
.SH "DESCRIPTION"
.B 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
.I SQMAIL/users/authuser 
and the given arguments.
It can be used as substitude for the programs
.IR checkpassword ,
.IR cmd5checkpw ,
.IR checkvpw ,
and 
.I vchkpw
supporting the same arguments on call.
.TP 5
Native mode:
.B qmail-authuser
reads
.I SQMAIL/users/authuser 
and uses the information as local authentication database.
.TP 5
System mode:
.B qmail-authuser
accesses the Unix 
.I /etc/password
file (or it's shadow companion) as authentication source.
.TP 5
Virtual user mode:
.B qmail-authuser 
calls either the virtual domain auth handler
.B vchkpw 
or 
.BR checkvpw .
.TP 5
Dovecot mode:
.B qmail-authuser
queries
.B dovecot
as authentication provider.
.SH "USAGE"
.B qmail-authuser 
can be called by
.B qmail-smtpd 
and/or
.B qmail-popup
while following the 
.BR 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 \fIauthuser\fR name terminated by \e0,
a \fIpassword\fR or \fIresponse\fR terminated by \e0,
and a \fIchallenge\fR for CRAM-MD5 or APOP 
authentication terminated by \e0.
There must be at most 512 bytes of data before end of file.

In case
.I authuser 
and 
.I password 
match,
.B qmail-authuser
calls
.B pathexec
to run
.B subprogram
with the given arguments and perhaps setting up the user environment.
The use of
.B subprogram 
is required and can be expressed as
.B /bin/true
or 
.B /usr/bin/true
for compliance reasons.
.SH "FILES"
.I SQMAIL/users/authuser 
contains pairs of 
.I authuser 
and 
.I 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 
.I 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.
.SH "AUTHUSER"
The 
.I authuser
token is the public part of the identity and
may include a composit information, typically the 
.I userid 
and the 
.I domain
respectively, described as
.IR userid@domain .
.B qmail-authuser
may treat both parts independently.
Domain specific authentication may be considered using the
.I @domain
part within the
.I authuser 
token. However, as an abbreviation, 
this may be provided simply as
.IR @ ,
telling 
.B qmail-authuser
to consider all unspecified authusers solely and transparently 
as \'virtual users\'.
On the other hand, the
.I authuser
token may be wildcarded as
.IR * .
Now, 
.B qmail-authuser 
is instructed to query the local Unix system as identity provider.

More specific 
.I 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:
.IR !authuser .

Note: Virtual Domain Managers require to include the domain within 
.I authuser 
in order to identify the domain the user belongs to.
.SH "NATIVE MODE"
.B qmail-authuser
recalculates the digest using the provided challenge
and the passwords from
.IR SQMAIL/users/authuser 
and compares it with response (2nd parameter). 

If no challenge is provided,
.B qmail-authuser 
compares the supplied password with the stored 
.I password 
token in 
.IR SQMAIL/users/authuser .
Thus,
.B qmail-authuser 
can be used as PAM identity provider for 
PLAIN, LOGIN, CRAM-MD5 and APOP auth methods.
.SH "SYSTEM MODE"
.B qmail-authuser
may also been used as a replacement for the
.B checkpassword
PAM, allowing to evaluate the 
.I /etc/passwd
and 
.I shadow
files for the auth methods USER, PLAIN & LOGIN 
while only considerung the user part in 
.IR authuser .
In this case,
.B qmail-authuser
has to be \'sticky\' and running as 
.IR root .
.SH "VIRTUAL USER MODE"
.B qmail-authuser
includes the call of both
.IR vpopmail 's
.B vchkpw
and
.IR vmailmgr 's
.B checkvpw 
(which need to be in the path) 
and transfers the received authentication information transparently to those.
.SH "DOVECOT MODE"
.B qmail-authuser 
is also capabable to connect to a Unix socket created for authentication by
.IR Dovecot .
.SH "POP3 AND APOP"
Calling
.B qmail-authuser
for POP3 authentication with the option
.I qmail-pop3d 
together with the format of the mailbox given as
.IR maildirname ,
which is typically
.I Maildir 
or
.IR mbox .
The required environment variables
\fIUSER\fR, \fIHOME\fR, and \fISHELL\fR
for the respective user are evaluated from
.IR /etc/passwd .
APOP authentication is possible for a given user, if
.I authuser 
and the
.I password
is included in
.IR SQMAIL/users/authuser .
Upon successful authentication 
.B qmail-authuser
changes to $\fIHOME\fR. 
.SH "QUERY AND STORAGE MODES"
The first character 
.I X
of the 
.I password 
token is used to indicate the password's query and storage method. 
The following cases may be considered:

.EX
  (1a) authuser:clearpwd
  (1b) authuser:%pwdhash
  (2a) authuser:?
  (2b) *:?
  (3a) authuser:+
  (3b) @domain:+
  (3c) @:+
  (3d) authuser:&
  (3e) @domain:&
  (3f) @:&
  (4a) authuser:=
  (4b) @domain:=
  (4c) @:=
.EE

(1) Local query/storage:
Here, together with the 
.I authuser
plaintext (1a) or hashed passwords (1b)
may be provisioned in the
.I SQMAIL/users/authuser
control file.
In case of
.IR %pwdhash ,
the password is stored as MD5, SHA1, or SHA256 hash prepended with the \'%\'.
If the plaintext password is given as
.I password
this means that the following password is taken literally
though allwowing a leading \'%\'.  

(2) Unix system query/storage:
In case the 
.I password 
token consists of
.IR '?' ,
the received authentication information is used to emulate a 
standard Unix user login taking the 
.I userid
information as system user account. Therefore, no particular
.I password 
token is required here.
The inclusion of any specific 
.I authuser
information can be avoided in case
.I '*'
is used as shortcut within
.I SQMAIL/users/authuser
followed by 
.I '?'
as 
.I password 
token. Now, the received
.I userid 
and password is taken from the Unix system for authentication (crypt).

(3) Virtual domain query/storage:
Alternatively, 
.B qmail-authuser
may call either 
.B checkvpw
once a 
.I '+'
or
.B vchkpw
in case 
.I '&'
is given as 
.I password 
token.

(4) Dovecot as Identity Provider:
.B Dovecot 
can be used as authentication backend in case a
.I '='
is included as 
.I password
token. Assuming
.B doveadm 
is in the path, a particular
.B auth-qmail
listener (socket) is tested by
.I doveadm 
with the arguments
.I \'auth test -a\' 
provided the socket is available via 
.IR \'-s\ authsocket\' .


The definition of the auth socket 
needs to be included in 
.BR Dovecot 's
control file in the following way:

.EX
service auth {
  unix_listener /var/run/dovecot/auth-qmail {
    mode = 0600
    user = qmaild
    group = nofiles
  }
}
.EE

Reversely, this socket has to be
specified as calling argument for
.I qmail-authuser 
providing 
.I -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
.I -x service=authmethod
in the call of 
.BR qmail-authuser .
Check the
.b doveadmn
documentation for particular authentication methods,
typically available as \fIsmtp\fR and \fIpop3\fR.

Note: All authentication storage and query mechanism
can be used concurrently, depending on the settings
of the
.I authuser
and 
.I password
token in
.IR SQMAIL/users/authuser .
.SH "SECURITY"
.B qmail-authuser
is invoked in the environment of 
.B qmail-smtpd 
or 
.B qmail-popup
which is typically run as user 
.IR qmaild .
The file
.I SQMAIL/users/authuser
shall be
.I qmaild
owned and belonging to the group
.I sqmail 
and SHOULD NOT be readble by the \fIworld\fR.

Since the given
.I authuser 
token is visible in the email, it could be typically chosen as
.I user@domain 
making it usable for virtual domain managers and allowing
a common
.I password 
for ESMTP/IMAP4/POP3 services.

The included
.I password
token shall solely be used for ESMTP/IMAP4/POP3 authentication
and should possess enough entropy. 

A sticky and root-owned
.B qmail-authuser
is a potential security risk.
.SH "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.  
.SH "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
.B vchkpw
C/R is possible querying the local \'vpopmail\' database.
.SH "EXIT CODES"
In case the provided
.I authuser
or 
.I userid
does not exist, or the digest and the response, 
or the passwords
differ,
.B qmail-authuser
exits 1.
If
.B qmail-authuser
is misused, it may instead exit 2.
In case 
.I SQMAIL/users/authuser
is not readeable, 
.B qmail-authuser
exits 110.
If there is a temporary problem checking the password,
.B qmail-authuser
exits 111.
.SH "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.
.SH "SEE ALSO"
qmail-popup(8),
qmail-smtpd(8),
checkpassword(8),
vchkpw(8),
checkvpw(8),
doveadm(1),
doveadm-auth(1).