by Mark Dammer, June 2008
This HowTo only explains how to get your outgoing mail signed with a valid Domainkey / DKIM signature. It does not cover verification of incoming mail. It is recommended to use SpamAssassin for this purpose (see dkimproxy manual).
Warning: An improper DKIM/Domainkey setup can cause mail from your site being rejected or tagged as spam. http://www.dkim.org has a lot of information and a site offering and listing mail reflectors for testing as well (http://testing.dkim.org)
Requirement: A second SMTP server to relay outgoing messages to. This can be your ISPs SMTP server. You may have already configured that server as a “smarthost” in your citadel configuration. An alternative is a postfix installation running on your system.
1. Install the Net::Server and Mail::DKIM perl modules and their dependencies via CPAN
2. Download and install Dkimproxy. You get dkimproxy and the docs here: http://dkimproxy.sourceforge.net/ Follow the instructions on the page to build dkimproxy and to generate the keypair.
3. Copy /usr/local/etc/dkimproxy_out.conf.example to dkimproxy_out.conf and edit it as follows:
# specify what address/port DKIMproxy should listen on listen 127.0.0.1:10027 # specify what address/port DKIMproxy forwards mail to relay put_your_ISPs_smtp_server_here:25 # specify what domains DKIMproxy can sign for (comma-separated, no spaces) domain yourcitadelmaildomain.org # specify what signatures to add signature dkim(c=relaxed) signature domainkeys(c=nofws) # specify location of the private key keyfile /usr/local/etc/dkim/keys/private.key # specify the selector (i.e. the name of the key record put in DNS) selector selector1
4. Publish your public key on your DNS server as described in the installation.
WARNING: If you are configuring your DNS via a webinterface you may have to leave out the quotation marks. Test this carefully as wrong quotes may cause a wrong TXT entry or mess up your entire zone configuration !!!!!!!!!!
It is advisable to create a second TXT record to create a DKIM policy:
_domainkey IN TXT "o=-; t=y"
This entry tells the testing server that this site is signing all messages, but that it is still in testing mode. You can remove the t=y once you are VERY VERY sure that your setup works. DO NOT CHANGE IT TO t=n !
Changing o=- to o=~ tells the server that not all messages coming from this site are signed.
It may take up to two days for your DNS setup to be propagated through the internet. You can check the DNS records with the following Linux commandlines:
host -t TXT selector1._domainkey.yourcitadelmaildomain.org should return the key record host -t TXT _domainkey.yourcitadelmaildomain.org should return the policy record
5. Configure your Citadel server to use dkimproxy as smarthost.
For this step you login as administrator and you go to “Domain Names and Internet Mail Configuration”.
Enter 127.0.0.1:10027 in the smarthosts field and press “Add”. Delete all other smarthosts.
6. Open a terminal as root and start dkimproxy manually via the following commandline:
You can “daemonize” dkimproxy by using the –daemonize and maybe the –pidfile= options in a startup script once you are sure your setup works fine
7. Send a test message from Citadel to an outside email address and check that the message source contains DKIM and Domainkey - headers. Once that works you can try one of the reflectors on testing.dkim.org to see if your message passes their test. Another good test site is http://www.mailradar.com/domainkeys
Googlemail is verifying Domainkeys and DKIM as well. The message source of a signed message received by googlemail should contain something like a “dkim=pass” entry in the “Authentication-Results” header field.
9. Switch your DKIM setup out of testing mode by removing the t=y entry from DNS (See 4.)
10. Have a cup and enjoy your Citadel system !