Had some fun installing DomainKeys Identified
Mail (DKIM
for short) at work today and seeing as I had some problems I figured I'd
detail my experiences here, for future reference.
Short intro
The basic idea in DKIM is to be able to show that a given email message
came from a specific domain. In a way, it's like SPF but in reverse:
where SPF says that a given IP address is allowed to send e-mail (or not
allowed) for a specific domain, DKIM will state that a given e-mail
originated from a specific domain. Both technologies involve DNS - you
need to publish DNS records that a receiving server can use to check
that the message received is legit. The point being that if you can show
control over DNS records for the relevant domain, you gain a certain
amount of trust (as presumably not anyone can edit records for a given
domain).
Whereas with SPF all you need to do is create a TXT record, with DKIM
you'll need to setup some software. This is because DKIM creates a
signature of the e-mail sent and adds this signature as a header to the
e-mail. A receiver can then check that this signature is valid, upon
receipt, and thus make sure that the e-mail is legit.
Installation
I was working on a Debian Squeeze server, and the first of my worries
came from trying to install the two packages needed for the setup.
Essentially you want to install opendkim and opendkim-tools
apt-get install opendkim opendkim-tools
However, this gave errors about broken dependencies. The reason turned
out to be that opendkim was offered from Squeeze but opendkim-tools was
only found in Squeeze-backports. The two packages are incompatible with
one another (surprise!). The solution was to install the opendkim
package by specifying the newer version on the command line, so that
both packages got installed from Squeeze-backports.
apt-get install -t squeeze-backports opendkim opendkim-tools
This got the needed packages installed - so onto the next bit.
Configuration
Assuming a Debian installation, you'll now have an /etc/opendkim.conf
and an /etc/default/opendkim file. To this, we'll add a directory for
opendkim files (mainly private keys and some lookup tables). So
mkdir -p /etc/opendkim/keys chown opendkim:opendkim /etc/opendkim -R
Next, edit /etc/opendkim.conf, and make sure the following bits are set
UserId opendkim:opendkim KeyTable /etc/opendkim/keytable SigningTable /etc/opendkim/signingtable ExternalIgnoreList /etc/opendkim/trustedhosts InternalHosts /etc/opendkim/trustedhosts
In the setup/debug phase, you should use the following settings to help
narrow down problems:
LogResults Y LogWhy Y
Save opendkim.conf and edit /etc/opendkim/trustedhosts to contain
127.0.0.1 localhost
Save it, then edit /etc/opendkim/signingtable. Here, you put lines that
specify a domain and the matching DNS record ID to request a TXT record
from. So the form is
domain domain-key-dns
Stick in a line for every domain you need to sign e-mails for. Example
for plind.dk
plind.dk dkim._domainkey.plind.dk
After saving this file, open up /etc/opendkim/keytable and edit it.
Again, you want a line per domain to sign e-emails for - this time the
format looks like:
domain-key-dns domain:selector:path-to-private-key
The private keys haven't been created yet, but that doesn't matter - set
up a proper naming scheme for them now and stick to that, then you can
create keys before or after editing this file as you prefer. Example of
a keytable file for plind.dk
dkim._domainkey.plind.dk plind.dk:dkim:/etc/opendkim/keys/plind.dk/dkim.private
After editing this file, it's time to create the actual keys. CD into
/etc/opendkim/keys, create a directory per domain, then in each of the
domains run the following:
opendkim-genkey -r -h sha256 -d domain -s selector
Make sure to replace the domain with what you want to create keys for,
and the selector to match your setup. Also, make sure that you put in
'sha256' as the value for -h - I saw a couple of places online that used
rsa-sha56, which is invalid and might give you problems.
Example for plind.dk
opendkim-genkey -r -h sha256 -d plind.dk -s dkim
This generates a selector.txt and a selector.private file (substitute
selector with whatever you provided on the command line). From the
selector.txt file, you'll find the contents you need to create a DNS
record with. Remember, you need to create a TXT record for a domain
named like selector._domainkey.domain - so, using plind.dk as example
domain and dkim as selector, it would be dkim._domainkey.plind.dk.
When you create the TXT record, you only need to supply the content
within the quotation marks - leave the rest out.
After creating the private key with opendkim-genkey, step out on
directory and chown the folder and the files to opendkim - and make sure
that only dkim can read and write the files.
Then, lastly, it's time to edit /etc/default/opendkim to set details of
how opendkim can be connected with. I opted for a unix socket as they
are generally faster then TCP sockets, and we handle a fair amount of
email.
To set this, uncomment the line in your /etc/default/opendkim file that
looks like SOCKET:local:/var/run/opendkim/opendkim.sock - rename the
path as needed here.
Two things to keep in mind if you do this: if you try to connect postfix
and opendkim, you need to have opendkim create it's socket somewhere
that postfix can access it, which most likely means in
/var/spool/postfix as postfix will probably run chrooted. I created an
opendkim directory right under /var/spool/postfix, to put the socket in.
The second thing to keep in mind is handling permissions for the socket.
I found I needed to set the socket to 0777, before postfix could access
it properly. To support this, you'll also need to change the UMask
setting in /etc/opendkim.conf. After taking care of both, I could get
postfix to successfully connect to opendkim.
Lastly, restart opendkim and make sure that it's running - that way
you'll know if you made any mistakes along the way.
Connecting to postfix
To have postfix connect to opendkim, you need to set a couple of
settings in /etc/postfix/main.cf. Specifically, edit the file to include
these:
milter_default_action = accept milter_protocol = 6 smtpd_milters =unix:/path/to/socket non_smtpd_milters = unix:/path/to/socket
Remember that the path to the socket is relative to the chroot of
postfix, if it's running chrooted.
Finally, restart postfix to refresh the configuration, then try to send
e-mail with one of the domains you set up keys for. Try sending it to a
Gmail account (you should some extra info displayed for the e-mail) or
use www.mail-tester.com to check that a DKIM was added properly.
In case you experience problems, use the debugging settings of opendkim
and check the syslog for error messages.