			spfmilter DNSSEC HOWTO
			=======================

Introduction
============

This HOWTO describes the installation, configuration and execution steps for
adding DNSSEC validation to sendmail using spfmilter.


Installation
============

Download spfmilter-x.tar.gz from http://www.libspf2.org/download.html.
Currently supported versions, x, are 0.97 and 1.0.8.

Unzip and untar it by:

	tar -xvzf spfmilter-x.tar.gz

Go to the spfmilter-x directory:

	cd spfmilter-x

For 0.97, a patch is needed to update it for some changes in libspf2:

	patch -p 1 -b -z .orig </path/to/patch/spfmilter-0.97_libspf2.patch

Apply the spfmilter-x_dnssec_patch.txt patch found in this directory by:

	patch -p 1 -b -z .orig </path/to/patch/spfmilter-x_dnssec_patch.txt

This will apply the patch and store the original files with a .orig suffix.

Before compiling, run 'autoconf' from the main spfmilter-x directory to
generate a new 'configure' file.  Then, run configure with the
--enable-dnssec-support option:

	autoconf
	./configure --enable-dnssec-support

Finally, compile and install spfmilter as per the instructions given in the
spfmilter distribution.  The only change is that instead of installing
the original libspf2, you need to patch it with the corresponding libspf2 
dnssec patch. For instructions on how to install libspf2 with
the dnssec-patches, see ../libspf2.

Configuration
=============
Configure sendmail as per the instructions given in the spfmilter distribution.


Execution
=========

The dnssec patch adds a new command line option to spfmilter:

     -s <ignore|warn|reject>

     or

     --dnssec_policy=<ignore|warn|reject>

This option specifies the action spfmilter should take in the event of DNSSEC
validation failure.

If the option is

      --dnssec_policy=ignore

then DNSSEC validation will not take place.  This is the default if the
--dnssec_policy (or the -s) option is not specified on the command line.

If the option is

      --dnssec_policy=reject

the spfmilter patch looks for the SPF_E_DNSSEC_FAILURE error code in the 
response. If it detects this error code, it will return 
SPFMILTER_RESULT_FAIL, which causes the mail
to be rejected or marked according to the spfmilter configuration.
The receipent will not get an email.  The sendmail maillog file will show an
error message similar to the following:

    "Error: DNSSEC validation of SPF record failed."

If the option is

      --dnssec_policy=warn

then the mail will get delivered to the receipent, even in the event of a
DNSSEC validation failure.  However, in this case an error message
similar to the following will be added to the Receivd-SPF mail header:

    x-dnssec="fail (DNSSEC validation of SPF record failed.)";

The sendmail maillog file will also show a similar warning message.

In case of the 'reject' and 'warn' policies, if DNSSEC validation succeeds,
the Received-SPF mail header will contain the following status message:

    x-dnssec="pass";

In case of the 'ignore' policy, the Received-SPF mail header will contain
the following status message:

    x-dnssec="none";

which means that there was no DNSSEC validation.  This error code is also
added if there is no SPF record for the domain.

The dnssec-policy is applied to all emails, irrespective of the sender or the
recepient.  Future versions may allow a more granular policy based on the
sender's domain, sender's email address and/or the recepient's email address.

Use other options to spfmilter as per the instructions given in the
spfmilter distribution.


To Test
=======

1. Start spfmilter with the above dnssec patch applied
2. Start sendmail with the appropriate configuration for spfmilter

(I) Basic Scenarios: DNSSEC validation of the SPF Records
---------------------------------------------------------
The following table gives a summary of the basic scenarios.

+-----------------------------+----------------+--------------+---------------+
| Domain Characteristics      | Ignore Policy  | Warn Policy  | Reject Policy |
+-----------------------------+----------------+--------------+---------------+
|                             |                |              |               |
| No SPF Records              | No DNSSEC      | No DNSSEC    | No DNSSEC     |
|                             | Validation     | Validation   | Validation    |
|                             |      _/        |     _/       |      _/       |
+-----------------------------+----------------+--------------+---------------+
|                             |                |              |               |
| SPF Records present, but    | No DNSSEC      | Error        | Error message |
| not a DNSSEC signed zone    | Validation     | message in   | in maillog.   |
|                             |                | mail header  | Mail dropped. |
|                             |                | and maillog  | Error message |
|                             |                |              | sent to sender|
|                             |      _/        |     _/       |      _/       |
+-----------------------------+----------------+--------------+---------------+
|                             |                |              |               |
| SPF Records present and     | No DNSSEC      | Success      | Success       |
| a DNSSEC signed zone        | Validation     | message in   | message in    |
|                             |                | mail header  | mail header   |
|                             |                | and maillog  | and maillog   |
|                             |      _/        |     _/       |      _/       |
+-----------------------------+----------------+--------------+---------------+

			 Table 1: Basic Scenario Matrix
                         ==============================
	 (A _/ indicates that the scenario has been tested successfully.)

Scenario 1:
-----------
Mails sent from a domain that does not have SPF records.

