Skip to content

Latest commit

 

History

History
116 lines (81 loc) · 3.92 KB

README.dkim.rst

File metadata and controls

116 lines (81 loc) · 3.92 KB

DKIM

DKIM involves applying a digital signature to every email to prevent email spoofing. We'll install and use OpenDKIM to sign emails before Postfix sends them.

Choose a domain and a selector

For simplicity, the sending domain should match your Discourse hostname (eg, discourse.jamielinux.com). Login to your Admin dashboard and set notification email accordingly (eg, [email protected]).

Pick a unique selector for the key pair. An identifier followed by the current date works well (eg, discourse-20150601).

Create a key pair

Install opendkim (or opendkim-tools on Debian). Run dkim-genkey.sh with your desired domain and selector.

$ cd files/dkim
$ ./dkim-genkey.sh discourse.jamielinux.com discourse-20150601

Two files have been created: a private key (discourse-20150601.private) and a public key (discourse-20150601.txt). Use the contents of the public key to create a TXT record. In zone file format, it looks like this:

; 't=y' indicates "test mode". Remove 't=y' once you know DKIM is working.
discourse-20150601._domainkey.discourse.jamielinux.com. IN TXT (
    "v=DKIM1; k=rsa; t=y;"
    "p=MIIBIjANBgkqhkiG9w0BAQEFAAOC... " )

Add these options to group_vars/all/main.yml:

dkim_enabled:  True
dkim_domain: "discourse.jamielinux.com"
dkim_selector: "discourse-20150601"

# Discourse notification emails will be signed by this private key.
# Ensure the matching public key has been published to DNS records.
dkim_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpQIBAAKCAQEA7+2mcjteiADpXQK5PQyfv+U2yxRxwTEhF2py/1y0ZY4Pybnr
  30+aQ4Q5RWRCDGm+nq8dZu0l//EuwBqC0GZDQyfCEl4ozHtL4SLYP3MGNXUjek3q
  hq7qT82dwKjqO5UtqTsrJVuCJjoNPixJUIX3bmCy3a2HeXwMk8JZor33tcnC2Lvk
  RnP7chlT4zlbrgO9XtNcXiBdyV1K1g+uqYHczQJehPXn5+lMFMRNHbns/p1+x7dz
  ... snipped ...
  sKwoinVMHG2amJS85DWKw7hRzJHrWUqqMcCPcwCxg3D0vOc+vD7snNGXqXKb1dX5
  82xQhRECgYEAnKxf25mG1iVW1cnuAM7d6m3eGhZWqZMZnQegBIGmbUs/IggOkKUB
  wAvhb5O1oVwctaqQxpdJfP/9ekXnt5iEWkj7pJX4OyDrSMyF7b6BOCbugCxQS2Ev
  Ie8xVj/6E40HAdA2+49SmPZJ4N6dw4s5ZlUHbYY/cA8pL+DmX/bghIU=
  -----END RSA PRIVATE KEY-----

Key rotation

Advice varies on how often to rotate. A 2048-bit key should probably be rotated every few years. Follow these steps:

  1. Generate another key with a different selector.
  2. Add a TXT record for your new key, but don’t change the TXT record for your old key. If you retire the old TXT record too early, emails sent before you rotated might fail validation.
  3. Update the variables in group_vars/all/main.yml. Re-run the playbook to rotate to the new key.
  4. Wait a couple of weeks and then retire the old key. Empty the contents of the p field from the old TXT record.
; This should remain in your DNS records.
discourse-20150601._domainkey.discourse.jamielinux.com. IN TXT (
    "v=DKIM1; k=rsa; p=" )

How do I know DKIM is working?

A few services can check for you, such as port25. To receive a report to [email protected], login to your Admin dashboard and send a test email to [email protected].

The email report sent to [email protected] should look like this:

SPF check:          pass
DomainKeys check:   neutral
DKIM check:         pass
Sender-ID check:    pass
SpamAssassin check: ham

Once you know everything is working, remove t=y from the DKIM record.

Further reading