qpsmtpd Wiki


You are here: start » api » plugin_auth


You are currently not logged in! Enter your authentication credentials below to log in. You need to have cookies enabled to log in.


You don't have an account yet? Just get one: Register

Forgotten your password? Get a new one: Set new password

Authentication API framework for qpsmtpd

The authentication API framework provides support for SMTP AUTH within qpsmtpd transactions, see RFC2222 and RFC2554 for more details.


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

Plug-in Design

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

All plugins must provide two functions:


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.


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:


A Qpsmtpd::Plugin object, which can be used, for example, to emit log entries or to send responses to the remote SMTP client.


A Qpsmtpd::Transaction object which can be used to examine information about the current SMTP session like the remote IP address.


The lower-case name of the authentication mechanism requested by the client; either “plain”, “login”, or “cram-md5”.


Whatever the remote SMTP client sent to identify the user (may be bare name or fully qualified e-mail address).


If the particular authentication method supports unencrypted passwords (currently PLAIN and LOGIN), which will be the plaintext password sent by the remote SMTP client.


An encrypted form of the remote user's password, using the MD-5 algorithm (see also the $ticket parameter).


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.

Plug-in return codes

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) I<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:


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.


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


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


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

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.