DKIM-MILTER PACKAGE

This directory has the latest open source DKIM filter software from
Sendmail, Inc.

Report any bugs to dkim-milter-discuss@lists.sourceforge.net.

There is a web site at http://sourceforge.net/projects/dkim-milter that is
home for the latest updates.


+--------------+
| INTRODUCTION |
+--------------+

The dkim-milter package is an open source implementation of the DKIM
sender authentication system proposed by the E-mail Signing Technology
Group (ESTG), now a proposed standard of the IETF (RFC4871).

DKIM is an amalgamation of the DomainKeys (DK) proposal by Yahoo!, Inc.
and the Internet Identified Mail (IIM) proposal by Cisco.

This package consists of a library that implements the DKIM service and a
milter-based filter application that can plug in to the sendmail MTA to
provide that service to sufficiently recent sendmail MTAs and other MTAs
that support the milter protocol.

An optional asynchronous resolver library is also provided to work around
limitations of the basic BIND resolver which comes installed on most
systems.


+--------------+
| DEPENDENCIES |
+--------------+

To compile and operate, this package requires the following:

o OpenSSL (http://www.openssl.org, or ask your software vendor for a package)
  (any version will get you started, however v0.9.8 is required if you want
  to be able to sign or verify messages using the SHA256 message digest
  algorithm)

o sendmail v8.13.0 (or later), and libmilter from the same distribution
  (http://www.sendmail.org)

o Access to a working nameserver (required only for verification).


+-----------------------+
| RELATED DOCUMENTATION |
+-----------------------+

Yahoo!'s DomainKeys page is available at http://antispam.yahoo.com/domainkeys.

The man page for dkim-filter (the actual filter program) is present in the
dkim-filter directory of this source distribution.

HTML-style documentation for libdkim is available in libdkim/docs in this
source distribution.

General information about DKIM can be found at http://www.mipassoc.org/dkim.

Mailing lists discussing and supporting the DKIM software found in this
package are maintained via the list server at SourceForge.  Visit
http://sourceforge.net/dkim-milter to subscribe or browse archives.


+---------+
| WARNING |
+---------+

Since dkim-milter uses cryptography, the following information from OpenSSL
applies to this package as well.

PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY
SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING
TECHNICAL DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME
PARTS OF THE WORLD.  SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR
COUNTRY, RE-DISTRIBUTE IT FROM THERE OR EVEN JUST EMAIL TECHNICAL
SUGGESTIONS OR EVEN SOURCE PATCHES TO THE AUTHOR OR OTHER PEOPLE
YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO ANY EXPORT/IMPORT
AND/OR USE LAWS WHICH APPLY TO YOU.  THE AUTHORS ARE NOT LIABLE FOR
ANY VIOLATIONS YOU MAKE HERE.  SO BE CAREFUL, IT IS YOUR RESPONSIBILITY.

If you use OpenSSL then make sure you read their README file which
contains information about patents etc.


+---------------------+
| DIRECTORY STRUCTURE |
+---------------------+

devtools	m4-based build scripts and other data needed to compile
		the package.

libar		An optional thread-safe asynchronous resolver library.

libdkim		A library that implements the proposed DKIM standard.

libdkim/docs	HTML documentation describing the API provided by libdkim.

dkim-filter	A milter-based filter application which uses libdkim (and
		optionally libar) to provide DKIM service via a sendmail MTA
		and the milter protocol.


+-------------------+
| PERFORMANCE NOTES |
+-------------------+

Courtesy of Thom O'Connor from Sendmail, Inc. who did a lot of the initial
performance and stress testing (slightly edited):


The key to building a dkim-filter binary built for very high performance is
two-fold:

1. If poll() is available on your system, build libmilter to use poll()
rather than select(). This is accomplished by modifying your build
file (devtools/Site/site.config.m4) to contain this:

dnl # use poll() instead of select() in libmilter
APPENDDEF(`confENVDEF', `-DSM_CONF_POLL=1')dnl

Then build dkim-filter with the resulting libmilter.a.  poll() is able to
handle higher descriptors than select() is on some systems.  During high
loads where lots of descriptors can be in simultaneous use, this can
become important.

2. Make sure to build dkim-filter using the asynchronous (ARLIB) resolver.
This is accomplished by modifying site.config.m4 to enable these lines:

define(`bld_USE_ARLIB', `True')

Obviously, overall throughput performance is then based on factors such as
CPU resource available, DNS performance, etc.  However, in benchmark tests
using 100% message signing or verification, on a 2-cpu linux box, I'm
getting consistent rates of over 100 messages signed or verified per second
with a 32kB average message size, and upwards of 200 messages
signed/verified per second when using 1kB messages. 


+----------------------+
| VERIFYING DOMAINKEYS |
+----------------------+

This version supports verification of DomainKeys signatures on arriving
messages, if present.  To get this service, copy site.config.m4.dist
to devtools/Site/site.config.m4 (if you haven't done so already) and
make the edits suggested in that file for adding DomainKeys support.

You will also need to copy the "libdk" directory from the "dk-milter"
package (also available on SourceForge) into the top directory of
this package.

DomainKeys signing is not provided in this package.  To sign your mail
with DomainKeys, download and install the "dk-milter" package from
SourceForge.


+----------------+
| RUNTIME ISSUES |
+----------------+

WARNING: sendmail symbol 'X' not available

 The filter attempted to get some information from the MTA which the MTA
 did not provide.

 At various points in the interaction between the MTA and the filter, certain
 macros containing information about the job in progress or the connection
 being handled are passed from the MTA to the filter.  The names of the macros
 the MTA should pass to the filter are defined by the "Milter.macros"
 settings in sendmail.cf, e.g. "Milter.macros.connect",
 "Milter.macros.envfrom", etc.  This message indicates that the filter needed
 the contents of macro X, but that macro was not passed down from the MTA.

 Typically the values needed by this filter are passed from the MTA if the
 sendmail.cf was generated by the usual m4 method.  If you do not have
 those options defined in your sendmail.cf, make sure your M4 configuration
 files are current and rebuild your sendmail.cf to get appropriate lines
 added to your sendmail.cf, and then restart sendmail.

MTA timeouts

 By default, the MTA is configured to wait up to ten seconds for a response
 from a filter before giving up.  When querying remote nameservers
 for key and policy data, the DKIM filter may not get a response from the
 resolver within that time frame, and thus this MTA timeout will occur.
 This can cause messages to be rejected, temp-failed or delivered without
 verification, depending on the failure mode selected for the filter.

 When using the standard resolver library provided with your system, the
 DNS timeout cannot be adjusted.  If you encounter this problem, you must
 increase the time the MTA waits for replies.  See the documentation in
 the sendmail open source distribution (libmilter/README in particular)
 for instructions on changing these timeouts.

 When using the provided asynchronous resolver library, you can use the
 "-T" command line option to change the timeout so that it is shorter than
 the MTA timeout.

d2i_PUBKEY_bio() failed

 After retrieving and decoding a public key to perform a message verification,
 the OpenSSL library attempted to make use of that key but failed.  The
 known possible causes are:

  (a) Memory exhaustion

  (b) Key corruption

 If you're set to temp-fail messages in these cases, the remote end will
 probably retry the message.  If the same message fails again later,
 the key is probably corrupted or otherwise invalid.

 You can try compiling with _FFR_LOG_SSL_ERRORS to have the filter extract
 OpenSSL library errors and include them in the system log when such
 conditions occur for further diagnostics.  In one observed case, a corrupt
 key also caused the following to be logged:

  error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag;
  error:0D07803A:asn1 encoding routines:ASN1_ITEM_EX_D2I:nested asn1 error
 

+--------------------------------+
| MASQUERADING AND GENERICSTABLE |
+--------------------------------+

There are two features of the sendmail MTA which, if activated, can interfere
with successful use of the DKIM service.  The two features are MASQUERADE_AS
and FEATURE(genericstable).  See cf/README in the open source sendmail
source code distribution for more information.

Due to the way the milter protocol is incorporated into the MTA, dkim-filter
sees the headers before they are modified as required by those two features.
This means the DKIM signature is generated based on the headers originally
injected by the mail client and not on the headers which are actually sent
out by the MTA.  As a result, the verifying agent at the receiver's side
will be unable to verify the signature as the signed data and the received
data don't match.

The suggested solutions to this problem are:

(1) Send mail with the headers already written as needed, obviating the
    need for these features (or just turn them off).

(2) Have two MTAs set up, either on separate boxes or on the same box.
    The first MTA should do all of the rewriting (i.e. use these two
    features) and the second one should use dkim-filter to add the signature
    and do no rewriting at all.

(3) Have multiple DaemonPortOptions lines in your configuration file.  The
    first daemon port (port 25) does the header rewriting and then routes
    the message to the second port; the latter does no rewriting but does the
    signing and then sends the message on its way.

    [include further instructions, e.g. m4 examples, here]

+-------------------------------------+
| OPERATING SYSTEM AND COMPILE QUIRKS |
+-------------------------------------+

For a more comprehensive set of entries in this area, check the README
in the sendmail distribution.  This section contains entries copied from
there which have been reported specifically about the dkim-milter package.

Fedora Core 5, 64 bit version
	If the ld stage fails with undefined functions like
	__res_querydomain, __dn_expand
	then add these lines to devtools/Site/site.config.m4

	APPENDDEF(`confLIBDIRS', `-L/usr/lib64')
	APPENDDEF(`confINCDIRS', `-I/usr/include/bind9')

	and rebuild (sh ./Build -c).

	Problem noted by Daniel Krones, solution suggested by
	Anthony Howe.


$Revision: 1.15 $, Last updated $Date: 2008/02/26 17:41:27 $