Postfix + OpenDKIM (DKIM) configuration example

20 April 2013

In this tutorial you will learn how to configure Postfix together with OpenDKIM in order to send signed messages according to DomainKeys Identified Mail (DKIM).

Introduction

One of the standard and widely used email message sender authentication mechanism is DomainKeys Identified Mail (DKIM). DKIM relies in private/public key pair cryptography (asymmetric cryptography).

The message sender holds a private key that is used to sign messages he sends. The resulting message digest is included in the mail message itself as a MIME header. The public key is published as a DNS entry, so when a receiver receives a signed message he fetches the public key and then checks if the message content, together with the included digest, are legitimate and were not tampered by any means.

This is straight-forward asymmetric cryptography.

The tutorial considers the following software and environment:

Ubuntu 12.10
Postfix 2.9.6
OpenDKIM 2.6.8

Note: This tutorial assumes that you have already configured a Postfix mail server instance. If you haven't configured Postfix yet you should first go through the following tutorial: Postfix Mail Server configuration tutorial.

Note2: This tutorial relies mostly in configuration. The entries we are adding or modifying are kind of self explanatory. If you need clarification on some configuration entries please ask in comments section (or check Postfix / OpenDKIM reference documentation).

Installing OpenDKIM

We will integrate our Postfix instance with OpenDKIM. OpenDKIM will then be used to sign all messages sent by Postfix. In order to install OpenDKIM issue the following command:

apt-get install opendkim opendkim-tools

Generating the keys

Now we will generate the needed private and public keys. We will assume that the keys will be generated in:

/etc/opendkim

Place yourself in /etc/opendkim and issue the following commands:

openssl genrsa -out private.key 1024
openssl rsa -in private.key -out public.key -pubout -outform PEM
chmod 600 /etc/opendkim/private.key

Your private key will be stored in private.key and your public key will be stored in public.key

Creating the hosts file

We will create a hosts file. This file contains the hosts which are considered internal so any message sent to this hosts does not need to be signed by our Postfix instance. Create the following file:

/etc/opendkim/opendkimhosts

Insert the following contents in the file:

127.0.0.1
localhost
# Your IP addresses (one per line)
215.222.32.54
#Your hostnames (one per line)
example.com

Configuring OpenDKIM

Now we will configure OpenDKIM. Edit the following file:

/etc/opendkim.conf

Comment the following line:

#UMask 002

Insert the following lines:

Domain *
KeyFile /etc/opendkim/private.key
Selector mail
InternalHosts /etc/opendkim/opendkimhosts
ExternalIgnoreList /etc/opendkim/opendkimhosts
AutoRestart yes
Background yes
Canonicalization simple
DNSTimeout 5
Mode sv
SignatureAlgorithm rsa-sha256
SubDomains no
#UseASPDiscard no
#Version rfc4871
X-Header no

Now edit the following file:

/etc/default/opendkim

Insert the following line:

SOCKET="inet:8891@localhost"

Configuring Postfix

Now we need to configure Postfix. Edit Postfix main.cf file and add the following lines:

milter_default_action = accept
milter_protocol = 2
smtpd_milters = inet:localhost:8891
non_smtpd_milters = inet:localhost:8891

Setup the DNS entry

The last step is to make our public key to be publicly available. We set it up as a DNS entry. Go into your DNS configuration and add the following TXT record:

entry name:
mail._domainkey.example.com

entry value:
v=DKIM1; k=rsa; p=[THE_CONTENT_FROM_YOUR_PUBLIC_KEY_FILE]

Note: The mail selector in bold is the selector you configured previously on /etc/opendkim.conf

Note2: The content of your public key file is placed in the record value without the square brackets.

Testing

When you send a message and inspect the message content you will see a header similar to the following:

DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=example.com; s=mail; t=1366348901; bh=pbdwLjYLg5ab1IEde1m4Cv2fEC0gJj9EWQ10C2GCIWE=; h=Date:From:To:Subject:From; b=bY0PIkyw+X5GNWEcnCpLmlN+tyGF4tAFQ3OKo01TeUtrx8HQsEPfKhumtayNpmNE1 JqtN91hodv/EjqnB6I/sq71YKVpnlVt7iy9I6FeWakirrlW9Oh4c6kaMMfkr0rKGRD jQ8A3i8hIwRJS5b32d4eg48uKG3qAlosB9R5W3EQ=

Configuring a mail server can be problematic especially if you are doing it for the first time. Postfix provides a robust logging mechanism and by looking at the logs you can almost certainly check what went wrong. The log file is located at:

/var/log/mail.log