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 | Domain Name | Time to Live (TTL) | DNS Record Type | Contents |
---|---|---|---|---|
"The selector is used to identify the keys used to attach a token to a piece of email." | The record is for the email domain specified here. | In order to speed up domain name resolution requests, DNS servers will cache information about a domain. Time To Live specifies the number of seconds a DNS server should keep a record cached before refreshing it. If you make updates to your DNS records during this period, they will not be propagated until the TTL has passed. | A valid DKIM record must be a TXT-type record. | Contents consist of the version (v=DKIM1; ) and the public key data (p=MIGf… ) |
dkim | ._domainkey.twitter.com | 271 | TXT | "v=DKIM1\; p=MIGf...[truncated for readability]" |
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.
Take care if using an online wizard to create a DKIM record for you. Do not upload or reveal your private key to anyone, and make sure to clean up any formatting errors in the generated code.
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."
Resources
- February 24, 2022: Fixed broken link to DKIM in Amazon Simple Email Services guide.
- March 28, 2019: Updated reference links.
- August 30, 2018: Updated reference links.
Feedback
0 comments
Please sign in to leave a comment.