dkim-filter with sendmail

dkim-filter is a milter for sendmail/postfix to implement signing and verifying emails according the DKIM-standard.

installing dkim-filter on Ubuntu

I think dkim-filter is easy to install on any system, but on ubuntu its just

apt-get install dkim-filter


I didnt had to copy and edit any M4-files as described in various howtos. I use Ubuntu 8.04 LTS but I assume its the same on any more recent Ubuntu.

configuring dkim-filter


On Ubuntu you will have a file /etc/default/dkim-filter with only a socket-directive in it. I recommend commenting this line out cause it will override any directive you’ll set in dkimfilter.conf.

The main-config is in /etc/dkim-filter.conf and its well documented in man dkimfilter.conf. I strongly advice to use KeyList instead of KeyFile and dont forget the InternalHosts-directive which is what many Howtos miss.

Here is my dkim-filter.conf .. Please note that the paths are special to my system, so please adapt.

Syslog                  yes
AutoRestart             yes
AutoRestartRate         10/1h
AlwaysAddARHeader       yes
Background              yes
Canonicalization        relaxed
DNSTimeout              5
Mode                    sv
SignatureAlgorithm      rsa-sha256
SubDomains              no
UseASPDiscard           no
      
X-Header                yes
Socket                          local:/var/run/dkim-filter/dkim-filter.sock

KeyList         /etc/mail/dkim-keys/keylist
InternalHosts   /etc/mail/dkim-keys/goodhosts



The Socket-Directive and the communication with sendmail


The Socket is the communication between sendmail and the milter. It can be a internet-socket via tcp on a port or via a socket-file. I choose the file-socket.

Note that the Socket-Direktive is a bit .. strange. It seems that it has to be a directory where it can put its PID-file as well. Watch syslog for errors about the socket and then watch the running process (ps waux | grep dkim) which socket it has choosen and enter it in your configfile.

The path of this Socket is what you’ll have to specify in your sendmail.mc below !!

InternalHosts describes which mails shall be signed


By default dkim-filter is verifying all emails. Only emails from 127.0.0.1 (localhost) are signed by default. Well this is satisfying on very basic setups, on average mail-hosts its not.

Create this file and add all mailhosts that will send mail through this milter. 127.0.0.1 should be in it, and the Public Domainname of your server and of course every other mailserver that uses your mailserver as smarthost or DKIM-signing-instance.

Mine looks like this (my zimbra uses this server as smarthost !!):

127.0.0.1
server.mydomain.at
zimbra.mydomain.at



Please Note there is also a Directive ExternalIgnoreList that is not used on my system but can be used to specify hosts that will use your server as smarthost, but do their own DKIM-signing.

KeyList and setting a selector


The InternalHosts specifies which emails are signed. This setting specifies which keys are used for signing so of course it only applies for signing.

You have to create this file and it should look like the following:

*@mydomain1.at:mydomain1.at:/etc/mail/dkim-keys/mydomain1.at/default
*@mydomain2.at:mydomain2.at:/etc/mail/dkim-keys/mydomain2.at/default
...


The first column is the sender-glob. Any sender-adress that matched the glob will be signed for the domain that is specified in the second column and the key that is specified in the third column.
You can read below how to create the keys.
The name of the keyfile is very important. (not that path, just the name). Its the SELECTOR. The Selector is very important for setting up your DNS-record below. The selector is kind of the subdomain that will hold the key for your domain as TXT-record. default is a common selector. mail another, but I guess PINKCROCODILE wont hurt either.

Creating a key


go to the folder where you want to create your keys. I recommend using a own subdirectory for each domain. You will not override your own files then and can use the same selector for all your domains.

create the directory and go to it and then run

dkim-genkey -d mydomain1.at
This will create two files:

  • default.private
  • default.txt


rename default.private to default or whatever you want to use as selector. Remember: the name of the key defined the name of your selector !!

you can use

dkim-genkey -s myselector -d mydomain1.at
to have the files created as myselector.private and myselector.txt, but you must remove the trailing ‘.private’ anyway, but this is necessary if you have all keys in one folder

configuring sendmail


You have to add the milter to your sendmail.mc which might be located in /etc/mail
Add the following line to sendmail.mc and be sure not to touch any other line if you are new to sendmail. sendmail.mc is very sensitive about leading whitespaces and such stuff.

