3 Authentication

When GNU Anubis accepts incoming connection, it first has to identify the remote party, i.e. to determine whether it is authorised to use Anubis resources and, if so, what configuration settings to use during the session. We call this process authentication. The exact method of authentication depends on Anubis operation mode. Currently there are three modes:

proxy

No authentication is performed. Anubis switches to the unprivileged user (see section user-unprivileged) and acts as an SMTP proxy.

transparent

Anubis relies on AUTH service (identd) to authenticate users. This is the default mode. It is compatible with versions of GNU Anubis up to 3.6.2.

auth

This mode uses SMTP AUTH mechanism to authenticate incoming connections. See section Pixie & Dixie, the original description of this mode.

Proxy mode is special in that no authentication is performed in it. The remaining two modes require authentication. Both have their advantages and deficiencies, which you need to weigh carefully before choosing which one to use. They are discussed below:

Transparent (‘traditional’) mode.

Deficiencies:

1. The user must have identd installed on his machine.
2. The user must have a system account on the machine running GNU Anubis (though the system administrator may relax this limitation by using user name translation, see section TRANSLATION Section).

Advantages:

1. Relative simplicity. No user database is necessary.
2. Authentication is performed immediately after connection is established.

Auth mode.

Deficiencies:

1. A user database is needed
2. MUAs of the users must be able to perform ESMTP AUTH.(1)

Advantages:

1. Improved reliability.
2. Users do not have to run identd on their machines.
3. Users are not required to have accounts on the machine where Anubis runs.
4. Users can remotely modify their configuration files.

3.1 Auth Service

Anubis session in traditional mode begins by querying auth service on the client machine in order to obtain system name of the user that initiated the session. Some identd servers are able to encrypt sensitive information in their replies. Anubus supports encryption protocol introduced by pidentd server (2). If some of your clients implement encryption, you would need the DES key (or keys) they use for that purpose. Each such key is a sequence of 1024 bytes. Store them in a file and ensure its ownership and mode prevent dissemination of this information. Any number of keys can be stored.

Once done, inform anubis about location of this file by placing the following statement in the CONTROL section of your configuration file:

identd-keyfile filename

(replace filename with the actual name of the file).

3.2 User Database

A User Database is a storage system where GNU Anubis keeps user credentials, i.e. data necessary for authenticating and authorizing users. The exact way of storing these data is described further in this manual. In this section we treat user database as an abstraction layer.

The user database consists of records. Each record keeps information about a particular user. A record consists of four fields. A field may contain some value, or be empty, in which case we say that it has null value.

The fields are:

SMTP AUTHID

SMTP authentication ID of the user.

AUTH PASSWORD

SMTP password.

ACCOUNT

System user name.

CONFIG

Path to the configuration file.

The first two fields are mandatory and must always have non-null values. No two records in the database may have the same value of SMTP AUTHID field. When anubis is trying to authenticate a user, it first looks up in the database a record with the value of SMTP AUTHID field matching AUTHID given by the user. If no such entry is found, authentication fails. Otherwise, anubis goes on and compares the password supplied by the user with that from AUTH PASSWORD field. If they match, authentication succeeds and anubis passes to authorization state.

In this state, it first determines the user ID (UID) to switch to. If the ACCOUNT field is not null, its value is used as account login name. If it is null, anubis will use privileges of the default not privileged user, specified by user-notprivileged statement in the global configuration file (see section user-notprivileged).

The final step is to parse the user configuration file. If CONFIG field is not null, its value is the absolute pathname of the user configuration file. Otherwise, anubis searches for file ‘~/.anubisrc’ (where ‘~’ denotes home directory for the system account obtained on the previous step) and if such a file exists, loads it.

3.3 Database URL

Anubis database is identified by its URL, or Universal Resource Locator. A URL consists of following elements (square brackets enclose optional ones):

proto://[[user[:password]@]host]/path[params]

where:

proto

