1 files changed, 433 insertions, 0 deletions
diff --git a/man/qmail-authuser.9 b/man/qmail-authuser.9
new file mode 100644
index 0000000..affb9fa
--- /dev/null
+++ b/man/qmail-authuser.9
@@ -0,0 +1,433 @@
+.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).