path: root/README

                                    Tamarind

                         Say Good-Bye to Spam, Forever


1. INTRODUCTION

Tamarind is a web application intended for use on GNU/Linux systems which host
both a web and mail server. Tamarind lets a user of such a system easily manage
a list of randomly generated e-mail aliases, through a simple and friendly
web interface.

Tamarind is an acronym; it stands for:

  Throwaway Mail Alias Randomization is not Defeatable.
  ^    ^    ^    ^     ^             ^  ^   ^

2. FUNCTIONALITY

The user of Tamarind logs into the Tamarind web service by entering
their IMAP4 or Linux user ID and password into a form. Once authenticated,
the user is presented with a list of their e-mail aliases, intially
empty.

A new alias can be created by optionally filling in the Memo
input field, and clicking the Create New button. 

The randomly generated alias consists of a ten digit numeric string resembling
a North American style telephone number, exemplified by 123-456-7890. 
This is the local part of the e-mail address. Of course, it has a domain
part: the configured mail domain of the server. If the domain is example.com,
then the alias looks like 123-456-7890@example.com.

The alias becomes active immediately. E-mail received for this alias is
delivered to the user's mailbox.

The Memo field is a piece of arbitrary text associated with an alias;
the user can put whatever information they wish.

An alias can be deleted at any time. The user can simply enable a checkbox
next to the alias in the alias list view. After checkboxing one or more
aliases, the Del button permanenty removes them.

Once removed, an alias stops working; mail received by the mail server
for that alias is simply undeliverable at the SMTP level, and "bounces"
back to the originator.

For each alias, two supplementary aliases are also created in which
the dashes are replaced, respectively with underscores and periods.
That is to say, if Tamarind creates the alias 123-456-7890,
it also creates 123_456_7890 as well as 123.456.7890.

2. ARCHITECTURE

Tamarind is a CGI program written in the TXR language, running under
the Apache web server. Each web request  from a web browser launches
a new instance of the Tamarind program.

Tamarind authenticates users in one of two ways: using IMAP (opening
a TCP connection to an IMAP server to verify the user name and password)
or SASL (UNIX domain socket to saslauthd server).

User sessions are maintained in per-user persistent files stored on the server
in a configurable session directory. A browser cookie is associated with an
authenticated browser.

A user may have only one session at a time, making it impossible to log
in at the same time from multiple locations. If a user makes a new session
on Computer B, the previous session from Computer A is overwritten, and
the cookie stored in the browser on Computer A becomes invalid.

The aliases maniupulated by Tamarind are stored in a single alias file,
usually called /etc/tamarind/aliases which is hooked into the Exim mail
server's configuration as an auxiliary aliases file processed in
addition to the usual /etc/aliases.

The Memo texts are stored in the aliases file; to the mail server,
those lines of the file appear as comments.

