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
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.
It can only be left out if no info field is returned.
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, or left off, but it
must not be left off if the info field follows it. 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
or is left off, then the drop file ownership is not checked or set.
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.
- The authentication module should only ever return one line, in response to
any query.
- 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.
- If 'info' is returned then uid must also 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 (or left off if no info field is returned).
- 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.
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.
- -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.
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!
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
|
