Enable DKIM in Postfix on Ubuntu

[supermathie (Michael Brown)]

I’d like to set up DKIM to help ensure that email notifications from my self hosted Discourse instance actually get reliably delivered.

DomainKeys Identified Mail (DKIM) lets an organization take responsibility for a message that is in transit. The organization is a handler of the message, either as its originator or as an intermediary. Their reputation is the basis for evaluating whether to trust the message for further handling, such as delivery. Technically DKIM provides a method for validating a domain name identity that is associated with a message through cryptographic authentication.

How do I do this?

[supermathie (Michael Brown)]

You’ll need to enable DKIM signing on your MTA of choice that will handle outbound email.

Here at Discourse, we use Postfix on Ubuntu.

References

• DKIM main site
• Ubuntu Postfix/DKIM documentation

First-time setup of opendkim:

1. Install opendkim and opendkim-tools:
   sudo apt-get install opendkim{,-tools}

2. Make the following changes in /etc/opendkim.conf:

    Syslog                  yes
    UMask                   002
    Canonicalization        relaxed/simple
    SubDomains              yes
    OversignHeaders         From
   
    KeyTable                /etc/opendkim/KeyTable
    SigningTable            /etc/opendkim/SigningTable
    ExternalIgnoreList      /etc/opendkim/TrustedHosts
    InternalHosts           /etc/opendkim/TrustedHosts
    
    Socket                  inet:8891@localhost
   

3. Add to /etc/opendkim/TrustedHosts (adjust as necessary):

    127.0.0.1
    localhost
    .internal.dns.name
    192.168.0.0/24
   

4. Add to /etc/postfix/main.cf:

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

5. Add -l to daemon options in /etc/default/opendkim

6. Reload opendkim and postfix

For each domain for which you’ll sign mail

We’ll use howtogeek.com as an example:

1. Generate the signing keys (as root):

    mkdir -p /etc/opendkim/keys/howtogeek.com
    cd !$
    opendkim-genkey -r -d howtogeek.com -s discourse
    chgrp opendkim *
    chmod g+r *
   

2. Add the following to /etc/opendkim/KeyTable:

    discourse._domainkey.howtogeek.com howtogeek.com:discourse:/etc/opendkim/keys/howtogeek.com/discourse.private
   

3. Add howtogeek.com to /etc/opendkim/SigningTable:

    howtogeek.com discourse._domainkey.howtogeek.com
   

4. Add the public key (found in /etc/opendkim/keys/howtogeek.com/discourse.txt) to DNS

5. Verify setup:

    $ host -t TXT discourse._domainkey.howtogeek.com
    discourse._domainkey.howtogeek.com descriptive text "v=DKIM1\; k=rsa\; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDEwNwDtyZAEXy8ElFu/YrJFfFn3XxlLmY/ErqNj+9gYoc+EW/vWkYqm8lvkgeKCGxaum54LajGAOfOdDd4dNwlqCPhQ9V2pMoRC8cvpDXnyC5uWNbnPAfeneDhEr5/iHcEETsuooTmxOwoRtShttksN+evOL9HdoBNe4q00oH4PQIDAQAB"
    $ sudo opendkim-testkey
    opendkim-testkey: /etc/opendkim/keys/howtogeek.com/discourse.private: WARNING: unsafe permissions
   

You can ignore the ‘unsafe permissions’ warning as we know that it’s OK. opendkim-testkey complains if the file permissions are anything but 0600, but I see no reason to allow the opendkim user to modify the file.

1. Reload opendkim:

    $ sudo service opendkim reload
    Restarting OpenDKIM: opendkim.
   

Now test! Send a test email from the Discourse control panel and you should see a DKIM header:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=discourse.org;
    s=discourse; t=1375244260;
    bh=qJH3NcptcxBvtKlFtHRUKKT9+KOQ/a4wjqyRN5+Wjac=;
    h=Date:From:Reply-To:To:Subject:List-Id:From;
    b=GtKwkX5mb6Cb4uVE0UDb01imuzPPtruxCK3FVaKyoayYYV
    6G0LJ28nPnBVU0NcdfMAJg8Ox2t48esVvnJGIjCrzB38pOSq
    HFbvNG9WXQ+jQ9aDrOGReVNNI80W+TomfTjR7V0Beo+foeeT
    ikVfXNLxfX/EZIroe9ZfhMGyXq0p0=

[codinghorror (Jeff Atwood)]

Also just as a reminder, I strongly recommend anyone configuring email in Discourse to send a test email. You can do this from the admin panel, under Email logs, at the top where the button says “send test email”.

This email contains crucial, extremely important tips to get your Discourse forum email notifications working:

This is a test email sent from your Discourse forum at:

http://forum.example.org

Email deliverability is complicated. Here are a few important things you should check first:

• Know how to view the raw source of the email in your mail client, so you can examine the email headers for important clues. in Gmail, it is the “show original” option in the drop-down menu on each mail.

• IMPORTANT: Does your ISP have a reverse DNS record entered to associate the domain names and IP addresses you send mail from? Test your Reverse PTR record here. If your ISP does not enter the proper reverse DNS pointer record, it’s very unlikely any of your email will be delivered.

• Is your domain’s SPF record correct? You can test your SPF record here.

• Check to make sure the IPs of your mail server are not on any email blacklists.

• Verify that your email server is definitely sending a fully-qualified hostname that resolves in DNS in its HELO message. If not, this will cause your email to be rejected by many mail services.

• Configure DKIM email key signing in your email software, and place the public DKIM key in your DNS records. This is not required, but will significantly improve email deliverability.

We hope you received this email deliverability test OK!

Good luck,

Your friends at Discourse

[codinghorror (Jeff Atwood)]

In this, as with any other email deliverability stuff, remember to check the email headers to see if it is working. For Gmail that is the “Show Original” drop down menu option on the email.

When DKIM is configured correctly, you should see a confirmation of some kind in the email headers (using GMail in this example)

Authentication-Results: mx.google.com;
   spf=pass (google.com: domain of info@discourse.org designates 64.71.148.3 as permitted sender) smtp.mail=info@discourse.org;
   dkim=pass header.i=@discourse.org

When you only have SPF and Reverse PTR configured, you’ll just see

Authentication-Results: mx.google.com;
   spf=pass (google.com: domain of info@discourse.org designates 64.71.148.3 as permitted sender) smtp.mail=info@discourse.org

The magic phrase you are looking for in the GMail headers specifically is

dkim=pass