MAIL_FILTER(`dkim-milter’,`S=local:/var/run/dkim-filter/dkim-filter.sock,F=, T=C:10m;S:10m;R:20m;E:20m’)
This defines a milter. I named the milter dkim-milter. This name is used in the next line you have to add. Then after the S= you need to specify the Socket as descibed in dkim-filter.conf. For the meaning of the other parameters please check your sendmail-docs or just use the values I used :)

And then you have to add another line to sendmail.mc - or - if you use any other milters, add this milter to the existing ones.

define(`confINPUT_MAIL_FILTERS’, `goldmilter,dkim-milter’)
There is only one confINPUT_MAIL_FILTERS-lines in each sendmail.mc, so dont add another one if there is already one !!. I have two milters in my system so I have to milters specified in this line.

If dkim is the only milter you use, its just dkim-milter then:

define(`confINPUT_MAIL_FILTERS’, `dkim-milter’)

After you are are ready, you will recompile sendmail.cf by entering the directory this two files are located in and running make and restarting sendmail.

cd /etc/mail
make
/etc/init.d/sendmail reload


watch the logs and please not that dkim-filter should be started before sendmail is started or sendmail will complain that it cant find the milter cause the socket does not exist yet. Its created by the Milter.

In a nutshell: sendmail is a program and dkim-filter is a program and they both communicate via the Socket we specified. dkim-filter is actually a milter which means that its a program that is integrated in every step of emailcommunication and therefor can do things that are not integrated into sendmail.

starting dkim-filter


on ubuntu its /etc/init.d/dkim-filter restart
on other systems it will be different

adding the public key to your DNS-record


DKIM works with asymetric keys. We created the keys above.
Remember: There is a private key whos filename specifies the selector. And there is a second file that has a txt-extension. This file holds everthing we need to add to our domain-record.

If you run bind9/named, just open your master-file and add the content of this file.
For any other setup (like a webbased domain-tool) you create a subdomain and add a TXT-record for this domain.
The name of the subdomain depends on your selector (set by the name of your private keyfile) and is SELECTOR._domainkey. So if you followed my instructions you’ll have a name default._domainkey but this can also be any name you used as selector. The full name an also be pinkcrocodile._domainkey.mydomain.at.

Then create a TXT-record that holds the string in the txt-file (one of the two files you created when creating the key with dkim-genkey) starting with v=DKIM ....
Then reload your nameserver and check if you did it right at http://dkimcore.org/c/keycheck

checking if things work


* send yourself a mail and look at the mail-source * send a mail to your gmail-account and look at ‘show details’ where it should say signed by mydomain1.at
example of a real source:
(the selector is heavypedals here and not default - for promoting my cargobike-company www.heavypedals.at)

X-DKIM: Sendmail DKIM Filter v2.5.4 tng.goldfisch.at oBJKvEtj004420
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=heavypedals.at;
	s=heavypedals; t=1292792234; bh=ZMqIXD99NQ7chkcOn6W+a+0Kd4Cdcw3KCF+
	ZIw6Jq4o=; h=Date:From:To:Message-ID:Subject:MIME-Version:
	 Content-Type:Content-Transfer-Encoding; b=Ev1gSD7F/iCK+P86mbePJlTX
	0l0mQAGf93dmeyKN5EtoBoZY+s3c+LTKRrQKHsr4r8b7vj759JcxA/QVsS1G9DTcNds
	E+67ZrGSlFjXwefGFK+3jmQP4Gyji8GS+my0JIEb6LGxCzQQFSbgSsPHiu9+9Sziw9p
	NZnWGqECja9bg=



and gmail adds the following header if everything works well:

Authentication-Results: dkim=pass header.i=@heavypedals.at


ADSP - records


You can add more information to your DNS-zone. the adsp-record will distribute a policy how DKIM is used on your system. That means it tells recipient what to do if a mail from your domain is not signed !!

see http://www.dkim.org/specs/draft-ietf-dkim-ssp-04.html#rfc.section.2.6 and http://www.zytrax.com/books/dns/ch9/dkim.html

 
knowwiki/howtos/dkim-filter.txt · Last modified: 2011/02/06 12:03 by peter