Index

DKIM

TL;DR

DomainKeys Identified Mail (DKIM) is a method to cryptographically sign email. The goal of DKIM is to reduce email spam and fraud. Receivers use DKIM as one of the methods for spam detection.

With DKIM the sending email system adds a cryptographic signature to the email headers using its private key. This signature is used by the receiving system to determine if the sender, and the email content, are to be trusted.

The domain owner (that's you) publishes the public key of the sender in the DNS of the domain. By doing so you tell the receivers that a sender that holds the corresponding private key is to be trusted to send email for your domain,

DKIM is considered an improved mechanism over SPF because it also protects the email content from tampering, and it doesn't suffer from the problems with email forwarding that SPF has.

Cryptographic signatures

To understand how DKIM works, you first need to understand what cryptographic signatures are, and how they work. If you are already familiar with cryptographic signatures and Public Key Infrastructure you can skip this segment.

A cryptographic signature is different from a 'human' signature.

A human signature is a handwritten scribble (like someone's name, of even an 'X'). If placed on a document, it proves (to certain extent) the identity and intent of the signer.

A cryptographic signature is a (very long) number, that uniquely and mathematically matches to the information that was signed. The signed information can be anything that can be digitally represented, such as a document, email or financial transaction. The cryptographic signature proves identity and intent if the signer, and also authenticity of the signed information.

A cryptographic signature is created by applying a mathematical function on the information to sign in combination with a cryptographic key. The key consists of two parts (represented as long numbers) that are mathematically linked to each other. One part is called the private key, it is meant to be kept secret by its owner. The other part is called the public key, and like the name suggests it is public (not secret) information. Here comes the clever bit: a cryptographic signature can only be created with the private key, but it can be validated by anybody using the public key.

You can sign a document with a private key, and publish the resulting signature along with the document and the public key. Anyone can use the public key to validate that the signature was created with the corresponding private key. This scheme is called a Public Key Infrastructure (PKI), it allows for anyone to validate a signature without needing access to the private key.

Unlike a human signature, a cryptographic signature is unique to the information that is being signed. For every document and key combination there will be a different and unique signature. If a single letter in a signed document was to be changed, the signature would no longer be valid for that document. This means that a cryptographic signature can be used to check if a signed document is authentic, thus not been tampered with. This also makes copying a cryptographic signature pointless, as it will only be valid for the original email.

Human signature Cryptographic signature
Representation Handwritten Large number
Proves Identity, intent Identity, intent and authenticity
Proof Judgement Math
Forgeable Easy Very hard to impossible

DKIM

DomainKeys Identified Mail (DKIM) leverages Public Key Infrastructure (PKI) to cryptographically sign email. The signature proves that the email is authentic and that the sender was authorized to use the domain name in the sender address. DKIM is defined in RFC 6376.

To use DKIM, an RSA key pair is created by the system that sends the email, this can be your email server, but also a cloud service such as Office365 or Mailchimp. The private key remains on the email server, the public key is shared with the domain owner. The domain owner publishes the public key through DNS as a DKIM record. The DKIM record is placed in the DNS zone of the domain that wants to allow the email service to send email for the domain.

The sending server automatically adds a cryptographic signature to every email that it sends using the private key. Any email service receiving the email will request the public key through DNS, and validate the signature using that public key.

If the signature is valid, it proves that:

By publishing a DKIM record in your DNS, you are saying "Any email service that proves it has access to the corresponding private key (by adding the signature) is allowed to send email for this domain."

By adding a DKIM signature to an email, the sender is saying "Here is proof that I have access to the private key that corresponds to the public key that you will find in the DNS of the domain that I am sending for"

By validating a DKIM signature of an email, the receiver is saying "I have found proof that this email is authentic and the sender was authorized to send email for this domain"

The DKIM DNS record

The public key to validate the DKIM signature is published in a DNS record for the domain. A DKIM record is of type TXT and must be placed in at address [selector]._domainkey.[domain]. The selector is an identifier for the DKIM key, more about this later.

A DNS query on [selector]._domainkey.[domain] may only result in 1 TXT type record maximum. If you have multiple keys, you can publish each corresponding public key with a different selector. That way different private keys can be used to sign the email. For example: You can have a key for your own mail server and one for a third party such as Mailchimp.

DKIM keys are not meant to ever change. If you need to use a new DKIM key, you should use a new selector also. Because DKIM records never change they can have a high time-to-live (TTL) value. A TTL of 1 day (86400 seconds) or more is not uncommon for DKIM records.

Here is an example of a DKIM record:

google._domainkey.mailhardener.com. 86400 IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgAF0AKrnAY2oscOh7jlBBPJDHgWO/HR/TxPr18yG6uFs3jVLkz1qZpI0QJX90aVnpPiu1C+6MZzUwzYYY/f8g8rVGxwj2D/anjih4sKUFmun2IluFiS93RcPZXYWNXor4gALdsdAVB7ak4/30l0uVAU3OEwFX77yWNT6BDSiobfpKMDG4TV4iZiohOlc1gHHX" "HYbLbcQ1uM9CLPkuqHKQkudLjvAbvl0eqDtAzThAahsmhl5Lc7Qru1SJShv47RxzIxShBL6MGTxEGiIR09244oQf++CmKCT8TPxptT/Y6mrLO5+t//dlvSVLsrKhF6xqZWwSOL0pskJiDdqDAxDGQIDAQAB"

We have a DKIM inspection tool available here, you can use it to inspect and validate a DKIM DNS record.

Field specification

The following information can be placed within a DKIM record:

Field Required Description
v Optional The version field. The default is DKIM1, which is currently the only acceptable value.
h Optional A colon-separated list of acceptable hash methods to be used with this key. Supported methods are sha1 and sha256.
k Optional The type of key. Valid values are rsa or ed25519 (see: How to use DKIM with Ed25519. Defaults to rsa.
n Optional Notes for the record, such as an identifier. Intended for humans (administrators), validators ignore this value.
p Required The public key data, BASE64 encoded.
s Optional A colon-separated list of types of services intended to be used with this key. Allowed values are * (all services) or email. Defaults to *.
t Optional A colon-separated list of flags for this key. Supported values are y to indicate this is a testing key. And s to require strict domain validation (this key is not valid for subdomains).

The selector

Every DKIM record must have a unique identifier known as the selector. The selector is part of the address that is used to query the DKIM record in the DNS. A DKIM signature in the headers of an email will also contain this selector, so the receiver knows where to query the DKIM DNS record.

Since the selector is used as the DNS name of the DKIM record, it can contain only characters that are valid for a domain name. So a maximum of 255 characters containing letters, numbers and hyphens (-).

Spaces, dots, and underscores are not allowed. As with all DNS names, a selector is not case-sensitive.

Because the v=DKIM1 part in the DKIM record is optional (unlike, for example, the version indicator in a DMARC record), there is no way for a validator to distinguish a DKIM record from any other TXT type DNS record. It is therefore required that a DNS query on the selector address yields no more than one TXT record.

The DKIM signature header

An email message consists of 2 parts:

The headers contain information such as the date, subject, return address and more. The headers are used by email servers and clients to process the email. Most email programs will hide the headers from the user.

When using DKIM, a DKIM-Signature header is added to the email that contains the DKIM signature, and other implementation details instructing the receiving system on how to validate the signature.

The DKIM header is added to an email by the sending service. An email message may contain more than one DKIM header, as an email can be signed by multiple parties and by multiple keys.

Here is an example of an email with a DKIM header:

From: John Doe <john@example.com>
To: example@mailhardener.com
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; 
    d=example.com; h=subject:from:to; 
    s=selector1; bh=edgxW+m2NmYw6Pxq6wY+B9YA+Z8SvmZ+y5zRCKxm6ik=; b=ClVxK8f
    QZzK9147Bc/s4wrvS0VZCpdDuwTvGWzj/cWCjiDsY/Y3ShRnsv/2lTe0nXW01OB7
    hanPe3VEm1fuR0wV+G8ODeiV43NuELKVwWvhZD7Rb0B7SlBWpPBuJH6A+q8i+rwe
    61p6Ay5Ff6EMGnqeHS/RiRZqa8rjViLXUQkM=
Subject: This email is signed with DKIM

This is an email signed with DKIM

In the sample email message the DKIM header was added by the sender in order to prove that the service that sent the email was really allowed to send email on behalf of example.com.

The DKIM header contains the domain name d=example.com, and the selector s=selector1. This means that the receiver is supposed to query the DNS service for a DKIM TXT type record at selector1._domainkey.example.com.

The bh field contains the BASE64 encoded hash digest of the email body. The h field indicates which headers of the email were also included in the signature input. The a=rsa-sha256 indicates that the SHA256 hash function was used to create the digest. Finally, the b field contains the BASE64 encoded RSA signature.

Field specification

Here is the full list of fields that can be used in the DKIM-signature header:

Field Required Description
v Required The version field. This is a numeric field, currently the only supported value is 1.
a Required The signature and hash algorithms used to create the signature, in format [sig]-[hash]. The recommended algorithm is rsa-sha256.
b Required The signature data, BASE64 encoded, created with the algorithm defined in a.
bh Required The BASE64 encoded hash digest of the message body, created using the algorithm defined in a.
c Optional The message canonicalization method used, default is simple/simple.
d Required The domain claiming responsibility for this signature. This is the domain that is queried for the DKIM DNS record to obtain the public key.
h Required A colon separated list of the email headers that were included during creation of the signature.
i Optional Email address claiming responsibility over the created signature. The domain part in the address (after the '@' character) must match the value in d.
l Optional Body length in octets used as input for the hash function, defaults to the entire message length.`
q Optional The method how to retrieve the public key. Defaults to txt/dns, which is currently the only allowed value.
s Required The public key selector, together with the d value this determines the address for the DNS query to fetch the DKIM DNS record.
t Recommended A UNIX style timestamp of the time when the signature was created. If not set, the creation date is unknown.
x Recommended A UNIX style timestamp of the expiration of the signature. After this date a validator should no longer accept the signature. If not set, the signature never expires.
z Optional A vertical-bar (|) separated list of all email headers that were present during creation of the signature.

Debugging DKIM issues

Debugging DKIM issues can be frustrating, as email services (by design) do not give feedback when email is rejected.

If you are experiencing DKIM related issues with one of the services you use to send email on behalf of your domain, there are some simple steps to take to debug the issue.

The easiest method is by sending yourself an email from the service you are experiencing problems with, then inspect the email headers using your email client.

  1. Verify that the sender address (in the From header) is actually set to your domain. The means that the part of the sender address after the '@' sign must match your domain.
  2. Verify that at least one DKIM-Signature header has your domain in the d= section of the header.
  3. Verify that the correct selector is used in the s= section of the DKIM-Signature header found in step 2.
  4. Verify that the DKIM selector exists at [selector]._domainkeys.[yourdomain], and that it is a valid DKIM record. You can use our DKIM record validator to verify the record is valid.

Must receiving email services will add debugging headers to the email before delivering it to the inbox. Check if you can find a Authentication-Results header, it should contain information on SPF, DKIM and DMARC results, and whether the validation has passed or failed.

Note that a DKIM header may be found valid, but that does not necessarily imply the email is DKIM aligned, see more about DKIM alignment in the section below.

DMARC DKIM alignment

As DKIM is optional to use in email, a malicious sender may just send email without a DKIM-Signature header, or just send the email with a DKIM-Signature for a domain that they control.

To mitigate this weakness in DKIM, DMARC may be used to mandate that any email received claiming to be from your domain, must be at least SPF or DKIM aligned.

DKIM alignment means that there must be at least one DKIM-Signature with the d= value set to the domain that is used in the RFC5322.From address (in the From header).

An email containing a DKIM header for a different domain than the one used in the From header is considered DKIM verified, but not DMARC aligned.

Advantages of DKIM over SPF

As explained in our document about SPF, SPF is also used to authorise a mail server to send email for a given domain. So why use DKIM, if SPF is much easier to set up?

This does not mean that DKIM is a replacement of SPF. SPF should still be used as it is a quick and effective method for receivers to perform basic verification of email.

Further reading

Tools

Updates

Share your thoughts!

On last thing: If you have questions, comments or thoughts on this article, don't hesitate to shoot us an email.

You can also follow and reach us on Twitter @Mailhardener.

With Mailhardener you can configure, validate and monitor your domain for all aspects of email security. Mailhardener is free to use for a single domain.
Sign up now