Specifies the database protocol. The protocol describes how to access the database. In a way, it may be regarded as specifying the database type. Currently, GNU Anubis supports the following database protocols:

‘text’	A plain text file with users’ credentials.
‘gdbm’	GDBM database
‘mysql’	MySQL database
‘pgsql’	PostgreSQL database
‘postgres’	Alias for ‘pgsql’.

These protocols are described in detail below.

user

The name of the user authorized to access the database.

password

Password for the above user.

host

Domain name or IP address of a machine running the database.

path

A path to the database. The exact meaning of this element depends on the database protocol. It is described in detail when discussing particular protocols.

params

A list of protocol-dependent parameters. Each parameter consists of the parameter name, or keyword and its value separated by a equals sign:

keyword=name

Multiple parameters are separated by semicolons.

3.3.1 Plain text databases

A simplest database is a plain text file, with lines representing records. Empty lines and lines beginning with ‘#’ (comments) sign are ignored. A record consists of fields, separated by colons (‘:’, ASCII 58). If ‘:’ character occurs as a part of a field, it must be escaped by a single backslash character (‘\\’, ASCII 92). Each record must contain at least two and no more than four fields:

1. SMTP ‘AUTHID’.
2. SMTP password.
3. Account name.
4. Pathname of the user configuration file.

URL syntax

The URL syntax for this type of databases is quite simple:

text:path

where path specifies absolute file name of the database file.

3.3.2 Databases in GDBM format

The protocol value ‘gdbm’ specifies a GDBM database. For the detailed description of GDBM system Introduction in The GNU DBM Manual.

Technically speaking, each GDBM record consists of a key and content. Its key holds the value of SMTP ‘AUTHID’, whereas its content holds SMTP password, system account name and path to user configuration file, separated by commas. As it was with ‘text’ databases, the two last fields are optional.

The URL syntax for GDBM databases is:

gdbm:path

where path specifies absolute file name of the database file.

3.3.3 MySQL and PostgreSQL

This is the most flexible database format. GNU Anubis 4.3 supports MySQL(3) and PostgreSQL(4) interfaces. No matter which of them you use, the implementation details are hidden behind a single consistent Anubis interface.

GNU Anubis supposes that all user data are kept in a single database table. This table must have at least four columns for storing SMTP ‘AUTHID’, SMTP password, system account name and path to user configuration file. Among those, only the last two may have NULL values. There is no restriction on the name of the database or the authentication table, nor on its column names. This information may be specified in URL as discussed below.

URL syntax

proto://[[user[:password]@]host/]dbname[params]

Proto describes the database type to use. Use ‘mysql’ for MySQL databases and ‘pgsql’ or ‘postgres’ for PostgreSQL databases.

Optional user and password specify authentication credentials for accessing the database.

Host sets the domain name or IP address of the machine running the database. It may be omitted if the database resides on ‘localhost’.

The database name is specified by the dbname element.

Further details needed for connecting to the database are given by URL parameters. All of them have reasonable default values, so you’ll have to specify only those parameters that differ from the default. The following parameters are defined:

‘port=number’

