DMail's External Authentication Protocol

As supported by NWAuth :-)

The DMail servers allow use of an External Authentication module to provide for interaction with any type of user database. The external authentication module is run as a sub process and accepts commands from the server on stdin and returns replies on stdout.

The Simple Authentication Protocol consists of the commands that are necessary for the dmail system to work.

The Extended Authentication Protocol includes other commands which we recommend your authentication module should implement. These allow for much easier user administration (including adding users) via utilities like our DMAdmin (windows GUI tool) or NetAuth (web based administration tool).

Our "standard" NWAuth module also has a number of other commands (mostly only operative from the command line) which are useful for things like, debugging, converting from other systems etc. So, on this page:

Definition of Simple Authentication Protocol
Notes on the Definition
Info Fields supported by DMail
Definition of Extended Authentication Protocol
Other commands that NWAuth supports
Examples

1. Definition of Simple Authentication Protocol

The application that is the external authentication module must read commands from standard in and write replies to standard out. The commands and replies defined allow the same system to be used by both DPOP and DSMTP. Note some parts of the reply are not needed for DPOP.

The only three input commands are:

exit
check   username   password   [fromIPaddress] 
lookup   username 
(lookup - is used when drop file path is needed but user is not connecting so the password does not need checking)

The replies are

```
+OK
```

+OK    username  drop_file_path  uid  [info]
or
-ERR   reason    (less than 100 bytes)

+OK    username  drop_file_path  uid  [info]
or
-ERR   reason    (less than 100 bytes)

NB: UID can be given as 0 on systems which don't require a uid, similarly the drop_file_path can be given as 'config'. They can not be left out.

Command Details:

exit:

The exit input tells the external authentication program to shutdown. It should respond with +OK.

check:

username: The username with optional prefix or suffix to indicate the user's domain.
This is generally in the form that the user is to be known by in the user database.
The main part of the name is taken from the username that the user used to login to DPOP or from the username of the destination address that DSMTP is looking up.
DMail adds on '@domain' as a suffix to the username if you have set the dmail.conf setting, authent_domain true.
The domain name that it uses is taken from the dpop_host setting or the first host_domain setting if the user belongs to the main domain. If the user belongs to a virtual domain then the domain is taken from the matching virtual domain line, vdomain, in the configuration file.
See notes below.

password: The password that the user used to connect to DMail (may be lowercased if lowercase_password is set in dmail.conf)

fromIPaddress: The IP address from which the user connected is optional, but is sent by DPOP.

lookup:

The lookup input is as per the check input. It is used when the drop file path is needed but the user is not connecting, so the password does not need to be checked.

Response Details:

+OK userdetails

-ERR reason

+OK: Implies command was successful. It will be returned by itself for the exit command.. If a user lookup or check has been successful it will be returned with the following information about the user attached.

username: Must match that given in lookup or check command, otherwise servers report "external authentication out of sync".

drop_file_path: Full path to the dropfile, including filename, for the user OR the word 'config'. The keyword config indicates that the servers should work out the user's drop path from the relevant settings in dmail.conf (i.e. drop_path + hash_spool or vdomain + hash_spool + drop_prefix + vdomain separator).

uid: User ID, can be a number or a name or zero, but it must not be left off. If a number, then UNIX uses that uid number when it checks the ownership of the drop file. If a name, then DPOP/DSMTP looks up that name in the UNIX password file and uses the corresponding uid. If uid is the number 0, then the drop file ownership is not checked or set.
Note: this manual used to erroneously say that the uid could be left off if no info field was returned.

info: Any additional fields that you wish to have.

These should have the syntax,

field1_name="value1" field2_name="value2" ...

See Info Fields supported by DMail

-ERR reason

The error reply, giving a reason, which is less than 100 bytes in length.

2. Notes on the Definition

The authentication module should only ever return one line, in response to any query. The only exception to this is the search command in the extended protocol where a number of +DATA lines are returned.

The @domain suffix to the username is only sent by DPOP and DSMTP if the configuration file contains line: authent_domain true

The returned drop file path must contain the full path and filename of the drop file for that user.

If any directory hashing is required it must be included in the returned drop_file_path string.

The info field is not used by DPOP (only by DSMTP) and may be left blank if not required.

The uid field must always be returned.

If the normal drop file path specified in the configuration file is to be used then the drop file path in the response may be replaced by the single word config

The uid is used to set/check user ownership of drop files.

The uid returned may be numeric or an alphanumeric username.

If no uid checking/setting for drop files is to be used then the uid returned can be 0.

