How to Set Up DKIM Records

DomainKeys Identified Mail (DKIM) provides a way for organizations to claim ownership of their emails using cryptographic keys, which helps stop unauthorized use (spoofing) of a company's email domain name. A DKIM record is part of a domain's DNS record.

Setting up DKIM requires three steps:

• Create a key pair.
• Add a DKIM record containing the public key to your DNS records.
• Set up DKIM on your mail server(s) for signing mail.

If you are already familiar with DKIM, skip ahead to Create a Key Pair.

How DKIM Works

A company employee sending email uses a DKIM key file with their email client to sign the message as it goes out, or the company mail server signs it for them. The recipient sees a DKIM signature in the email, looks up the public DKIM record for the email domain, gets the associated key from the record, and uses cryptography to verify the signature (authenticity) of the email with the key.

A DKIM email signature is a base64-encoded string that represents a snapshot of the email contents as well as the signing key. Email signatures can't be reused because they are unique to that email message, so an attacker could not copy the signature and try to slip malware-laden messages under the radar that way.

Emails are signed in two ways: by the sender in their email client software, or by the email servers (mail submission agents, mail transfer agents) as the emails go out.

Example DKIM Record

One way to understand how DKIM is used is to look at existing DKIM records for a domain. There are a few ways to find a DKIM record for a domain. You will need to know the selector for the domain (explained in the next section) in order to look up the record. If you don't know the selectors that the domain is using, you can try using google (a common selector for organizations with email hosted by Google), default, and dkim as test selectors which may reveal the DKIM record(s) being used.

1) Use the command line on your system and enter the following:

dig google._domainkey.domain.com TXT

Where domain.com is the domain you wish to look up. Note that the dig software is available by default on Mac OS and Linux systems. Windows users can download the software from the Internet Systems Consortium's BIND website.

For example:

dig dkim._domainkey.twitter.com TXT

Returns the following result:

dkim._domainkey.twitter.com. 271 IN TXT "v=DKIM1\; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrZ6zwKHLkoNpHNyPGwGd8wZoNZOk5buOf8wJwfkSZsNllZs4jTNFQLy6v4Ok9qd46NdeRZWnTAY+lmAAV1nfH6ulBjiRHsdymijqKy/VMZ9Njjdy/+FPnJSm3+tG9Id7zgLxacA1Yis/18V3TCfvJrHAR/a77Dxd65c96UvqP3QIDAQAB"

2) If you prefer not to use the command line, use a website to look up the information for you. There are a number of freely available services on the web that can look up DKIM records using a domain name with a selector.

Anatomy of a DKIM record

Let's look at the DKIM record for twitter.com shown above.

Selector: A string of your choice to help identify a public key. Selectors make it possible to seamlessly replace public keys on a routine basis. A selector can be a date (march2016), a geographical location (massachusetts), a business unit (marketing), or even a combination (march2016.marketing), including arbitrary strings up to the DNS maximum label length. Changing the selector of the DKIM record means that mail would no longer be signed using the previous selector. 1

A selector is added to the domain name, for instance:

dkim._domainkey.example.com

The _domainkey. prefix is used by DKIM and is standard with all DKIM configurations (can't be changed). But the selectors can, and they can be separated by periods as well, for instance:

march2016.dkim._domainkey.example.com

Each selector must have its own DKIM record. You may set up as many DKIM records as you like.

Create a Key Pair

Use OpenSSL or other SSL / TLS implementation of your choice to create an RSA key pair. For example:

openssl genrsa -out domain.com.private 2048

creates a 2048-bit RSA private key file called domain.com.private, where domain.com is your email domain. This naming is to help stay organized and is not part of any requirement.

Extract the public key like so:

openssl rsa -in domain.com.private -out domain.com.public -pubout -outform PEM

Look in the domain.com.public file, copy the contents between the begin and end statements, and make sure to take out new lines so that it is all one line. This is the portion you will use in your DKIM record, in the p= tag.

Add DKIM record to DNS records

Using an example selector and the public portion of an RSA keypair, we'll assemble an example DKIM record, with 21600 seconds as the TTL:

• Selector: yourselector._domainkey.yourdomain.com

• Public portion of DKIM key:

  MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/ zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto /NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB

Assembled in the proper DKIM format:

yourselector._domainkey.yourdomain.com 21600 IN TXT "v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB"

Once you have a DKIM record ready, you can add it to your domain by configuring it on your authoritative name servers or your DNS provider’s administrative control panel. Ensure the new record type you are creating is a TXT record.

Depending on your DNS provider you may also need to escape the semicolons with \ and include the double quotation mark around the contents.

Using a control panel

If using a control panel, yourselector._domainkey will go in the hostname field. The contents of the record (version and public key tags) go in the space provided, and may be alternately called “text” or “contents” or “body.” If your control panel provides some other measurement of Time to Live (minutes, perhaps) be sure to convert your chosen TTL seconds to that time format.

Use Token for Signing Email

At this point you will need to install an implementation of DKIM on your mail server and configure it to use your selectors and the key files generated for your domain (see Create a Key Pair above). Key files can also be created while setting up your DKIM implementation of choice.

To help you get started, please consult the following guides:

• Configure DKIM with Postfix on Debian (Note that the opendkim package is available for many Linux and BSD distributions)
• DKIM Signing Agent for Microsoft Exchange Server
• DKIM in Amazon Simple Email Services
• DKIM - Exim tutorial

Expiring or Removing DKIM records

To transition from one selector to another, ensure that records exist for both the previous and the new selectors. Phasing out a key is as simple as removing the record after the transition period. From RFC-6736:

If a domain wishes to change from using a public key associated with selector “january2005” to a public key associated with selector “february2005,” it merely makes sure that both public keys are [available] … concurrently for the transition period during which email may be in transit prior to verification. At the start of the transition period, the outbound email servers are configured to sign with the “february2005” private key. At the end of the transition period, the “january2005” public key is removed …” ^[1]

Re-using Selectors

Do not re-use selectors. Doing so "makes it impossible to tell the difference between a message that didn't verify because the key is no longer valid and a message that is actually forged. For this reason, Signers are ill-advised to reuse selectors for new keys. A better strategy is to assign new keys to new selectors."