How to configure DKIM with PostFix, a step by step guide

How to configure DKIM ?

This page is a step by step page that will show you how to sign outgoing email with the DKIM specification.

OpenDKIM will sign the email passed by Postfix and every receiver can check the email authenticity through the public key published in the DNS record of the domain.

The signature is added in the email in an header field. Example:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bytle.net;
	s=vps748761.ovh.net; t=1591988898;
	bh=WBggpZrfs7F0OzQkyE7LiZPHyfFFhl7N4CNav2f5YVw=;
	h=Date:To:Subject:From:From;
	b=ByN4Iw4U9RP8bzaPK0n3HJbFlvI60ett+V9pkoli+UNtdAcSdq/ANc3hL71PzjrT4
	 3yyTjK3MC5e2f/k+BAnIaAgnradAK/1CbMF4vMZVD6WoVIx7KTZlfWsW39Ir8PhqYQ
	 4TKvPpDUx8ToxUz1gwQlxJoExYW3McXJ2WdvUAf8=

The configuration is done with OpenDkim installed as a milter software of Postfix (for the MTA) on a CentsOS (Redhat) linux box.

Steps

To install opendkim as a milter to an MTA, you need to perform the following steps:

Install openDKIM
Generate a private and public key pair (to sign the mail) (skipped if you will only be verifying)
Post the public key in the DNS space (also skipped if only verifying)
Configure openDKIM:
- Choose a local socket interface between the filter and your MTA
- Define a mapping between the domain and the key
Configure the mail transfer agent (MAT) (ie Postfix)
Restart all and test it

Installation

If you want to install it from the source. See the install doc

install the EPEL repository
install OpenDKIM

yum install -y opendkim

Generate the key and the DNS record with opendkim-genkey

The opendkim-genkey will:

generate a private key in PEM format
and output a TXT record containing the matching public key appropriate for insertion into your DNS zone file.

The private key signs the message (ie encrypt) and the public key can decrypt it.

As there is only one public key that can decrypt a message encrypted by the private key, the authenticity of the sender can then be verified.

This is a feature of the Public Key Cryptography system.

Syntax:

opendkim-genkey -s SELECTOR -d DOMAIN
# example with your brand name
opendkim-genkey -s brandName -d example.com

where:

SELECTOR: a name given to the key to select the DNS record that stores the public key.
DOMAIN is the DNS name of the domain

If you want to test it, you can add the --testmode argument.

testmode tells the verifiers that they should not take any real action based on success or failure of the use of this key after verifing a message.

In the generated TXT record, you will find back a t=y that you can remove to enter in production mode.

Two files should have been generated:

the private key with the following name $(hostname).private
the txt record (and the public key as value) with the following name $(hostname).txt

Verification of the file existence:

the TXT record with the public key where you can verify your domain at the end of the file.

cat brandName.txt

yourSelector._domainkey	IN	TXT	( "v=DKIM1; k=rsa; "
	  "p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQUtHxTD63yxwq5fmjJ3RtXw2NP5/QEiSq3Xx85faTHnnj3/PA/igwWaueDsoeUuZOpkL74gDNGWBoQPecRaFrAXdPoEKGDYNBeMXzIkWQOth9Oaq4N+38LV08Ui86so8B2BhcvgXiqpACsrPur0hbDQWI183tZve7MKMPs3KPIQIDAQAB" )  ; ----- DKIM key vps748761.ovh.net for bytle.net

The private (Should stay private, not shared). The private key encrypt the message and the public key decrypt.

ll brandName.private

-rw------- 1 root root 887 Jun 12 12:03 vps748761.ovh.net.private

DNS Zone

The next step is to publish the public key by creating a TXT DNS record with the help of the generated TXT file.

DNS DKIM value explained

The TXT record value generated has the form:

"v=DKIM1; k=rsa; " "p=public key"

where :

v=DKIM1 is the DKIM protocol version.
p=… is the public key (base64 encoded)
k= provide a list of mechanisms that can be used to decode a DKIM signature such as RSA

DNS DKIM Creation

