Authentication Protocol

Various NetWin Ltd products 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 protocol is broken up in two main sections:

Simple Authentication Protocol

All external authentication modules are required to support these commands.

Extended Authentication Protocol

This includes other commands which we recommend your authentication module should implement. These allow for much easier user administration (including adding users) via external utilities.

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.

Contents

Simple Authentication Protocol

Notes on the Definition

Extended Authentication Protocol

Command prompt commands that should be supported

Examples
Module list and Supported Commands

Simple Authentication Protocol

The application that is the external authentication module must read commands from standard in and write replies to standard out. Note: Not all applications will use all the information that the reply returns.

Every command within the external authentication module can give one of four responses:

+DATA
A command can return one or more '+data' responses where, the information asked for was successfull and it is returning multiple information. The module MUST still return '+OK' once all the '+DATA' information has been sent.

+OK
This implies that the command was successful.

-ERR
This is a failed result. Which can mean that the the user doesn't exist if a check is preformed. Or the data inputted is invalid. It can also provide extra information after the '-ERR'.

The total response text SHOULD be less than 100 bytes.

-DEAD
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 or the module has not been correctly setup.

The total response text SHOULD be less than 100 bytes.

IMPORTANT: Immediately following the +OK, -ERR and -DEAD response tag should come the username exactly as given by the command, this allows applications to verify commands and responses stay in sync. The exception to this rule is a command which does not involve a specific username, for example; search, quit, exit, version, verbose. +DATA is also expected to be followed immediately by the username (or result) but is not used to check things are in sync.

The three basic commands are:

exit

Response: +OK successfull

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

check username password [fromIPaddress]

Response:
+OK username drop_file_path uid [info]
-ERR username reason
-DEAD username reason

username:
The username with optional prefix or suffix to indicate the users domain.
This is generally in the form that the user is to be known by in the user database. This can also be case sensitive.
Some applications will add on '@domain' as a suffix to the username if they have been setup to do so.

password: The users password. This password is case sensitive and the application might have already lowercased the password before it's passed to the external module.

fromIPaddress: The IP address from which the user connected. This is optional, but if given the external module should check against an IPMask. If it does not match then it should return back:
-err ipmask failed

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

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.

info:
Any additional fields that you wish to have. In the layout:

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

lookup username

Response: +OK username drop_file_path uid [info]
-ERR username reason
-DEAD username reason

username:
The username with optional prefix or suffix to indicate the users domain.
This is generally in the form that the user is to be known by in the user database. This can also be case sensitive.
Some applications will add on '@domain' as a suffix to the username if they have been setup to do so.

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 users drop path from the relevant settings it has.

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.

info:
Any additional fields that you wish to have. In the layout:

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

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

Extended Authentication Protocol

The following is a list of extened Authentication command, the following are optional, but if you can set these up you should.

set username [password [info]]

Response:
+OK username [message]
-ERR username reason
-DEAD username reason

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. This can also be case sensitive.
Some applications will add on '@domain' as a suffix to the username if they have been setup to do so.

password: The users password. This password is case sensitive and application might have already lowercased the password before it's passed to the external module.
If the password is given as '(NULL)' then the users info field information is altered only (the password is not changed).

info:
Any additional fields that you wish to have. In the layout:

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

message: The message is optional,
"user x data updated"

Use this command to ADD or MODIFY a user.
NB: NO warning is given if you are overwriting an existing user.

del username

Response:
+OK username [message]
-ERR username reason
-DEAD username reason

username:
The username with optional prefix or suffix to indicate the users domain.
This is generally in the form that the user is to be known by in the user database. This can also be case sensitive.
Some applications will add on '@domain' as a suffix to the username if they have been setup to do so.

message: The message is optional,
"+OK Deleted user successfully"

search string [-from <x>] [-max <n>]

Response:
+DATA username [info]
+OK [message]
-ERR username reason
-DEAD username reason

search:
This is the search on the username which can continue '*' and '?' wildcards. Also some external module might have limits on the minimum number of character that are allowed. (ie: 3)

-from:
-max:
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.

username:
The username with optional prefix or suffix to indicate the users domain.
This is generally in the form that the user is to be known by in the user database. This can also be case sensitive.
Some applications will add on '@domain' as a suffix to the username if they have been setup to do so.

info:
Any additional fields that you wish to have. In the layout:

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

message: The message is optional,
"+OK X out of Y results found"

NOTE: SurgeMail will look for the text "out of" in the +OK response, if found it will attempt to locate X and Y and use these values for display purposes. This information is optional and if it requires significant processing to obtain then it's probably best not to include it.

Command prompt commands that should be supported
The external authentication module should not only support all of the commands to be run in interactive mode but also it supports them all run in command line mode, eg:
\dmail\nwauth -lookup bob
+OK bob config 0
The syntax is generally,
NWAuth -command cmd1_param1 cmd1_param2 
Examples
NWAuth is our example of authentication module code, see NWAuth Code . You will also find the version of nwauth.c in most of NetWin Ltd applications which supports external authentication.

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
Module list and Supported Commands

Simple Authentication Protocol Extended Authentication Protocol Other

Module
Check

Lookup

Exit

Set

Delete

Search

Help

Quit
Version Verbose

NWAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

UnixAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

NTAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

LDAPAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

MySQLAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

MultiAuth
Y

Y

Y

Y

Y

Y

Y

Y

OracleAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

PAMAuth
Y

Y

Y

Y

Y

Y

Y

Y

RadiusAuth
Y

Y*

Y

Y

Y

DNAuth
Y

Y

Y

ODBCAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

TCPAuth
Y

Y

Y

Y

Y

Y

Y

Y

Y

POPAuth
Y

Y

Y

+DATA	A command can return one or more '+data' responses where, the information asked for was successfull and it is returning multiple information. The module MUST still return '+OK' once all the '+DATA' information has been sent.
+OK	This implies that the command was successful.
-ERR	This is a failed result. Which can mean that the the user doesn't exist if a check is preformed. Or the data inputted is invalid. It can also provide extra information after the '-ERR'. The total response text SHOULD be less than 100 bytes.
-DEAD	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 or the module has not been correctly setup. The total response text SHOULD be less than 100 bytes.

	Simple Authentication Protocol			Extended Authentication Protocol				Other
Module	Check	Lookup	Exit	Set	Delete	Search	Help	Quit	Version	Verbose
NWAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
UnixAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
NTAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
LDAPAuth	Y	Y	Y	Y	Y	Y	Y	Y		Y
MySQLAuth	Y	Y	Y	Y	Y	Y	Y	Y		Y
MultiAuth	Y	Y	Y	Y	Y	Y		Y	Y
OracleAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
PAMAuth	Y	Y	Y	Y			Y	Y	Y	Y
RadiusAuth	Y	Y*	Y					Y		Y
DNAuth	Y	Y	Y
ODBCAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
TCPAuth	Y	Y	Y	Y	Y	Y	Y	Y	Y
POPAuth	Y	Y	Y