added auth_vpopmail plugin

added auth_vpopmail plugin, using the perl-vpopmail module
added VPOPMAIL auth methods description to docs/authentication
added SEE ALSO section to each module, noting the VPOPMAIL description

Signed-off-by: Robert <rspier@pobox.com>

docs/authentication.pod

@@ -201,10 +201,51 @@ authentication attempts for this transaction.
 In addition, all plugins that are registered for a specific auth hook will
 be tried before any plugins which are registered for the general auth hook.
 
+=head1 VPOPMAIL
+
+There are 4 authentication (smtp-auth) plugins that can be used with
+vpopmail.
+
+=over 4
+
+=item auth_vpopmaild
+
+If you aren't sure which one to use, then use auth_vpopmaild. It
+has full support for all 3 authentication methods (PLAIN,LOGIN,CRAM-MD5),
+doesn't require the qpsmtpd process to run with special permissions, and
+can authenticate against vpopmail running on another host. It does require
+the vpopmaild server to be running.
+
+=item auth_vpopmail
+
+The next best solution is auth_vpopmail. It requires the p5-vpopmail perl
+module and it compiles against libvpopmail.a. There are two catches. The
+qpsmtpd daemon must run as the vpopmail user, and you must be running v0.09
+or higher for CRAM-MD5 support. The released version is 0.08 but my
+CRAM-MD5 patch has been added to the developers repo:
+   http://github.com/sscanlon/vpopmail
+
+=item auth_vpopmail_sql
+
+If you are using the MySQL backend for vpopmail, then this module can be
+used for smtp-auth. It has support for all three auth methods. However, it
+does not work with some vpopmail features such as alias domains, service
+restrictions, nor does it update vpopmail's last_auth information.
+
+=item auth_checkpassword
+
+The auth_checkpassword is a generic authentication module that will work
+with any DJB style checkpassword program, including ~vpopmail/bin/vchkpw.
+It only supports PLAIN and LOGIN auth methods.
+
+=back
+
 =head1 AUTHOR
 
 John Peacock <jpeacock@cpan.org>
 
+Matt Simerson <msimerson@cpan.org> (added VPOPMAIL)
+
 =head1 COPYRIGHT AND LICENSE
 
 Copyright (c) 2004-2006 John Peacock

plugins/auth/auth_checkpassword

@@ -39,6 +39,11 @@ Using sudo is preferable to enabling setuid on the vchkpw binary. If
 you reinstall vpopmail and the setuid bit is lost, this plugin will be
 broken.
 
+=head1 SEE ALSO
+
+If you are using this plugin with vpopmail, please read the VPOPMAIL
+section in docs/authentication.pod
+
 =head1 DIAGNOSTICS
 
 Is the path in the config/smtpauth-checkpassword correct?

plugins/auth/auth_vpopmail