Here is a visual representation of the architecture:


    +---------+    HTTPS    +------------+
    | Browser |  <------->  |   Apache   |
    +---------+             +------------+
                                 ^
                                 |
                                CGI
                                 |
                                 v 
                            +------------+                     +------------+
                            |  Tamarind  | <-- Unix Socket --> | saslauthd  |
                            +------------+ <--\                +------------+
                              |       |       |      ^
                              ^       |       |     OR        AUTHENTICATION
                              v       |       \      v         +------------+
                              |       |        - TCP Conn. --> | IMAP Serv. |
                              |       |                        +------------+
                              |       \
                              |        -- /var/run/tamarind/session/*
                              \
                               ------------ /etc/tamarind/aliases
                              /
                              |
                              v
            SMTP mail       +----------+
          ----------------> | Exim MTA | ---->  your inbox
                            +----------+



3. HOW TO INSTALL TAMARIND

3.1 Overview.

An intallation of Tamarind requires the correct configuration in
multiple places, with correct permissions of files an directories.

Tamarind itself must be configured where to maintain the aliases file, and
where to keep the sessions. The default values for these configurations can
probably be used.

The Apache web server must be configured to present the Tamarind application to
the world. The Apache account (www-data, on Debian servers) must be added to
the sasl group in /etc/groups, so that Tamarind has permissions to open the
SASL socket.

The Exim mail server must be configured to scan the Tamarind-maintained aliases
file, and optionally may be configured such that mail received for Tamarind
aliases bypass some anti-spam checks. The rationale for this is given
below.

Of course, the TXR language is required: version 140 or later.

Detailed configuration steps follow.

3.2 Apache

Choose a location for the code, and put the code there.  Make sure the
directory is owned by the the Apache user and group (www-data:www-data)
and has appropriate permissions to that directory and the code.

For instance, suppose the code lives in /home/projects/tamarind.

Also suppose that we want the application to appear on the
server as /tamarind 

Then use a configuration similar to the following in Apache's
httpd.conf:

Alias /tamarind /home/projects/tamarind
 
<Directory "/home/projects/tamarind">
  AllowOverride None
  Options All -Indexes FollowSymlinks MultiViews
  Options +ExecCGI
  Order allow,deny
  Allow from all
  AddHandler cgi-script .txr
  RewriteBase /tamarind
  RewriteEngine on
  RewriteCond %{HTTPS} !^on$ [NC]
  RewriteRule ^$ https://%{HTTP_HOST}%{REQUEST_URI} [R,L]
  RewriteRule ^$ main.txr
</Directory>

Don't forget that Apache has to be restarted for config
changes to take effect. You may wait to do this restart
until configuring SASL permissions.

3.3 SASL-Related Group Permissions

Edit the /etc/groups file. Ensure that the sasl group
contains the Apache user. On Debian, that user is www-data,
and the line in /etc/groups might look like this:

  sasl:x:45:www-data

Of course, other user IDs may be present there in addition
to www-data. Multiple user IDs are comma separated, as in:

  sasl:x:45:joe,mary,www-data

(joe, mary and www-data are members of the sasl group).

Apache must be restarted into order to pick up this
new group membership.

3.4 Exim

3.4.1 Create the Tamarind aliases directory

# mkdir -p /etc/tamarind
# touch /etc/tamarind/aliases
# chown -R www-data:www-data /etc/tamarind

Make sure the directory itself has rwxr-x--- (750) permissions.  755 is also
acceptable (the directory can be readable and searchable to others, but not
writable). Tamarind's umask ensures that the files in this directory are only
readable to their owner and group, not others.

3.4.2 Exim Permissions to read Aliases

Exim runs as the "Debian-exim" user on Debian.  This user doesn't have access
to files created by the Apache user "www-data", such as the file
/etc/tamarind/aliases. To address this, we add the Debian-exim user to the
www-data group in the /etc/groups file.

   www-data:x:33:list,Debian-exim

3.4.3 Exim Aliases Configuration

Early versions of Tamarind worked directly with /etc/aliases.  Later, it was
changed to use an alternative aliases file, /etc/tamarind/aliases.

An Exim configuration change is required for it to process this file just like
it processes aliases.

On the system where Tamarind is developed, Exim is configured using the "all in
one file" configuration style. The following has been added to the file, right
after the system_aliases: section:

#####################################################
### router/450_exim4-config_tamarind_aliases
#####################################################
tamarind_aliases:
  debug_print = "R: tamarind_aliases for $local_part@$domain"
  driver = redirect
  domains = +local_domains
  allow_fail
  allow_defer
  data = ${lookup{$local_part}lsearch{/etc/tamarind/aliases}}
#####################################################
### end router/450_exim4-config_tamarind_aliases
#####################################################

In a "separate files" configuration style for Exim, this would be placed in its
own file: router/450_exim4_config_tamarind_aliases.

3.4.5 Exim Delivery Configuration

Optionally, configure Exim to allow Tamarind addresses to bypass spam
filtering.  Under the  acl_check_rcpt: section in your Exim configuration, add
the following.

  accept
    recipients = ^\\d\\d\\d[-._]\\d\\d\\d[-._]\\d\\d\\d\\d@YOUR_DOMAIN\$

Substitute the mail domain for YOUR_DOMAIN!

Note: when Tamarind generates aliases, the domain part of these
aliases is taken from /etc/mailname.

The above rule should be among the first rules processed, before any "deny"
rules for spam filtering.

Rationale---why this is a good idea: Tamarind addresses are an anti-spam
measure; they do not need to be combined with other anti-spam checks, and doing
so is counter-productive in some ways. It is useful for Tamarind addresses to
enjoy certain delivery.  They can then be used for online transactions in which
it is inconvenient or impossible to have an e-mail repeated.   If a Tamarind
address starts being abused by spammers, the user can stop the spam by deleting
it. That is the only anti-spam measure required.