path: root/doc/pixie-dixie.texi

@macro pixie
@samp{Pixie}
@end macro

@macro dixie
@samp{Dixie}
@end macro

@itemize @bullet
@item Introduction

This document describes a new scheme for client authentication and
authorization in GNU Anubis 4.x.

@item Task Description

So far the only authentication method used by Anubis was based on the
@uref{ftp://ftp.rfc-editor.org/@/in-notes/@/rfc1413.txt,AUTH protocol (RFC 1413)},
and thus required client party to use a popular daemon
@command{identd}, which listens on TCP port 113 for authentication requests. As
its primary advantage, this method allows to quickly identify whom the server
had to deal with, i.e. to obtain user name or his UID. Actually, the
authentication process finishes before the client sends over his first
byte. Besides, this method allows to process the entire SMTP envelope.
It has, however, several drawbacks, first of them being the
requirement to run @command{identd} on the client machine, which is
not always possible (e.g. on mobile devices), and may be considered
harmful for the system security (due to sending user @acronym{ID} over
the wire).

@item The Proposed Solution

Proposed are two operation modes:

@enumerate 1
@item @dfn{Traditional} or @dfn{transparent} (also known as @dfn{Pixie} ;-)
@item @dfn{Authentication first} (also known as @dfn{Dixie} ;-)
@end enumerate

A short description of each mode follows:

@itemize @minus
@item @pixie{} mode
@itemize @minus
@item Server requires the remote party to authenticate itself using
@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2554.txt,SMTP AUTH (RFC 2554)}.
@item Early processing of SMTP envelope is possible. @FIXME{How early,
actually? Both commands and headers are processed when the entire
message contents is read (at least in 3.9x branch. So there's not such
a big difference, except that @command{if command[EHLO]...} will not
work. I'd put a footnote here explaining that.}
@item Connections between MUA and MTA are tunneled ``on the fly''
@end itemize

@item @dixie{} mode
In this mode GNU Anubis runs its own user database, additionally
translating logins (@pxref{login translation}). It also is able to keep
users' configuration files (an additional option and an advantage ---
@pxref{anubis database}).
@end itemize

Users are authenticated using ESMTP AUTH protocol. Early processing
of SMTP envelope is not possible in this mode @FIXME{See the previous
note}, instead it becomes
possible only after the authentication is finished successfully. This mode
also delays connecting to the MTA, since Anubis first has to perform
ESMTP AUTH, and only after finishing authentication, does
it read and process the user's configuration file and connects to the
selected MTA. Of course, the client is not able to begin sending
messages until he is authenticated and accepted by Anubis.

@item Details

There is a great difference between the two modes. To begin with,
@pixie{} mode provides a tunnel (or proxy), in the sense that Anubis
connects user's MUA to the remote MTA without requiring any
special actions from the user. 

Let's consider a simple interaction between @samp{Machine-A}, which runs
Anubis 4, and @samp{Machine-B}, where MUA is run.

@smallexample
@group
A: 220 Machine-A (GNU Anubis vX.X [Dixie]) ESMTP time; send your identity!
B: EHLO Machine-B
A: 250-Machine-A Hello ID
250-STARTTLS
250-AUTH DIGEST-MD5 CRAM-MD5 LOGIN
250-XDATABASE
250 HELP
B: STARTTLS
A: 220 2.0.0 Ready to start TLS
<TLS>
B: AUTH <METHOD>
[method-specific authentication interchange follows]
@end group
@end smallexample

Now, the Anubis server has authenticated the client using data from
Anubis database! @anchor{anubis database}I'd like this database to
contain, beside the user name and password, the name and password of
this user on Machine-A. 

Confusing? Let's suppose that the database contains following record:

@smallexample
@cartouche
 JohnSmith encrypted-pass-1  John 
@end cartouche
@end smallexample

@anchor{login translation}
The user has authenticated himself as @samp{JohnSmith} with password
@samp{encrypted-pass-1}, using ESMTP AUTH, and the given credentials
matched those from the Anubis database. 
Now, Anubis, which has been running with super-user privileges,
switches to @acronym{UID} of the user @samp{John}.

Such solution will allow for a very flexible database,
that would ease the administration tasks, since users will be able to update
their corresponding records (of course, if the system administrator
grants them such privileges). For instance, @acronym{ODBC}, @acronym{SQL}?

Let's return to our sample session. After successful authentication
and switching to the user's privileges, Anubis parses
file @file{~/.anubisrc}. Then, based on user's configuration settings, it
connects to the MTA and from then on operates as SMTP tunnel and mail
processor :-). It sends the following response to @samp{Machine-B}:

@smallexample
A: 220 OK, Welcome. Continue sending your mail!
@end smallexample

@item Further details

The above description shows that it is impossible to use both
@pixie{} and @dixie{} simultaneously. It is the responsibility of
the system administrator to decide which operation mode to use. We could
probably provide for a smooth switching between the two modes, without
requiring to restart the daemon... However, it is not critical.
Restarting the daemon in order to switch to another operation mode is also
a feasible solution.

