Skip to content

sys checkpwd.8

Jump to bottom
Manvendra Bhangui edited this page Jul 16, 2024 · 5 revisions

NAME

sys-checkpwd - indimail-mta checkpassword program for authentication

SYNOPSYS

sys-checkpwd alternate_checkpassword_program(s) /bin/false

DESCRIPTION

sys-checkpwd supports authentication for ESMTP AUTH option in qmail-smtpd(8), allowing the LOGIN, PLAIN, XOAUTH2, and CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5 AUTH types. sys-checkpwd looks up userids in the systems authentication database (/etc/passwd or /etc/shadow). sys-checkpwd needs to be setuid root to function. sys-checkpwd drops all root privileges after reading the shadow(5) file, switches to the real uid of the invoking process.

As reflected in the qmail-smtpd(8) man page, qmail-smtpd(8) must be invoked with three arguments: hostname, path of the sys-checkpwd program, and subprogram. If these arguments are missing, qmail-smtpd(8) will not advertise availability of AUTH.

sys-checkpwd reads descriptor 3 through end of file and then closes descriptor 3. There must be at most 512 bytes of data before end of file. If it invokes an alternate_checkpassword_program, it opens a pipe duping the read descriptor as 3 for the alternate_checkpassword_program. The write end of the pipe is duped to descriptor 4 and the data which was earlier read on descriptor 3 is written back on descriptor 4. The alternate program is invoked when sys-checkpwd doesn't support authentication for the supplied login name.

For LOGIN, PLAIN, XOAUTH2 AUTH types, the information supplied on descriptor 3 is a login name terminated by \0 and password terminated by \0. sys-checkpwd encrypts the password using crypt(3) routine and compares it against the value present in the passwd database. The encrypted password can be in DES, MD5, SHA-256 or SHA-512 hash.

For CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5 AUTH type, the information supplied on descriptor 3 is a login name terminated by \0, a cram-md5 challenge terminated by \0, and a cram-md5 response terminated by \0. sys-checkpwd encrypts the challenge with keyed MD5 using passwords from passwd database. It's compared with response (3rd parameter) and if they are the same then sys-checkpwd uses execvp to run subprogram with the given arguments. If they differ then it returns -1.

If challenge and response differ, sys-checkpwd exits 1. If sys-checkpwd is misused, it may instead exit 2. If there is a temporary problem checking the password, sys-checkpwd exits 111.

hostname is simply used to form the CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-RIPEMD, DIGEST-MD5 challenge. qmail-smtpd invokes sys-checkpwd, feeding it the username and password, in the case of LOGIN, PLAIN, XOAUTH2 or the username, challenge, and response, in the case of CRAM-MD5, CRAM-SHA1, CRAM-RIPEMD, DIGEST-MD5. If the user checks out, sys-checkpwd exits with a status of 0 for the user to be authenticated. Otherwise, subprogram should exit with a non-zero status, or call an alternate checkpassword program. The last subprogram can usually be /usr/bin/false (or /bin/false, depending on your flavor of OS).

For getting the user's encrypted password, sys-checkpwd(8) uses getpwnam(3) and getspnam(3) from glibc(7). It can use an internal version of these functions, qgetpwnam(3) and qgetspnam(3) if the environment variable USE_QPWGR is set.

sys-checkwd does not authenticate if user is inactive. A user is active if one logs in using IMAP or POP3 protocol. If ALLOW_INACTIVE is defined, sys-checkwd will proceed regardless of the user's active or inactive status.

If the environment variable DOMAIN_LIMITS is defined, sys-checkwd validates domain expiry and password expiry set by vmoduser(1) program.

On successful authentication, sys-checkwd can execute a script defined by environment variable POSTAUTH. In that case, the return value of sys-checkpwd will be the return value of POSTAUTH program/script.

MUAs and AUTH types tested with this software are:

  • Netscape Communicator 4.76 - LOGIN & PLAIN

  • Microsoft Outlook 2000 - LOGIN

  • Microsoft Outlook Express 5 - LOGIN

  • Eudora 5.0.2 – CRAM-MD5

  • sylpheed 0.8.2 – LOGIN, PLAIN and CRAM-MD5

  • evolution - LOGIN, PLAIN

  • Thunderbird - LOGIN, PLAIN

  • RoundCube Mail - LOGIN, PLAIN

OPTIONS

alternate_checkpassword_program Path to an alternate checkpassword utility which supports additional authentication advertised by qmail-smtpd.

RETURN VALUE

0 if authenticated, 1 on authentication failure or system problems.

SEE ALSO

shadow(3) shadow(5) qmail-smtpd(8), qmail-poppass(8), vchkpass(8), ldap-checkpwd(8), pam-checkpwd(8) nssd(8), pam-multi(8),

Clone this wiki locally