Vetinari's $HOME


Authentication framework for qpsmtpd


Provides support for SMTP AUTH within qpsmtpd transactions, see

for more details.


This code is automatically loaded by Qpsmtpd::SMTP only if a plugin providing one of the defined "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.

Plugin Design

An authentication plugin can bind to one or more auth hooks or bind to all of them at once. See "Multiple Hook Behavior" for more details.

All plugins must provide two functions:

Plugins should perform whatever checking they want and then return one of the following values (taken from Qpsmtpd::Constants):


If the authentication has succeeded, the plugin can return this value and all subsequently registered hooks will be skipped.


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).


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 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.

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) helpfully hide this information under the default configuration. This message will be logged locally, if appropriate, based on the configured log level.

Auth Hooks

The currently defined authentication methods are:

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.


John Peacock <>


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.