Home Download FAQ / Knowledge Base Screenshots Documentation Support

Citadel DKIM/Domainkey signature HowTo

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:

  dkimproxy.out --conf_file=/usr/local/etc/dkimproxy_out.conf

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

Google mail 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 !
There are no social media links here. Enjoy a friendly Citadel community instead. Or go outside.