			postfix DNSSEC HOWTO
			=====================
			    (Version 0.1)

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

This HOWTO describes the installation, configuration and execution
steps for adding DNSSEC validation to outbound email for
postfix. The 2.5.1 patch have been tested with postfix version
2.5.1.  It will likely work, with some patch warnings, with versions
down to and including postfix 2.3.8, but this hasn't been tested
extensively.  This patch may work with versions of postfix newer
than 2.5.1.


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

Download postfix-2.5.1.tar.gz from
http://www.postfix.org/download.html

Unzip and untar it by:

   tar -xvzf postfix-2.5.1.tar.gz

Go to the postfix-2.5.1 directory:

   cd postfix-2.5.1/

Apply the postfix-2.5.1_dnssec_patch.txt patch found in this
directory by:

   patch -p 1 -b -z .orig </path/to/patch/postfix-dnssec.patch

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

This patch requires the 'libval' library for DNSSEC validation.
This library can be found at http://dnssec-tools.sourceforge.net/.
You must install this library before compiling the patched postfix
source.

Remember to run 'make -f Makefile.init makefiles' in the
postfix-2.5.1/ directory before following the rest of the postfix
build instructions

Note, if 'make -f Makefile.init makefiles' has already been run in
the postfix source code, it will be necessary to run it again in
order to apply the patch properly (a 'make clean' and 'make tidy'
beforehand may also be necessary).

Build and install postfix as per the instructions given in the
INSTALL files within the postfix source code.

NOTE: the postfix install process will attempt to resolve your local
hostname during the install.  You should ensure that your local hostname
resolves correctly before intalling postfix.  e.g.

    validate -o 5:stdout mail.example.com


Configuration
=============

All DNS queries are now checked using the dnssec-tools libval
libraries.  Attempts to send mail to untrusted sites will fail and
bounce with an applicable message.  Configuration of site trust is
done by editing the dnssec-tools' dnsval.conf file.  The default
location of this file is /usr/local/etc/dnssec-tools/dnsval.conf on
linux distributions, but this path is dependent on how dnssec-tools
was built.

Execution
=========

Start and run postfix as normal.


To Test
=======

(I) Basic Scenarios: DNSSEC validation of outbound email
    ----------------------------------------------------

1. Start postfix with the above patch applied.

2. Send email to a user at a domain whose MX records can be DNSSEC
   validated and where validation is required.  Verify that the mail
   goes through properly.

3. Send email to a user at a domain whose MX records cannot be
   DNSSEC validated and where validation is required.  Verify that
   an SMTP error message is returned back to the sender.

4. If reject_unknown_sender_domain is set for smtpd_sender_restrictions,
   verify that a client trying to send mail as a user with a domain
   whose MX records cannot be DNSSEC validated and where validation
   is required will be rejected.

-----------------------------------------------------------------------


Note: Postfix Failure to Start
------------------------------

If the libval installation is not configured and working properly,
postfix may fail at startup (obviously the configuration affects the
sending of mail during runtime).  If this happen, a first step in
diagnosing the problem is trying the executable 'validate' provided
by the libval package.  If 'validate' does not work properly when
looking up DNSSEC information on your server, neither will Postfix.