Now, let me describe for what kind of users each mode is intended.

The traditional (@pixie{}) mode is intended for those users who use
Anubis on a single machine or within a local network that allows
to use @command{identd}. In short, @pixie{} is useful when the use of
@command{identd} is possible and safe.

In contrast, the new mode @dixie{} is intended for more complex
setups, where a single machine running GNU Anubis serves a number
of clients connecting from different machines and networks. It
is supposed that no client machine is running @command{identd}.
The only recommendation for this mode is that each user have a system
account on the machine running Anubis. But then, even this is
not required!

That's a feature I haven't described yet :^) As described above, Anubis
database must contain second login name in order for Anubis to be able to
switch to the user's privileges and parse his @file{~/.anubisrc} file.
Now, I supposed that the database is able to keep user configuration files
as well. So, each database record must contain an additional
flag informing Anubis whether it should read the local file
@file{~/.anubisrc}, or read the configuration file stored in the
database. Sure enough, GNU Anubis still will have to switch
to the user's privileges, for security reasons, but this
can be done using usual @code{user-notprivileged} configuration
(@pxref{Security Settings, user-notprivileged}).

Surely you have noticed that in its response to EHLO command
Dixie returned @code{250-XDATABASE} capability. Yes, this is exactly
that command that I'd like to be used for remote management of
the database records (after having successfully passed ESMTP AUTH).

Available operations are: @code{ADD}, @code{MODIFY}, @code{REMOVE}, meaning
addition, modification and removal of a user record, and
@code{UPLOAD}, providing a way to upload the user's configuration
file @file{~/.anubisrc}.

This solution will free the users from the obligation to have
@file{~/.anubisrc} on the server machine, so they, for the first time 
since early Anubis versions, will be able to have their @emph{own}
configuration files. Current versions (@FIXME{up to version 3.6.2}) require
that the user configuration file be stored on the server machine
before the user is able to use the service. This approach requires a
certain attention from the system administrator. Should the user
wish to change something in his configuration file, he would have
to install the modified file on @samp{Machine-A} (that's how it works now,
and that's how it will continue to work for @pixie{} mode). The new
@dixie{} mode solves this and frees the user from necessity to
contact the system administrator of @samp{Machine-A}. The Anubis database
engine is supposed to check the correctness of the uploaded
configuration file and inform the client about the result. It also
should compute MD5 hash of the file and compare it to the one
sent by the user... What for?

@item A program sending user's configuration file

Well, we're almost finished. The user will have a small program,
@command{config-sender}, written in whatever language (C, Java, C#),
whose main purpose is to send user's configuration file to the
database. Such a program could even be installed on a mobile device!
Notice also, that this program is optional, the user is not required
to use it. I envision a situation where:

@enumerate 1
@item A user logs in to his account on @samp{Machine-B}
@item His @file{~/.profile} invokes @command{config-sender} program. This
program, in turn, computes MD5 sum of the local @file{~/.anubisrc}
file and sends it to Anubis. There it will be compared to the sum
kept in the Anubis database, and if the two sums differ, the
@command{config-sender} will upload the contents of
@file{~/.anubisrc}... @footnote{The scheme implemented currently is
a bit different. First, the @command{config-sender} program issues
an @code{EXAMINE} command that fetches the contents of the user
configuration file from the server. Then, it compares it with the
local copy kept on the client machine. If the copies differ,
@command{config-sender} issues @code{UPLOAD} and thus updates
the configuration on the server.}

@item The @command{config-sender} program will, of course, connect to the Anubis
database using ESMTP (TLS/AUTH) and @code{XDATABASE}.
@end enumerate

Such a program will be an additional advantage, since
no existing MUA is, of course, able to use @code{XDATABASE} command to
manage Anubis database. Notice however, that
@uref{http://savannah.gnu.org/projects/hydrant,GNU Hydrant} will probably
support @code{XDATABASE} in the future...

@item The End.

Thus, the user will simply use his MUA, no identd, no hassle :)

Actually, the only requirement for the MUA is that it support ESMTP
AUTH. Unfortunately, some MUA, even on UNIX-like systems, are still
not able to use ESMTP AUTH. But in this case,
the user can install Anubis on his machine and use it to perform
authentication ;-))) 

And the last detail: what to do if the remote MTA also requires ESMTP
AUTH? The answer is quite simple: GNU Anubis is already able to handle
this (@pxref{Basic Settings,esmtp-auth}).

@item Summary (@dixie{} mode)

@itemize @minus
@item a little slower than @pixie{}, in the sense that the actual connection
to the MTA is established only after successful authentication
@item does not require @command{identd}!
@item allows the user full control over his configuration settings
@item delays processing of SMTP envelope until after successful
authentication.
@end itemize

@item PS: A couple of words about storing configuration files in the database...

These can be stored in a special directory as usual files, then each
database record will have an additional field with the name of the
configuration file for the given user.
@end itemize

       --- THE END ---