If the DNS interface of your provider supports TXT input, you can just take the input of the TXT file and add it at the end.

Then you should see a TXT record with a DKIM value. Example with a snapshot of the DNS manager of my domain provider

where the public key DNS record should appear as a TXT resource record as:

SELECTOR._domainkey.DOMAIN
# in the snapshot
vps748761.ovh.net._domainkey.bytle.net.

where:

SELECTOR and DOMAIN are the value used when generating the key.

DOMAIN may also be specified:

the Domain option in the configuration file,
or the domain that would be returned from a KeyTable lookup.

DNS DKIM record test

You can verify that the key matches the private key with opendkim-testkey

opendkim-testkey -d DOMAIN -s $(hostname) -k $(hostname).private
# example
opendkim-testkey -d bytle.net -s $(hostname) -k $(hostname).private

If you got no message and an exit code of zero, that's all good.

echo $?

Private key

The key should be stored in a safe place.

As we installed it with the package, we will store it /etc/opendkim/keys In the official doc, you will see /var/db/dkim/

mv $(hostname).private /etc/opendkim/keys

The storage directory and the associated private key file should be owned by the user that will be executing the filter (preferably not the superuser) and be mode 0700 and 0600 respectively.

# The opendkim was created with the package installation
chown opendkim:opendkim /etc/opendkim/keys/ # should already by the case
chown opendkim:opendkim  /etc/opendkim/keys/$(hostname).private
chmod 0700 /etc/opendkim/keys # 0=rwx
chmod 0600 /etc/opendkim/keys/$(hostname).private # o=rw

OpenDKIM Configuration

The minimal configuration for OpenDKIM defines:

the socket
the domains and their key

FYI: The global configuration file can be found at:

/etc/opendkim.conf

Socket selection

The MTA and your opendkim filter communicate over a socket connection.

You can choose to use:

In case of a tcp socket, for selinux, the following command will need to be executed as the superuser, which declares the chosen port to be a milter application port:

# to see if SELINUX is enable
# cat /etc/selinux/config | grep -i SELINUX=
# if yes then
semanage port -a -t milter_port_t -p tcp <port>

The actual socket configuration of OpenDKIM is

##  Create a socket through which your MTA can communicate.
Socket	inet:8891@localhost

Mapping Key to Domain

KeyTable

OpenDKIM find the private keys with the KeyTable lookup file. It's a file that maps key names to signing keys. (private key)

Conf:

Enable the key table refile means regular expression file (ie regular expression are permitted)

KeyTable refile:/etc/opendkim/KeyTable

then change the mapping in the /etc/opendkim/KeyTable by adding the following line

SELECTOR._domainkey.DOMAIN DOMAIN:SELECTOR:/path/to/my/key
# or with this actual step by step
SELECTOR._domainkey.DOMAIN DOMAIN:SELECTOR:/etc/opendkim/keys/SELECTOR.private

It requires SigningTable be enabled.

SigningTable

This SigningTable is a file that maps:

email addresses (ie from the From: header field)
to one or several SELECTORs
in order to apply one or more signatures to outgoing messages.
and is a prerequisite of keytable

Conf:

Global conf The refile scheme enable regular expression in the SigningTable file . You could also used file to disable it

SigningTable refile:/etc/opendkim/SigningTable

SigningTable

# Wild card example (refile scheme)
*@DOMAIN SELECTOR._domainkey.DOMAIN

Operating mode

The operating modes are:

s (sign)
v (verify) - default
sv (sign and verify)

You need to change it at minimal to s in order to sign the email.

Mode	sv

Signing external mail

Optional

If you wish to sign mail that comes from sources other than the localhost address (127.0.0.1), include these in CIDR notation in the configuration file for the InternalHosts configuration option.

##  Identifies a set "internal" hosts whose mail should be signed rather than verified.
InternalHosts refile:/etc/opendkim/TrustedHosts

See also:

##  Identifies a set of "external" hosts that may send mail through the server as one
##  of the signing domains without credentials as such.
ExternalIgnoreList refile:/etc/opendkim/TrustedHosts

