diff options
Diffstat (limited to 'sqmail-4.3.07/man/qmail-authuser.9')
| -rw-r--r-- | sqmail-4.3.07/man/qmail-authuser.9 | 490 |
1 files changed, 0 insertions, 490 deletions
diff --git a/sqmail-4.3.07/man/qmail-authuser.9 b/sqmail-4.3.07/man/qmail-authuser.9 deleted file mode 100644 index d2e89d8..0000000 --- a/sqmail-4.3.07/man/qmail-authuser.9 +++ /dev/null @@ -1,490 +0,0 @@ -.TH s/qmail: qmail-authuser 8 - -.SH "NAME" -qmail-authuser \- user authentication -.SH "SYNOPSIS" -.B qmail-authuser -[ -.I program maildirname -| -.I [-s authsocket [-x service=authmethod]] -] -.I subprogram [ args ] -.SH "DESCRIPTION" -.B qmail-authuser -is a versatile authentication PAM for SMTP, POP3 and IMAP 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 authentication modules -.IR checkpassword , -.IR cmd5checkpw , -.IR checkvpw -(vmailmgr), -and -.I vchkpw -(vpopmail) -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 "USE CASES" -.B qmail-authuser -can be used for -.TP 5 -authentication only: -.B qmail-authuser -is called as a PAM typically by -.B qmail-smtpd -and verifies the user's credentials -(userid/password) -as given by the client. -.I subprogram -is typically -.BR true . -.TP 5 -mailbox interrogation: -Called by -.B qmail-popup -or -.BR bincimap-up , -upon successfull authentication -.B qmail-authuser -switches to the home directory of -.I userid -and hands over operations to -.I program -provided as -.B qmail-pop3d -or -.BR bincimpad . - -Note: -.I maildirname -has to start with \'mail\' or \'mbox\' -irrespective of case. -.SH "INTERFACE DESCRIPTION" -.B qmail-authuser -can be called by -.BR qmail-smtpd , -.BR qmail-popup , -or -.B bincimap-up -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 and -LOGIN and PLAIN for IMAP. - -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 program -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 -.B 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 -.BR qmail-smtpd , -.BR qmail-popup , -or -.B bincimap-up -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 or otherwise are an 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 "ENVIRONMENT VARIABLES SET" -Upon call, -.B qmail-authuser -clears the environment variable -.I USER -and sets to the -.I userid -irrespective whether authentication was successful or not. -Since -.I USER -may be used by other authentication PAMs called in the chain, -additionally -.I AUTHUSER -is set keeping the original -.I userid -information for logging purpose. -.SH "CREDITS" -The MD5 implementation originates from RSA though now supporting a -64 bit OS as well. 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). |