| [FrontPage] [TitleIndex] [WordIndex]

# TmdaOfmipdHowto

tmda-ofmipd - an authenticated SMTP proxy for TMDA

Contents

1. What is it?
2. Requirements
3. Authentication
4. Builtin SSL/TLS
5. Running
6. MUA Configuration

## What is it?

tmda-ofmipd allows users of any mail client capable of SMTP Authentication (e.g, Outlook, Eudora, Mozilla) to "tag" their outgoing mail as described in the ClientConfiguration section.

In this document, mail clients are referred to as an MUA, which stands for "Mail User Agent". The name ofmip stands for "Old Fashioned Mail Injection Protocol"

tmda-ofmipd can either accept SMTP connections directly on an available port (e.g, 8025), or can be triggered by another server such as xinetd or tcpserver. When a connection is received, tmda-ofmipd authenticates the user, and looks up the user's TMDA configuration. For each message that is received, the message is processed according to the user's outgoing filter.

Once the message has been processed, tmda-ofmipd simply forwards it to some existing SMTP server. This is why it's known as a "proxy" - tmda-ofmipd does not replace the real SMTP server; rather it accepts the message from the client, transforms the headers etc., and then sends the message by handing it off to the real SMTP server.

There are several reasons why you may want to (or have to) use tmda-ofmipd to take advantage of TMDA's client features:

- Your MUA doesn't support a /usr/sbin/sendmail interface, but rather uses direct SMTP to send mail. This includes practically all non-Unix mail clients, and even some Unix clients such as Thunderbird or Mozilla.
- You want to maintain your TMDA configuration in one central location instead of on each individual machine that you use. Unless all your machines share a home directory via NFS or somesuch, this isn't trivial. tmda-ofmipd allows you to maintain only one set of files - on the server on which tmda-ofmipd runs.

## Requirements

An MUA that supports RFC 2554 SMTP Authentication (i.e, username/password). TMDA FAQ 5.6 contains a preliminary list of MUAs known to work with tmda-ofmipd.

NOTE: If your MUA only supports a sendmail command-line interface, but you still want to use tmda-ofmipd, see below for some options.

## Authentication

tmda-ofmipd implements the minimal SMTP protocol as defined in RFC 2821, the ESMTP EHLO command defined in RFC 1869, and SMTP Authentication (PLAIN, LOGIN, CRAM-MD5 methods) as defined in RFC 2554. The proxy cannot be used by an unauthenticated user.

### Authentication Sources

tmda-ofmipd can get its authentication information from several different sources.

1. From a "password" file that you create. The format of this file is simple. Each line of the file should contain a username and password separated by a colon; one entry per line. e.g,

       bobby:FooBar
       chloe:baz_bap
       johndoe:8i9/hjuy+33

   The username fields should match the usernames of the TMDA users on your mail server. The passwords need not be the same as any other passwords on the system. In fact, for security reasons, they should remain distinct! The default location for the authentication file /etc/tofmipd if running in global mode (see below), otherwise ~user/.tmda/tofmipd. These defaults can be overridden using tmda-ofmipd's '-a' flag. The authentication file must be chmod 600 or 400, and be owned by the user running the daemon. tmda-ofmipd will fail to start otherwise.

2. A checkpassword compatible programs such as checkpassword-pam. This would allow you to utilize your existing password database. Use tmda-ofmipd's '-A' flag to specify the program and arguments. The help output contains such an example.

3. Against a remote resource such as POP3, IMAP, or LDAP server. Use tmda-ofmipd's '-R' flag to specify the protocol, and optionally the hostname and port of the server. See the help output for supported protocols and example usage.

## Builtin SSL/TLS

Recent versions of tmda-ofmipd have builtin support for SSL, removing the need to use stunnel. To use this support, you will need to install the tlslite Python module. tmda-ofmipd was developed and tested with version 0.3.8. The primary distribution site for tlslite is http://trevp.net/tlslite/. However, if you run tmda-ofmipd under Python 2.5, you need to use a patched version of tlslite, available from http://www.wwwdotorg.org/tlslite/.

