Skip to content

vchkpass.8

Jump to bottom
Manvendra Bhangui edited this page Feb 25, 2024 · 7 revisions

NAME

vchkpass - checkpassword program for IndiMail authentication

SYNOPSYS

vchkpass prog args

DESCRIPTION

vchkpass(8) supports authentication for ESMTP AUTH option in qmail-smtpd(8), allowing the LOGIN, PLAIN, CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5 AUTH types. vchkpass(8) looks up userid in IndiMail's MySQL Database. It uses the pw_passwd field for LOGIN, PLAIN, CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA523 in the MySQL indimail or indibak tables. For SCRAM authentication methods the scram field will be used in addition to the pw_passwd field. The pw_passwd field in the indimail MySQL table is normally encrypted using crypt(3). This works for LOGIN and PLAIN authentication. For CRAM authentication methods one can store un-encrypted value by passing the -e option to vadduser(1), vpasswd(1), vmoduser(1). However, LOGIN and PLAIN methods will not authenticate when passwords are stored un-encrypted. If you want to have authentication work for LOGIN, PLAIN and the CRAM methods, one can store the passwords encrypted, set the environment variable ENABLE_CRAM and have clients supply encrypted passwords as the password. If you set the passwords for SCRAM authentication, then one can store both encrypted and un-encrypted passwords in the database (-C, -m option when using vadduser(1), vmoduser(1), vpasswd(1)). In such a case all authentication methods will work. Additionally, if you set the passwords for CRAM, SCRAM, then you need not set ENABLE_CRAM environment variable.

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

vchkpass(8) 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 prog, it opens a pipe duping the read descriptor as 3 for the prog. 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 prog program is invoked when vchkpass(8) doesn't support authentication for the supplied login name.

For LOGIN, PLAIN AUTH types, the information supplied on descriptor 3 is a login name terminated by \0 and password terminated by \0. vchkpass(8) encrypts the password using cyrpt(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. The hash can be selected when creating users with vadduser(1) or modifying it using vmoduser(1) or vpasswd(1).

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. vchkpass(7) 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 vchkpass(8) uses execvp to run subprogram with the given arguments. If they differ then it returns -1.

If challenge and response differ, vchkpass(8) exits 1. If vchkpass(8) is misused, it may instead exit 2. If there is a temporary problem checking the password, vchkpass(8) exits 111.

hostname is simply used to form the CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5 challenge. qmail-smtpd invokes vchkpass(8), feeding it the username and password, for LOGIN or PLAIN methods or the username, challenge, and response, for CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5. If the password checks out, vchkpass(8) exits with a status of 0. If password is unacceptable, vchkpass(8) runs prog. You can have a chain of prog on the command line with the last prog being /bin/false to terminate the authentication process.

vchkpass(8) 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, vchkpass(8) will proceed regardless of the user's active or inactive status.

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

On successful authentication, vchkpass(8) can execute a script defined by environment variable POSTAUTH. In that case, the return value of vchkpass(8) will be the return value of POSTAUTH program/script.

If the environment variable QUERY_CACHE is set, vchkpass(8) sends requests to inlookup(8) daemon. Using inlookup(8) aids performance as requests are cached and pooled. Without QUERY_CACHE defined, vchkpass(8) directly connects to the MySQL database for fulfilling authentication request from clients.

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

OPTIONS

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

RETURN VALUE

If the password is acceptable, vchkpass(8) exits 0. If vchkpass(8) is misused, it may instead exit 2. If there is a temporary problem checking the password, vchkpass(8) exits 111.

If the password is unacceptable, vchkpass(8) runs prog. prog consists of one or more arguments.

If the environment variable NATIVE_CHECKPASSWORD is set, vchkpass(8) will run prog on successful authentication and exit 1 if password is unacceptable.

SEE ALSO

qmail-smtpd(8), qmail-poppass(8), sys-checkpwd(8), ldap-checkpwd(8), pam-checkpwd(8) nssd(8), pam-multi(8),

Clone this wiki locally