In this case, there is no SPF processing.  Hence, all mail will go through,
irrespective of the dnssec-policy in spfmilter.

The Received-SPF header will contain the following field:

    x-dnssec="pass";

Scenario 2:
-----------
Mails sent from a domain that has SPF records, but does not have DNSSEC signed
zones.

ignore policy:  DNSSEC validation will not be performed.  The Received-SPF
header will contain

    x-dnssec="none";

warn policy: An error message will be added to the Received-SPF mail header
and the sendmail maillog.

    x-dnssec="fail (DNSSEC validation of SPF record failed.)";

reject policy: An error message will be added to the sendmail maillog.  The
mail will be dropped and an error message will be returned to the sender.

    x-dnssec="fail (DNSSEC validation of SPF record failed.)";

Scenario 3:
-----------
Mails sent from a domain that has SPF records as well as DNSSEC signed zones.

ignore policy:  DNSSEC validation will not be performed.  The Received-SPF
header will contain

    x-dnssec="none";

warn policy: A DNSSEC validation success message will be added to the
Received-SPF mail header or the sendmail maillog:

    x-dnssec="pass";

reject policy: A DNSSEC validation success message will be added to the
Received-SPF mail header and the sendmail maillog:

    x-dnssec="pass";


(II) Intermediate Scenarios: DNSSEC validation of the SPF Mechanisms
--------------------------------------------------------------------

These scenarios test various SPF mechanisms.  In this case, the primary
SPF record is signed.  However, the further records that it points to may
or may not be signed.  It is assumed that the mail is sent from an
IP address that is ultimately referenced by the DNS records i.e. in the
absence of DNSSEC validation, the SPF result will be a PASS.  However,
one or more intermediate DNS records may or may not be signed using DNSSEC.
This gives rise to many interesting scenarios, some of which are enumerated
in the following table along with their expected results.

+-----------+-----------------+----------------+--------------+---------------+
| Mechanism |   Conditions    | Ignore Policy  | Warn Policy  | Reject Policy |
+-----------+-----------------+----------------+--------------+---------------+
|           |                 |       _/       |     _/       |      _/       |
|           | Signed A record |      PASS      |    PASS      |     PASS      |
|     A     +-----------------+----------------+--------------+---------------+
|           |                 |       _/       |     _/       |      _/       |
|           | Unsigned A rec. |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+-----------+-----------------+----------------+--------------+---------------+
|           |                 |       _/       |      _/      |      _/       |
|           | Signed MX rec.  |      PASS      |     PASS     |     PASS      |
|    MX     +-----------------+----------------+--------------+---------------+
|           |                 |       _/       |      _/      |      _/       |
|           | Unsigned MX rec.|      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+-----------+-----------------+----------------+--------------+---------------+
|           |                 |       _/       |      _/      |      _/       |
|           |Signed EXISTS rec|      PASS      |     PASS     |     PASS      |
|  EXISTS   +-----------------+----------------+--------------+---------------+
|           |    Unsigned     |       _/       |      _/      |      _/       |
|           | EXISTS record   |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+-----------+-----------------+----------------+--------------+---------------+
|           |Signed INCLUDE re|       _/       |      _/      |      _/       |
|           |Signed A record  |      PASS      |     PASS     |     PASS      |
|           +-----------------+----------------+--------------+---------------+
|           |Signed INCLUDE re|       _/       |      _/      |      _/       |
|           |Unsigned MX rec. |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+  INCLUDE  +-----------------+----------------+--------------+---------------+
|           |Unsigned INCLUDE |       _/       |      _/      |      _/       |
|           |Signed A rec.    |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
|           +-----------------+----------------+--------------+---------------+
|           |Unsigned INCLUDE |       _/       |      _/      |      _/       |
|           |Unsigned MX rec. |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+-----------+-----------------+----------------+--------------+---------------+
|           |Signed REDIRECT  |       _/       |      _/      |      _/       |
|           |Signed A record  |      PASS      |     PASS     |     PASS      |
|           +-----------------+----------------+--------------+---------------+
|           |Signed REDIRECT  |       _/       |      _/      |      _/       |
|           |Unsigned MX rec. |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
|  REDIRECT +-----------------+----------------+--------------+---------------+
|           |Unsigned REDIRECT|       _/       |      _/      |      _/       |
|           |Signed A record  |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
|           +-----------------+----------------+--------------+---------------+
|           |Unsigned REDIRECT|       _/       |      _/      |      _/       |
|           |Unsigned MX rec. |      PASS      | MAIL/WARNING | NO-MAIL/ABORT |
+-----------+-----------------+----------------+--------------+---------------+
|           |                 |                |              |               |
|           |                 |                |              |               |
|    PTR    +-----------------+----------------+--------------+---------------+
|           |                 |                |              |               |
|           |                 |                |              |               |
+-----------+-----------------+----------------+--------------+---------------+

			 Table 2: Intermediate Scenario Matrix
			 =====================================
	 (A _/ indicates that the scenario has been tested successfully.)


(III) Advanced Scenario: Use of DNSSEC in SPAM filtering
--------------------------------------------------------

===============================================================================