Currently the protocol does not support spaces in usernames. If you require this then please contact DMail Support.
The maximum length of any response is 1000 characters in total.
The @domain passed as part or the username can often be ignored. It is to allow for the use of virtual domains where a single DPOP server responds to connections to several IP addresses. In this case two users with the same username but who read their mail from different domains may connect to DPOP. See virtual domains for more details.

3. Info Fields supported by DMail

The servers of DMail support the following fields (field_name="value") in the 'info'

Field Name: fwd
Example: fwd="$USER,fred@domain2.com,|d:\dmail\robot.c"
This field specifies alternate destinations for any messages accepted by DSMTP for the looked up user. This field must be returned in response to the lookup command as DSMTP is the only server to use it.

No fwd field or an empty fwd field (fwd="") indicates that usual delivery shall occur.

Multiple destinations can be specified using comma separation.

Any destination specified indicates that the original destination shall NOT receive the message. Use the key destination, '$USER' as one of the destinations in the comma separated list to indicate that the original recipient should still receive the message.
Field Name: quota
Syntax: quota="<num>[K|k|M|m]" (default in bytes)
Example: quota="5000k"
This is new to version 2.7m. Returning this field in response to a lookup command tells dsmtp to use the specified individual quota for the user looked up.

The quota will only be applied if the quota system is turned on with the setting, user_quota. This setting overridden by any setting specified in the users _inf file.

No quota field or an empty quota field indicates that DSMTP should use the either the default quota value as set by the user_quota setting or the individual limit set in the user's _inf file.

4. Definition of Extended Authentication Protocol

-DEAD [message]
In addition to the +OK and -ERR responses the authentication module can now also return the -DEAD response with an accompanying message (version 2.5d and above).
This response should be returned if for any reason the authentication module is temporarily unable to respond. For example if the user database to which the module connects is down.
If DSMTP gets this response, it gives the sender a 400 level response (e.g. 450 Command RCPT User not OK. User database is down.), rather than a 500 level response to indicate that they should try sending again later. DPOP simply does not allow the user to login and passes the [message] back, so you should make the message something that you want the user to read.
```
set user [password [info]]
```
Response:
```
+OK  [message]
or
-ERR  [message]
```
or -DEAD [message]

The message is optional, nwauth states, "user x added to database"
Use this command to ADD or MODIFY a user.
NB: NO warning is given if you are overwriting an existing user.
If the password is given as '(NULL)' then the users info field information is altered only (the password is not changed).
```
mod user info
```
Response:
```
+OK  [message]
or
-ERR  [message]
```
or -DEAD [message]

Use this to modify a user's info fields without needing a password. The message is optional, nwauth states, "user x added to database"
```
del user
```
Response:
```
+OK  [message]
or
-ERR  [message]
```
or -DEAD [message]

Use this to delete a user from the database. The message is optional, nwauth states, "+OK Deleted user successfully"
```
search  string 
```
Response:
```
+DATA  username  info 
```
```
+DATA  username  info 
```
```
...
```
```
+OK Search Complete x items found
```
Notes:
string can be any piece of text found in the username or info fields (not in the password field).

The string '*' if supported indicates that ALL database entries should be listed. Other than that the wildcard character is not supported.
In version 2.0s of nwauth we have added,
```
search  string  [-from <x>] [-max <n>]
```
where -max limits the maximum number of search results to be returned to n and
-from causes results to be displayed starting at the x'th match.

5. Other commands that NWAuth supports

NWAuth supports all of the commands above run in interactive mode but also it supports them all run in command line mode, e.g.

\dmail\nwauth -lookup bob

+OK bob config 0

The syntax is generally,

nwauth -command cmd1_param1 cmd1_param2

Run

nwauth -help

for more information.

Extra commands at the command line (i.e. not supported in interactive mode):

nwauth -encrypt user/all (encrypts the password of a given user, or encrypts all passwords in the nwauth.txt file not already encrypted).

Extra switches at the command line:

nwauth -size x -... (sets max size of nwauth.add)

nwauth -log -... (turns on logging to nwauth.log)

nwauth -sleep x y (testing option, sleep for y seconds first and every x th response)

Notes on what NWAuth supports/does not support:

NWAuth currently only ever responds with +OK User deleted successfully to the del command, if it cannot edit its nwauth.add file then it does not respond at all!

6. Examples

NWAuth is our example of authentication module code, see NWAuth Code . You will also find the version of nwauth.c in your distribution set which matches your version.

Set:

\dmail\nwauth

set bob password

+OK bob added to database

set fred pass fwd="$USER,bob"

+OK fred added to database

exit

Set: command line mode

\dmail\nwauth -set bob password

+OK bob added to database