$Id: README,v 1.18 2008/03/05 18:17:21 msk Exp $

INTRODUCTION
============

This is the development area for Sendmail's DKIM (DomainKeys Identified Mail)
filter, which is our implementation of the DKIM service.

The filter implemented here, if plugged into the Sendmail MTA, provides
signing and verification service as per the DKIM specification.

DKIM is a merger of the Yahoo!'s DomainKeys (DK) specification, and Cisco's
Internet Identified Mail (IIM) proposal.


COMPILING
=========

Requires sendmail v8.13.0 or later, for required milter protocol
enhancements.

To build this package in the public domain:

(1) Download and unpack the source package.
(2) Change to the dkim-milter-(version) directory.
(3) Edit site.config.m4.dist to enable/disable/adjust any options or paths
    you'd like the package to use.  See the FEATURES file for a description
    of the compile-time features available.  When you're done, move or copy
    this file to devtools/Site/site.config.m4.
(4) Type "sh Build".


INSTALLING
==========

(1) Configure sendmail:
  (a) Choose a socket at which the MTA and the filter will rendezvous
      (see the documentation in libmilter for details)
  (b) Add a line like this example to your sendmail.mc using your desired
      socket specification:
	INPUT_MAIL_FILTER(`dkim-filter', `S=inet:8891@localhost')
  (c) Rebuild your sendmail.cf in the usual way

(2) Choose a selector name.  Current convention is to use the hostname
    (hostname only, not the fully-qualified domain name) of the host that
    will be providing the service, but you are free to choose any name you
    wish, especially if you have a selector assignment scheme in mind.

(3) Either:
  (a) Run the script gentxt.csh.  This will generate a public and private
      key in PEM format and output a TXT record appropriate for insertion
      into your DNS zone file.  Insert it in your zone file and reload your
      DNS system so the data is published.
	-OR-
  (b) Manually generate a public and private key:
    (i)   % openssl genrsa -out rsa.private 1024
    (ii)  % openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM
    (iii) Add a TXT DNS record containing the base64 encoding of your public
          key, which is everything between the BEGIN and END lines in the
          rsa.public file generated above, with spaces and newlines removed.
          It should be in this form:

	  "v=DKIM1; k=rsa; t=y; p=MFwwDQYJ...AwEAAQ=="

          ...using, of course, your own public key's base64 data.  The name of
          the TXT record should be SELECTOR._domainkey.example.com (where
          "SELECTOR" is the name you chose and "example.com" is your domain
          name).  You might want to set a short TTL on this record.  Reload
          your nameserver so that the record gets published.  For a translation
          of the parameter and value pairs shown here, see the draft spec;
          basically this just announces an RSA public key and also declares
          that your site is using this key in test mode so nobody should take
          any real action based on success or failure of the use of this key to
          verify a message.

(4) Store the private key in a safe place.  We generally use a path like
    /var/db/dkim/SELECTOR.key.pem (where "SELECTOR" is the name you
    chose).

(5) Start dkim-filter.  You will need at least the "-p" option.  The current
    recommended set of command line options is:

	-l -p SOCKETSPEC -d DOMAIN -k KEYPATH -s SELECTOR

    ...where SOCKETSPEC is the socket you told sendmail to use above,
    DOMAIN is the domain or set of domains for which you want to sign
    mail, KEYPATH is the path to the private key file you generated, and
    SELECTOR is the selector name you picked.  You can tack "-f" on there
    if you want it to run in the foreground instead of in the background
    as a daemon.

(6) Restart sendmail.


DEBUG FEATURES
==============

The DKIMDEBUG environment variable, if set, specifies debugging options to
be applied by the library.  Note that libdkim itself uses the same variable
name (for now) so there may be some overlap in the debug flags used.

The contents of DKIMDEBUG should be a string containing characters
representing the required debug options as depicted in this list:

	c	leave temporary files in /var/tmp; the files will contain
		canonicalized messages as they are fed to the signing or
		verifying operations

	t	log each thread that enters each callback or other
		major portion of the code; useful for deadlock hunting

The "c" debug option is useful when using a remote verifier that is equipped
to send back replies which contain the canonicalization output at the remote
end.  Such a verifier, when a signature verification fails, will ask the
sending domain for its sender policy.  If that policy exists and contains
an "r=" tag, then the verifier will send a message to the address
contained in that tag which contains the canonicalized forms of the failing
message as generated at the verifier.  Comparing these forms to the local
copies of the same (generated as described above) using a utility such as
"diff" will show how a message was modified between the signing and verifying
operations.  This will usually reveal the cause of the failed verification.

To become a verifier that sends such responses, start dkim-filter with the
"-R" command line option.


DOMAINKEYS SUPPORT
==================

This version supports optional verification of DomainKeys signatures
on arriving messages.  DomainKeys signing is not supported.

To add this feature:

(1) Go to http://sourceforge.net/projects/dk-milter and download the latest
    version.

(2) Unpack libdk from the tarball:

	gunzip -c dk-milter-0.x.y.tar.gz | tar xf libdk

(3) Move the "libdk" directory to the top of the dkim-milter-0.x.y source
    code directory.

(4) Edit libdk/Makefile.m4 and make any desired changes (e.g. enabling
    use of "libar", if desired).

(5) Edit devtools/Site/site.config.m4 to enable the lines which activate
    the DomainKeys support.

(6) Recompile dkim-filter ("sh Build -c").


REUSING DOMAINKEYS RECORDS
==========================

Published DomainKeys key records are almost totally compatible with DKIM.
The one area in which they differ is the use of the granularity ("g=") tag.

Under DomainKeys, the default granularity is the empty string.  DomainKeys
interprets this as "match anyone".  However, DKIM interprets this as
"match none".  Thus, a key record containing "g=" means one thing to
DomainKeys but the opposite to DKIM, making it incompatible.

Under DKIM, the default granularity is "*", which means "match anyone".

Since both systems have defaults that mean "match anyone", a DomainKeys
key record which doesn't have a "g=" string in it at all will work as
expected with DKIM.  Thus, if you want to use one key record with both
systems, remove the "g=" portion of the record and reload your nameserver.


SUPPORT
=======

To get support or report bugs, you can access the Sourceforge "tracker"
facilities at http://sourceforge.net/projects/dkim-milter.

There are two public mailing lists available for news and questions about
dkim-milter.  To keep up to date on the latest developments, please
subscribe to one or both of the following:

	dkim-milter-announce@lists.sourceforge.net (release announcements)
	dkim-milter-discuss@lists.sourceforge.net (general discussion)

You can subscribe to these lists via the project URL above.  There is also
a private mailing list which should be used to report security bugs or
other potentially sensitive issues:

	dkim-milter-security@lists.sourceforge.net (security issues)