@@ -0,0 +1,113 @@
+#!/usr/bin/perl -w
+use strict;
+
+=head1 NAME
+
+auth_vpopmail - Authenticate against libvpopmail.a
+
+=head1 DESCRIPTION
+
+This plugin authenticates vpopmail users using p5-vpopmail.
+Using CRAM-MD5 requires that vpopmail be built with the
+'--enable-clear-passwd=y' option.
+
+=head1 CONFIGURATION
+
+This module will only work if qpsmtpd is running as the 'vpopmail' user.
+
+CRAM-MD5 authentication will only work with p5-vpopmail 0.09 or higher.
+    http://github.com/sscanlon/vpopmail
+
+Decide which authentication methods you are willing to support and uncomment
+the lines in the register() sub. See the POD for Qspmtpd::Auth for more
+details on the ramifications of supporting various authentication methods.
+
+=head1 SEE ALSO
+
+For an overview of the vpopmail authentication plugins and their merits,
+please read the VPOPMAIL section in docs/authentication.pod
+
+=head1 AUTHOR
+
+Matt Simerson <msimerson@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2010 Matt Simerson
+
+This plugin is licensed under the same terms as the qpsmtpd package itself.
+Please see the LICENSE file included with qpsmtpd for details.
+
+=cut
+
+sub register {
+    my ($self, $qp) = @_;
+
+    $self->register_hook("auth-plain", "auth_vpopmail" );
+    $self->register_hook("auth-login", "auth_vpopmail" );
+    $self->register_hook("auth-cram-md5", "auth_vpopmail");
+}
+
+sub auth_vpopmail {
+    use vpopmail;
+    use Qpsmtpd::Constants;
+    use Digest::HMAC_MD5 qw(hmac_md5_hex);
+
+    my ($self, $transaction, $method, $user, $passClear, $passHash, $ticket) =
+      @_;
+    my ($pw_name, $pw_domain) = split "@", lc($user);
+
+    $self->log(LOGINFO, "Authenticating against vpopmail: $user");
+
+    return (DECLINED, "authvpopmail/$method - plugin not configured correctly")
+      if !test_vpopmail();
+
+    my $pw              = vauth_getpw($pw_name, $pw_domain);
+    my $pw_clear_passwd = $pw->{pw_clear_passwd};
+    my $pw_passwd       = $pw->{pw_passwd};
+
+    # make sure the user exists
+    if (!$pw || (!$pw_clear_passwd && !$pw_passwd)) {
+        return (DENY, "authvpopmail/$method - invalid user");
+
+        # change DENY to DECLINED to support multiple auth plugins
+    }
+
+    return (OK, "authvpopmail/$method")
+      if $pw_passwd eq crypt($passClear, $pw_passwd);
+
+    # simplest case: clear text passwords
+    if (defined $passClear && defined $pw_clear_passwd) {
+        return (DENY, "authvpopmail/$method - incorrect password")
+          if $passClear ne $pw_clear_passwd;
+        return (OK, "authvpopmail/$method");
+    }
+
+    if ($method =~ /CRAM-MD5/i) {
+
+        # clear_passwd isn't defined so we cannot support CRAM-MD5
+        return (DECLINED, "authvpopmail/$method") if !defined $pw_clear_passwd;
+
+        if (defined $passHash
+            and $passHash eq hmac_md5_hex($ticket, $pw_clear_passwd))
+        {
+        }
+    }
+
+    return (OK, "authvpopmail/$method")
+      if (defined $passHash
+          && $passHash eq hmac_md5_hex($ticket, $pw_clear_passwd));
+
+    return (DENY, "authvpopmail/$method - unknown error");
+}
+
+sub test_vpopmail {
+
+# vpopmail will not allow vauth_getpw to succeed unless the requesting user is vpopmail or root.
+# by default, qpsmtpd runs as the user 'qpsmtpd' and does not have permission.
+    use vpopmail;
+    my ($domain) = vpopmail::vlistdomains();
+    my $r = vauth_getpw('postmaster', $domain);
+    return if !$r;
+    return 1;
+}

plugins/auth/auth_vpopmail_sql

@@ -37,11 +37,7 @@ module requires that only a single record be returned from the database.
 This authentication modules does not recognize domain aliases. So, if you have
 the domain example.com, with domain aliases for example.org and example.net,
 smtp-auth will only work for $user@example.com. If you have domain aliases,
-consider using the auth_checkpassword plugin.
-
-The checkpassword plugin only supports plain and login authentications, where
-this plugin also supports CRAM-MD5. I use both modules together. I use this one
-for CRAM-MD5 and the checkpassword plugin for plain and login.
+consider using another plugin (see SEE ALSO).
 
 =head1 FUTURE DIRECTION
 
@@ -49,6 +45,11 @@ The default MySQL configuration for vpopmail includes a table to log access,
 lastauth, which could conceivably be updated upon sucessful authentication.
 The addition of this feature is left as an exercise for someone who cares. ;)
 
+=head1 SEE ALSO
+
+For an overview of the vpopmail authentication plugins and their merits,
+please read the VPOPMAIL section in docs/authentication.pod
+
 =head1 AUTHOR
 
 John Peacock <jpeacock@cpan.org>

plugins/auth/auth_vpopmaild

@@ -79,6 +79,11 @@ daemon is running on a different host or port, specify as follows:
 
 auth_vpopmaild host [host] port [port]
 
+=head1 SEE ALSO
+
+For an overview of the vpopmail authentication plugins and their merits,
+please read the VPOPMAIL section in doc/authentication.pod
+
 =head1 LINKS
 
 [1] http://www.qmailwiki.org/Vpopmaild