DomainKeys Identified Mail (DKIM)


What is DKIM?

DomainKeys Identified Mail (DKIM) is an email validation system which associates a domain name with an email message, allowing an entity to claim responsibility for the message. This is setup as a digital signature that can then be validated by recipients of the message. A "DKIM-Signature" field is added to the email header, and then the verifier can validate this signature by querying the domain's DNS records.

How do I set it up?

We must first note that this is a fairly complex and technical process, so it's recommended you find a server administrator to help if you're not confident in your own skills.

Create the Selector and Associated Key Pair

The selector is used to identify the token you use in your email headers. It's mostly for internal reference (in case you have multiple sets of keys for a single domain), so can be something generic like "key1".

Selectors are typically a string of characters followed by a period "." followed by another string of characters. You can optionally omit the second string of characters.

The key pair consists of a private key and a public key. These are a standard RSA key pair, described here.

You can either generate a key pair using the openssl command-line tool, on your mail server:

openssl genrsa -out example.com.priv 1024
openssl rsa -in example.com.priv -pubout >example.com.pub

Or you can use this free online tool:

dkimcore.org/tools/

Publish the Public Key

  1. Log into whichever website you use to manage your domain's DNS records (typically your registrar)
  2. Create a TXT DNS record with name key1._domainkey.example.com and content:

    v=DKIM1;t=s;n=core;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+LUKd/ow+060XFkDa+IL+LlxJQy3nX1miB0g54nREo98VMMOGydf39pNCh9zwZTN3XS5mzCC++B4hzW2mzjLcAoMWxdwxXqBvUvcgyq9mcnRAe01HqZNiMgwjOX+9DvGI5D95Mvs7FgnlA0LbW7KP3SkxsVG7qTk1z/5pjl6hbwIDAQAB

    Note that the content is created by concatenating the literal string v=DKIM1;t=s;n=core;p= and the public key you generated above.

Attach the Token to your Emails

Generate the Body Hash

  1. Remove any empty lines at the end of the email body
  2. Add a trailing CRLF at the end of the email body, if one doesn't already exist
  3. Taken an SHA256 hash of the body, including the trailing CRLF, as described here. Keep this, you'll need it soon.

Generate the Header Hash

  1. Take a subset of the existing email headers and convert them to canonical form
  2. Convert the header names to lowercase, ie "Sender: joeshmo@example.com" becomes "sender: joeshmo@example.com"
  3. Make sure each header consists of a single line terminated by CRLF
  4. Within each line, replace any sequence of multiple spaces or tabs with a single space character
  5. Remove any extra spaces after the colon that separates the header name from its content
  6. Create an "empty" DKIM-Signature header such as:

    dkim-signature:v=1;a=rsa-sha256;bh=BODYHASH;c=relaxed;d=TOKEN;h=HEADERS;s=SELECTOR;b=

    where:
    BODYHASH - The body hash, base-64 encoded

    TOKEN - The domain you're using as the token

    SELECTOR - The selector associated with the key pair

    HEADERS - A list of the header names that were found in the subset above, e.g. “h=from:subject”. They must be in the same order here as they are in the header.

  7. Then the “empty” DKIM-Signature header is appended to the canonical headers, without a trailing CRLF. Then an SHA256 hash of the canonical headers, including the DKIM-signature, is taken as described here. This is the header hash.
  8. Finally, throw the canonical headers away as we don't need them anymore.

Generate the DKIM-Signature Header

  1. Sign the header hash using RSA, as described here, giving the signature
  2. Create a DKIM-Signature header:

    DKIM-Signature: v=1;a=rsa-sha256;bh=BODYHASH;c=relaxed;d=TOKEN;h=HEADERS;s=SELECTOR;b=SIGNATURE

    SIGNATURE - the RSA signature we just calculated, encoded in base-64

    BODYHASH, TOKEN, SELECTOR and HEADERS - described above

  3. Prepend the DKIM-Signature header to the original email message. Now your emails are DKIM signed!

Credits to DKIMCore.org for providing most of this information.