$Id: README,v 1.12 2005/04/08 18:31:31 msk Exp $

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


This is the development area for Sendmail's DomainKeys filter, which is our
implementation of the Yahoo! DomainKeys service.

The filter implemented here, if plugged into the Sendmail MTA, provides
signing and verification service as per Yahoo!'s DomainKeys specification.


ADVISORY
========

THIS IS PRE-RELEASE SOFTWARE, and should not be used in any critical
production environments (yet).  However, we hope this pre-release period
will be as brief as possible so that it can be sanctioned for mainstream
use.


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 dk-milter-(version) directory.
(3) Edit libdk/Makefile.m4 and dk-filter/Makefile.m4 as indicated in those
    files to specify the locations of the OpenSSL include and library files.
(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(`dk-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 512
    (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:

	  "g=; 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/domainkeys/SELECTOR.key.pem (where "SELECTOR" is the name you
    chose).

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

	-l -p SOCKETSPEC -d DOMAIN -s 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.

(7) Restart sendmail.


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

The DKDEBUG environment variable, if set, specifies debugging options to
be applied by the filter.  Note that libdk uses the same variable name
(for now) so there may be some overlap in the debug flags used.
See libdk/README for details.

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

	t	thread progress; each callback is logged at LOG_INFO
		along with the thread ID

You can also compile the package with the -DDEBUG flag, which builds a version
of dk-filter that reads from standard input and dumps trace data to standard
output.  The input should be an RFC2822 message with the following lines
prepended:

	Fuser@example.com
	.

The first line, starting with "F", defines the envelope sender.  The value
of this is not actually used, but the mechanism is present and requires
the input.  The "." line separates the message headers and body from the
envelope and must also be included.

On standard output you will see each of the milter callbacks that are made
by the filter in response to the input, and ultimately the milter return
values, the headers that are added, modified or removed, and any changes to
the message body that result.  You can only feed one message per execution of
the debug mode of the program, and the program will terminate when a result
is produced.


SUPPORT
=======

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

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

	dk-milter-announce@lists.sourceforge.net (release announcements)
	dk-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:

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