SSL support works in two main modes:

1. --ssl: The first is SMTP-over-SSL (also known as SMTPS, or TLS-wrapper mode in postfix terminology). In this mode, the SSL connection is immediately negotiated when the client connects. Once SSL negotiation has completed, a standard SMTP communication occurs inside the SSL connection. Port 465 is typically used in this case.
2. --tls: The second mode is TLS/STARTTLS mode. In this mode, a plain-text SMTP connection is initially made. At some point, the SMTP client will issue the STARTTLS command, at which point SSL negotiation will occur, and any subsequent communication will be encrypted. Port 587 (submission) is typically used in this case. Note that --tls requires an argument; see below.

Further, --tls mode supports two sub-options. Specifically, usage of the STARTTLS command can be configured to be either optional or mandatory.

1. --tls=optional: If STARTTLS is optional, an SMTP client can completely ignore TLS support, and send email using a purely plain-text SMTP connection with absolutely no impact. This can be useful when initially rolling out SSL support; clients are not immediately forced to reconfigure and/or upgrade their MUAs because of the server-side change.
2. --tls=on: Secure sites will typically choose mandatory usage of STARTTLS. In this configuration, very few SMTP commands are accepted prior to invocation of STARTTLS. This prevents any authentication, or mail injection, from occuring over an unencrypted connection. This is intended to ensure that no passwords pass through an unencrypted connection. The option --tls=on enables this mode.

Theoretically, some AUTH methods are safe even over unencrypted connections. However, tmda-ofmipd does not currently support offering such AUTH mechanisms prior to STARTTLS, but allowing a different set of AUTH mechanisms after STARTTLS.

In all modes, tmda-ofmipd requires access to an SSL private key and SSL certificate file. Use the --ssl-key=/some/path.key and --ssl-cert=/some/path.crt command-line options to configure the relevant filenames.

The key and certificate files should be created in the standard way, most likely using OpenSSL. The file format required is exactly the same as any other SSL server, such as Apache, Dovecot, etc.

### Issues

#### Encryption acceleration package required

SSL supports a number of different encryption schemes. tlslite includes a Python implementation of some of these. However, the Python code doesn't implement all possible encryption schemes, simply because some encryption schemes would run insanely slowly if written in Python.

Some mail clients don't support all possible encryption schemes. If tlslite and your mail client don't both support at least one common encryption scheme, you won't be able to negotiate an SSL connection. So far, this has been observed with the Evolution client, which requires that the server support 3DES.

tlslite support various "encryption acceleration" packages written in C. These packages not only provide much higher encryption throughput, but also implement the 3DES encryption scheme. This will allow Evolution to connect. tlslite supports a variety of different acceleration packages; see the documentation for details. The pycrypto package has been tested by TMDA developers and appears to work well.

## Running

Familiarize yourself with tmda-ofmipd's command-line options by reading the output of:

`tmda-ofmipd --help`

### Modes

tmda-ofmipd can be run in two modes. "Personal" by your non-privileged TMDA user account for your own personal use, or "Global" by your system administrator to serve multiple TMDA users on the system with once instance of the daemon.

#### Personal mode

1. Choose one of the authentication mechanisms above. If you chose to use a password file, you will need to create this.
2. Run tmda-ofmipd under your regular Unix user account.

#### Global mode

1. Choose one of the authentication mechanisms above. If you chose to use a password file, you will need to create this.
2. Create a non-privileged user account for tmda-ofmipd to run under. The following creates an account for user 'tofmipd', group 'tofmipd' under FreeBSD:

        # pw groupadd tofmipd
        # pw useradd tofmipd -g tofmipd -s /nonexistent

   The following does the same for Linux:

        # groupadd tofmipd
        # useradd -g tofmipd -s /nonexistent tofmipd

   If you choose a name other than 'tofmipd', make sure to start tmda-ofmipd with the '-u' option.