MTA configuration (Postfix )

Email - Postfix

smtpd_milters

smtpd_milters You specify SMTP-only Milter applications (there can be more than one) with the smtpd_milters parameter. Each Milter application is identified by the name of its listening socket;

Syntax:

smtpd_milters = inet:localhost:portnumber ...other filters...

With the OpenDkim Socket configuration of this tutorial (the default)

smtpd_milters = inet:localhost:8891

non_smtpd_milters

The non-SMTP Milter applications handle mail that arrives via:

the Postfix sendmail command-line
or via the Postfix qmqpd server.

non_smtpd_milters = inet:localhost:8891

Error handling

Optional

The milter_default_action property defines what to do in case of errors.

The following value can be chosen:

tempfail (default) respond with a temporary error status, so that the client will try again later.
accept to receive mail as if the filter does not exist
reject to reject mail with a permanent status.
quarantine action is like “accept” but freezes the message in the “hold” queue (from Postfix 2.6 or later)

milter_default_action = tempfail

Restart

Restart the services

systemctl restart opendkim
systemctl restart  postfix

Test

To test, we need to send an email and to see if the DKIM header was added.

If the test does not work, check the diagnostic section.

We show two ways to test:

via mail-tester - graphical and all-in test solution
via gmail - just send a message to check the header

Install a Mail Client

The client mail used is mail that you can install with the mailx package

yum install -y mailx

It's possible to send email with the sendmail command line of postfix

Mail tester

The first easy method to test is to send an email to the mail-tester website. They will then analyze it and give you a score.

Go to https://www.mail-tester.com/
Note the temporary email (ie [email protected])
And send an email

echo "Body: This is a test mail. Hallo Charlie" | mail -s "Subject: A big test" [email protected]

Gmail

Gmail allows you to see:

the original email (header)
and the test that they performs.

Send an email to your Gmail address

echo "Body: This is a test mail. Hallo Charlie" | mail -s "Subject: A big test" [email protected]

You can then verify the signing:

in the original email

or quickly in the dropdown:

Diagnostic

Verify that you private / public key configuration is working. See DNS DKIM record test

opendkim-testkey -d DOMAIN -s $(hostname) -k /etc/opendkim/keys/$(hostname).private

Check the mail log - postfix and openDKIM use syslog, you should find the log then in /var/log/ such as:

tail -f /var/log/maillog

Example of log where you can see that opendkim added the DKIM-Signature field.

Jun 12 20:57:17 vps748761 postfix/pickup[22362]: D572A1FBE8: uid=0 from=<root>
Jun 12 20:57:17 vps748761 postfix/cleanup[23285]: D572A1FBE8: message-id=<[email protected]>
Jun 12 20:57:17 vps748761 opendkim[23276]: D572A1FBE8: DKIM-Signature field added (s=vps748761.ovh.net, d=bytle.net)
Jun 12 20:57:17 vps748761 postfix/qmgr[22361]: D572A1FBE8: from=<[email protected]>, size=521, nrcpt=1 (queue active)
Jun 12 20:57:18 vps748761 postfix/smtp[23288]: D572A1FBE8: to=<[email protected]>, relay=gmail-smtp-in.l.google.com[173.194.76.27]:25, delay=0.57, delays=0.06/0/0.35/0.16, dsn=2.0.0, status=sent (250 2.0.0 OK  1591988238 r8si6848556wrn.39 - gsmtp)
Jun 12 20:57:18 vps748761 postfix/qmgr[22361]: D572A1FBE8: removed

Check that the DKIM process is started on the Socket port

netstat -tulpn|grep 8891

tcp        0      0 127.0.0.1:8891          0.0.0.0:*               LISTEN      21636/opendkim

Verify the postfix configuration

postconf -h smtpd_milters # inet:localhost:8891
postconf -h non_smtpd_milters # inet:localhost:8891

Documentation / Reference

This page was created with the help of the following references:

The README document (in the opendkim directory) covers the installation and configuration of opendkim.
A big thanks to easy engine
The postfix documentation can be found at MILTER_README