From 89b7b67a13ebb7965cc7f13ad0595e2194a2d34c Mon Sep 17 00:00:00 2001 From: Jannis Hoffmann Date: Wed, 3 Jul 2024 15:48:04 +0200 Subject: add sqmail-4.2.29a --- man/qmail-authuser.9 | 433 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 433 insertions(+) create mode 100644 man/qmail-authuser.9 (limited to 'man/qmail-authuser.9') 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). -- cgit v1.2.3