3. Invoke tmda-ofmipd under the root account. tmda-ofmipd will internally switch privileges to the tofmipd user, and the user ID of the client connection, as appropriate.

### Starting tmda-ofmipd

tmda-ofmipd can run either as a standalone daemon, or run in "one-session" mode.

When run as a standalone daemon, tmda-ofmipd will listen for connections on the port you specify, accept those connections directly, and handle those connections as described in the introduction.

In "one-session" mode, a separate application, such as xinetd or tcpserver, is expected to listen for, and accept, incoming socket connections, and then spawn tmda-ofmipd to handle the connection.

Some advantages of "one-session" mode are:

- You can run tmda-ofmipd the same way as other network applications, for more consistent management (e.g. re-using xinetd's connection rate control features, or any tcpwrappers configuration, etc.)
- tmda-ofmipd doesn't currently handle SSL directly. To use SSL, you need to use another application such as stunnel. Typically, stunnel will accept the network connection, and make a "loopback" connection to tmda-ofmipd. In this scenario, tmda-ofmipd cannot know the client's IP address, and does not place useful information into the "Received" header it adds to messages. In "one-session" mode, tmda-ofmipd can pick up and use environment variables set by xinetd/tcpserver for this information.

Note that becaue "one-session" mode requires configuring an application such as xinetd to spawn tmda-ofmipd, and (typically) xinetd can only be configured by a system administrator, "one-session" mode will typically be used only in "global mode" as described above. However, a combination of a user-controlled "socket server" application such as stunnel running on a non-privileged port, and tmda-ofmipd in "personal" mode should work, but has not been tested.

#### Daemon

    $ tmda-ofmipd -d -f
    tmda-ofmipd started at Sun, 29 Oct 2006 17:50:25 -0700
            Listening on localhost:8025

tmda-ofmipd is now listening in the foreground for connections on port 8025 of your server.

The host:port combination can be changed using the '-p' option. The '-d' option prints debugging information to stderr which might be useful until you get tmda-ofmipd working as you want it to. Leave off the '-f' option, and tmda-ofmipd will detach and run in the background.

#### xinetd/tcpserver

Configure xinetd to run tmda-ofmipd just like any other program. A simple example configuration file for xinetd is shown below:

    # default: on
    # description: TMDA SMTP proxy daemon
    service tmda-ofmipd
    {
            socket_type     = stream
            wait            = no
            user            = root
            server          = /usr/local/tmda/bin/tmda-ofmipd -1
            log_on_failure  += USERID
    }

Note: Your /etc/services file will need a "tmda-ofmipd" entry to define the port that xinetd will listen on.

Also, note the use of the "-1" option to place tmda-ofmipd into "one-session" mode.

The contrib/ofmipd-stunnel-xinetd contains a more complete example, including the use of stunnel for SMTP/TLS.

tmda-ofmipd uses the environment variable TCPREMOTEIP, or REMOTE_HOST, to determine the client's IP address. tcpserver and xinetd respectively set those variables. If you use another socket server application, you should arrange for one of those variables to be set.

### Testing

    $ telnet localhost 8025
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    220 localhost ESMTP tmda-ofmipd
    quit
    221 Bye
    Connection closed by foreign host.

## MUA Configuration

You must now configure your MUA to use a port other than 25 to send outgoing mail (by default, tmda-ofmipd runs on port 8025 in daemon mode). Configuring your mail client to use an alternate SMTP port to send outgoing mail differs for every client, and is beyond to scope of this document. However, see the following link for examples of how to do this for some of the more popular clients.

http://www.itap.purdue.edu/email/mailhub/clientsetup.cfm

If your MUA only supports a sendmail interface for sending mail, see TMDA FAQ 5.7 for some options.

2007-07-30 15:45