opendkim for Debian
-------------------

Generating a key and publishing a TXT record
--------------------------------------------

The DKIM spec requires an RSA key between 512 and 2048 bits in length.
It also requires 1024 for keys that are "long-lived", so 1024 is a
good safe starting point. 

The easiest way to generate a key is with the opendkim-genkey(8) utility.
For example:

$ opendkim-genkey -b 1024 -d example.com -s selector1 

This will create two files: selector1.private, containing the private
RSA key, and selector1.txt, containing the appropriate DNS record for
this key.

Alternately, keys may be generated by hand:

$ openssl genrsa -out selector1.private 1024

Note that this private key should be installed such that it's readable
only by the filter itself and any other software requiring access to
it. Anyone who is able to access it will be able to sign mail as your
domain. The maintainer's recommendation: Change the key file's ownership
to opendkim and its permissions to 400 (read-only by owner).

The public value may then be retrieved with:

$ openssl rsa -in selector1.private -pubout -outform pem

The public key will go into your DNS TXT record under the name
<selector>._domainkey. The TXT record contains a number of tag/value
pairs as described in the DKIM specification. The required p= tag
contains the PEM-formatted (that is, base64-encoded DER) public key,
no header, footer, newlines or spaces. This can be obtained using
a command line like this:

$ openssl rsa -in selector1.private -pubout -outform pem 2>/dev/null | \
grep -v "^-"  | tr -d '\n'

Other useful but optional flags include k= (the key type, "rsa"
by default) and t= (which can have any of the flags "t" and "s",
indicating, respectively, testing mode and scope). Testing mode
instructs recipients to treat signed and unsigned email the same,
allowing the generation and verification of signatures without
any action (yet) being taken.

For example: example.com wishes to sign all of their mail with DKIM.
They choose the selector "mail" and decide, for now, to indicate that
they are in testing mode", until they've verified their configuration.
They might put the following in their DNS:

mail._domainkey.example.com TXT "v=DKIM1; k=rsa; t=y; p=<public key>"

In addition, some receivers may support DomainKeys-style sender policy
as described in the DomainKeys specification at:
http://tools.ietf.org/html/rfc4870#section-3.6

Note that this is not an exhaustive list of features or tags; see below
for a link to the DKIM specifications.

Notes for Postfix users
-----------------------

Postfix users who wish to access the opendkim service via UNIX socket
(the default) may need to add the postfix user to the opendkim
group and ensure that UMask is set to 002 in /etc/opendkim.conf, in
order to make the socket readable by Posfix.

Users may also need to move the socket into a directory accessible by the
Postfix chroot; this can be accomplished by setting the SOCKET variable
in /etc/default/opendkim.

As an alternative, you may opt to connect to the filter over TCP. The
filter can be bound to localhost to prevent other hosts from accessing it.
For example, to bind to port 8891, specify "inet:8891@localhost".

Changing group ownership of socket
----------------------------------

The group ID of the UNIX socket created by opendkim can be changed by
changing the primary GID of the opendkim user, e.g.:
$ usermod -g mail opendkim

Changes to key specifications
-----------------------------

The KeyList functionality in versions of OpenDKIM prior to 2.0.0 has been
replaced with two features called SigningTable and KeyTable. More information
on these can be found in opendkim.conf(5). If you use these features, the
script /usr/share/doc/opendkim/contrib/convert_keylist.sh can be used to read a
KeyList file and create appropriate SigningTable and KeyTable files.

More detailed information about the new data sets (including LDAP and other
data set types) can be found in README.opendkim.

 -- Scott Kitterman <scott@kitterman.com>  Fri, 08 Jun 2012 14:37:05 -0400
