259 lines
8.5 KiB
Plaintext
259 lines
8.5 KiB
Plaintext
#
|
|
# read this with 'perldoc authentication.pod' ...
|
|
#
|
|
|
|
=head1 NAME
|
|
|
|
Authentication framework for qpsmtpd
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Provides support for SMTP AUTH within qpsmtpd transactions, see
|
|
|
|
L<http://www.faqs.org/rfcs/rfc2222.html>
|
|
L<http://www.faqs.org/rfcs/rfc2554.html>
|
|
|
|
for more details.
|
|
|
|
=head1 USAGE
|
|
|
|
This code is automatically loaded by Qpsmtpd::SMTP only if a plugin
|
|
providing one of the defined L<Auth Hooks> is loaded. The only
|
|
time this can happen is if the client process employs the EHLO command to
|
|
initiate the SMTP session. If the client uses HELO, the AUTH command is
|
|
not available and this module isn't even loaded.
|
|
|
|
=head2 Plugin Design
|
|
|
|
An authentication plugin can bind to one or more auth hooks or bind to all
|
|
of them at once. See L<Multiple Hook Behavior> for more details.
|
|
|
|
All plugins must provide two functions:
|
|
|
|
=over 4
|
|
|
|
=item * init()
|
|
|
|
This is the standard function which is called by qpsmtpd for any plugin
|
|
listed in config/plugins. Typically, an auth plugin should register at
|
|
least one hook, like this:
|
|
|
|
|
|
sub init {
|
|
my ($self, $qp) = @_;
|
|
|
|
$self->register_hook("auth", "authfunction");
|
|
}
|
|
|
|
where in this case "auth" means this plugin expects to support any of
|
|
the defined authentication methods.
|
|
|
|
=item * authfunction()
|
|
|
|
The plugin must provide an authentication function which is part of
|
|
the register_hook call. That function will receive the following
|
|
six parameters when called:
|
|
|
|
=over 4
|
|
|
|
=item $self
|
|
|
|
A Qpsmtpd::Plugin object, which can be used, for example, to emit log
|
|
entries or to send responses to the remote SMTP client.
|
|
|
|
=item $transaction
|
|
|
|
A Qpsmtpd::Transaction object which can be used to examine information
|
|
about the current SMTP session like the remote IP address.
|
|
|
|
=item $mechanism
|
|
|
|
The lower-case name of the authentication mechanism requested by the
|
|
client; either "plain", "login", or "cram-md5".
|
|
|
|
=item $user
|
|
|
|
Whatever the remote SMTP client sent to identify the user (may be bare
|
|
name or fully qualified e-mail address).
|
|
|
|
=item $clearPassword
|
|
|
|
If the particular authentication method supports unencrypted passwords
|
|
(currently PLAIN and LOGIN), which will be the plaintext password sent
|
|
by the remote SMTP client.
|
|
|
|
=item $hashPassword
|
|
|
|
An encrypted form of the remote user's password, using the MD-5 algorithm
|
|
(see also the $ticket parameter).
|
|
|
|
=item $ticket
|
|
|
|
This is the cryptographic challenge which was sent to the client as part
|
|
of a CRAM-MD5 transaction. Since the MD-5 algorithm is one-way, the same
|
|
$ticket value must be used on the backend to compare with the encrypted
|
|
password sent in $hashPassword.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
Plugins should perform whatever checking they want and then return one
|
|
of the following values (taken from Qpsmtpd::Constants):
|
|
|
|
=over 4
|
|
|
|
=item OK
|
|
|
|
If the authentication has succeeded, the plugin can return this value and
|
|
all subsequently registered hooks will be skipped.
|
|
|
|
=item DECLINED
|
|
|
|
If the authentication has failed, but any additional plugins should be run,
|
|
this value will be returned. If none of the registered plugins succeed, the
|
|
overall authentication will fail. Normally an auth plugin should return
|
|
this value for all cases which do not succeed (so that another auth plugin
|
|
can have a chance to authenticate the user).
|
|
|
|
=item DENY
|
|
|
|
If the authentication has failed, and the plugin wishes this to short circuit
|
|
any further testing, it should return this value. For example, a plugin could
|
|
register the L<auth-plain> hook and immediately fail any connection which is
|
|
not trusted (e.g. not in the same network).
|
|
|
|
Another reason to return DENY over DECLINED would be if the user name matched
|
|
an existing account but the password failed to match. This would make a
|
|
dictionary-based attack much harder to accomplish. See the included
|
|
auth_vpopmail_sql plugin for how this might be accomplished.
|
|
|
|
By returning DENY, no further authentication attempts will be made using the
|
|
current method and data. A remote SMTP client is free to attempt a second
|
|
auth method if the first one fails.
|
|
|
|
=back
|
|
|
|
Plugins may also return an optional message with the return code, e.g.
|
|
|
|
return DENY, "If you forgot your password, contact your admin";
|
|
|
|
and this will be appended to whatever response is sent to the remote SMTP
|
|
client. There is no guarantee that the end user will see this information,
|
|
though, since some prominent MTA's (produced by M$oft) I<helpfully>
|
|
hide this information under the default configuration. This message will
|
|
be logged locally, if appropriate, based on the configured log level.
|
|
|
|
=head1 Auth Hooks
|
|
|
|
The currently defined authentication methods are:
|
|
|
|
=over 4
|
|
|
|
=item * auth-plain
|
|
|
|
Any plugin which registers an auth-plain hook will engage in a plaintext
|
|
prompted negotiation. This is the least secure authentication method since
|
|
both the user name and password are visible in plaintext. Most SMTP clients
|
|
will preferentially choose a more secure method if it is advertised by the
|
|
server.
|
|
|
|
=item * auth-login
|
|
|
|
A slightly more secure method where the username and password are Base-64
|
|
encoded before sending. This is still an insecure method, since it is
|
|
trivial to decode the Base-64 data. Again, it will not normally be chosen
|
|
by SMTP clients unless a more secure method is not available (or if it fails).
|
|
|
|
=item * auth-cram-md5
|
|
|
|
A cryptographically secure authentication method which employs a one-way
|
|
hashing function to transmit the secret information without significant
|
|
risk between the client and server. The server provides a challenge key
|
|
L<$ticket>, which the client uses to encrypt the user's password.
|
|
Then both user name and password are concatenated and Base-64 encoded before
|
|
transmission.
|
|
|
|
This hook must normally have access to the user's plaintext password,
|
|
since there is no way to extract that information from the transmitted data.
|
|
Since the CRAM-MD5 scheme requires that the server send the challenge
|
|
L<$ticket> before knowing what user is attempting to log in, there is no way
|
|
to use any existing MD5-encrypted password (like is frequently used with MySQL).
|
|
|
|
=item * auth
|
|
|
|
A catch-all hook which requires that the plugin support all three preceeding
|
|
authentication methods. Any plugins registering the auth hook will be run
|
|
only after all other plugins registered for the specific authentication
|
|
method which was requested. This allows you to move from more specific
|
|
plugins to more general plugins (e.g. local accounts first vs replicated
|
|
accounts with expensive network access later).
|
|
|
|
=back
|
|
|
|
=head2 Multiple Hook Behavior
|
|
|
|
If more than one hook is registered for a given authentication method, then
|
|
they will be tried in the order that they appear in the config/plugins file
|
|
unless one of the plugins returns DENY, which will immediately cease all
|
|
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
|
|
supports the PLAIN and LOGIN authentication methods,
|
|
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 supports LOGIN, PLAIN, and CRAM-MD5. 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
|
|
|
|
Portions based on original code by Ask Bjoern Hansen and Guillaume Filion
|
|
|
|
This plugin is licensed under the same terms as the qpsmtpd package itself.
|
|
Please see the LICENSE file included with qpsmtpd for details.
|
|
|
|
=cut
|