Specifies port number the database server is listening on. If it is not given, the behavior depends on the value of the ‘socket’ parameter (see below). If ‘socket’ is not present, the program will use the default port number for the given protocol (i.e. 3306 for ‘mysql’ and 5432 for ‘pgsql’.

‘socket=string’

Specifies the UNIX file name of the socket to connect to. This parameter cannot be used together with ‘port’ (see above).

‘bufsize=number’

Sets length of the buffer for storing SQL queries. Default is 1024 bytes.

‘table=string’

Specifies name of the database table with the authentication data. Default is ‘users’.

‘authid=string’

Specifies the name of a column in ‘table’ which holds ‘AUTHID’ value. Default is ‘authid’.

‘passwd=string’

Specifies the name of a column in ‘table’ which holds the user password. Default is ‘passwd’.

‘account=string’

Specifies the name of a column in ‘table’ which holds the name of system account to be used for this ‘AUTHID’. Default is ‘account’.

‘rcfile=string’

Specifies the name of a column in ‘table’ which holds the path to the user’s configuration file. Default is ‘rcfile’.

When using a MySQL database (‘mysql://’), database parameters and access credentials are first read from the file ‘/etc/my.cnf’, if it exists. This file called option file in ‘MySQL’ parlance (see option files). is organized in groups, each group beginning with the group name in square brackets on a separate line. Within a group, each non-empty line consists of a MySQL option name, optionally followed by an equals sign and the value. By default, settings from the group named ‘anubis’ are read.

Two additional parameters are provided to fine-tune this behavior:

‘options-file=file’

Read options from file instead of ‘/etc/my.cnf’. An empty value (‘options-file=’), disables using the options file.

‘options-group=name’

Set the name of the group in the MySQL configuration file, from which to read configuration options.

3.4 Managing the Database

Managing the user database is a complex task, which looks differently from administrator’s and user’s point of view. Administrators have all privileges on the database, they can add new records and delete or modify existing ones. Users, of course, do not have such ample rights. The only thing a user is able to do is to maintain his own record in the database, provided that he already has one.

3.4.1 Administrators

All administrative tasks are done via the anubisadm command — a multipurpose tool for Anubis administrators.

The command usage syntax is:

anubisadm command [options] database-url

where command specifies the operation to be performed on the database, options give additional operation-specific parameters, and database-url specifies the database to operate upon.

All administrative tasks can be subdivided into the following five categories:

• Creating the Database
• Listing Database Records
• Adding New Records
• Removing Existing Records
• Modifying Existing Records

3.4.1.1 Creating the Database

To create a database, use anubisadm --create (or anubisadm -c). Anubisadm will read database entries from the standard input and write them to the database. The standard input is supposed to be formatted as a text database (see section Plain text databases).

For example, to create a GDBM database from plain text file ‘userlist’, use the following command

anubisadm --create gdbm:/etc/anubis.db < userlist

Similarly, to create an initially empty database, type

anubisadm --create gdbm:/etc/anubis.db < /dev/null

Notice, that if you use SQL database format, ‘--create’ command does not imply creating the database structure! So, before running

anubisadm --create mysql://localhost/dbname < userlist

make sure you create the underlying database structure (including granting privileges to the anubis user), via the usual procedure. Please refer to corresponding database manual for the detailed instructions on this.

It is sometimes necessary to convert an existing user database from one format (protocol) to another. For example, suppose you have been running GDBM database (text:/etc/anubis.db) for some time, but now it has grown so big that you decided to switch to PostgreSQL database to improve performance. To do so, first create the database using postgres utilities. Then run

anubisadm --list text:/etc/anubis.db | \
 anubisadm --create pgsql://localhost/dbname

That’s all there is to it!

3.4.1.2 Listing Database Records

The ‘--list’ (or ‘-l’) option lists the existing database:

anubisadm --list gdbm:/etc/anubis.db

By default it displays all records from the database.

Among its other uses, such invocation is handy for converting user database to another format (see section Creating the Database).

If you wish to list only a particular record, specify the AUTHID using ‘--authid’ (‘-i’) option. For example, to list the record for AUTHID ‘test’, type:

example$ anubisadm --list --authid test gdbm:/etc/anubis.db

3.4.1.3 Adding New Records

To add a new record use the ‘--add’ (‘-a’) option. Additional data are specified via the following options:

‘-i string’

‘--authid=string’

Specify the user SMTP AUTHID.

‘-p string’

‘--password=string’

Specify the user password.

‘-u string’

‘--user=string’

Specify the system user name for this AUTHID.

‘-f string’

‘--rcfile=string’

Specify configuration file to be used for this user.

For example, the following command adds a record with SMTP AUTHID ‘test’, password ‘guessme’ and maps it to the system account ‘gray’:

anubisadm --add --authid test --password guessme \
          --user gray gdbm:/etc/anubis.db

3.4.1.4 Removing Existing Records

Removing a record is quite straightforward: use the ‘--remove’ (‘-r’) option and supply the AUTHID to delete via the ‘--authid’ option. For example, to remove the record created in the previous subsection, run:

anubisadm --remove --authid test gdbm:/etc/anubis.db

3.4.1.5 Modifying Existing Records

To modify an existing record use the ‘--modify’ (‘-m’) option. The record is identified via the ‘--authid’ option. The following options supply the changed values:

‘-p string’

‘--password=string’

Specify new user password.

‘-u string’

‘--user=string’

Specify new system user name for this AUTHID.

‘-f string’

‘--rcfile=string’

Specify the user’s configuration file.

For example, the following command changes the name of configuration file for the user ‘smith’:

anubisadm --authid smith \
          --rcfile=/var/spool/anubis/common gdbm:/etc/anubis.db

3.4.1.6 Summary of All Administrative Commands

• Usage

  anubisadm command [options] database-url
  

• Commands:

  ‘-c’

  ‘--create’

  Create the database.

  ‘-l’

  ‘--list’

  List the contents of an existing database.

  ‘-a’

  ‘--add’

  Add a new record.

  ‘-m’

  ‘--modify’

  Modify an existing record.

  ‘-r’

  ‘--remove’

  Remove an existing record.

  ‘--version’

  Display program version number and exit.

  ‘--help’

  Display short usage summary and exit.

• Options:

  ‘-i string’

  ‘--authid=string’

  Specify the authid to operate upon. This option is mandatory for ‘--add’, ‘--modify’ and ‘--remove’ commands. It may also be used with ‘--list’ command.

  ‘-p string’

  ‘--password=string’

  Specify the password for the authid. This option is mandatory for ‘--add’, ‘--modify’ and ‘--remove’ commands.

  ‘-u string’

  ‘--user=string’

  Specify the system user name corresponding to the given authid. It may be used with ‘--add’, ‘--modify’, and ‘--remove’ commands.

  ‘-f string’

  ‘--rcfile=string’

  Specify the rc file to be used for this authid. The option may be used with ‘--add’, ‘--modify’, and ‘--remove’ commands.

3.4.2 Users

Users maintain their database records via the anubisusr command. This command is built if anubis is configured with TLS support.

We suggest invoking anubisusr from your ‘~/.profile’, which will make sure that your configuration file is up to date when you log in.(5).

Usage

anubisusr [options] [smtp-url]

where smtp-url is a URL of your GNU Anubis server. Notice that if it lacks user name and password, then anubisusr will first try to retrieve them from your ‘~/.netrc’ file (see netrc in netrc manual page), and if not found, it will prompt you to supply them.

Options

‘-m mech’

‘--mechanism mech’

Use the SASL mechanism mech. Give this option several times to set a list of allowed mechanisms.

‘--file=file’

‘-f file’

Sets the user configuration file name (default is ‘.anubisrc’).

‘--netrc+file’

‘-n file’

Sets the name of the automatic login configuration file (default is ‘.netrc’).

‘-v’

‘--verbose’

Verbose output. Multiple options increase verbosity. Maximum verbosity level is 3.

Options controlling encryption:

‘--disable-tls’

‘-d’

Disable the use of TLS encryption.

‘--tls-cafile=file’

‘-C file’

Sets the name of certificate authority file to use when verifying the server certificate.

‘--tls-priorities=list’

Sets cipher suite preferences to use. The list argument may contain a single initial keyword or be a colon-separated list of TLS keywords. The description of TLS keywords is well beyond the scope of this document. Please refer to Priority Strings in GnuTLS Manual, for a detailed discussion.

Default priority list is ‘NORMAL’.

Informational options:

‘--version’

Display program version number and exit.

‘--help’

Display short usage summary and exit.

This document was generated on January 6, 2024 using texi2html 5.0.