DKIM

DKIM (DomainKeys Identified Mail) is an email authentication protocol that allows an organization to take some responsibility for a message by inserting a specially-crafted header into the message. This header contains two cryptographic hashes, one of some of the headers of the message and the other of the message body (or a portion of it), along with enough information for the message receiver to validate the hashes. The hashes are calculated and validated using Public Key Infrastructure (PKI), and the act of inserting the header is called “DKIM Signing a message”, and the header is called the DKIM-Signature header.

GreenArrow Engine supports DKIM Signing outgoing messages.

A typical DKIM-Signature header will look like this:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=greenarrowemail.com; s=default2; t=1749494995; x=1750099795; 
        h=to:from:subject:date:message-id:sender:reply-to:mime-version:from
         :to:cc:subject:date:message-id:reply-to;
        bh=u5gzbBo13gcY2WKsVVb3PQtL2xCef2vW01FjTyMzeVc=;
        b=FF3/rrUqG1Y/utJ4zonxpJ8Zm2N62B8o/crV5RNhAcj5e7SOOZt43eCp+6HI0ZM7Wm
         9YcyleG4IBXhorbUKEJzf96dqkoWz54xI/hRl3a7W01htqv7UQJaJvKhzv0OWiPrmmra
         3lV7TNCVELPWLffQMBPhtO25xrMz3z3+kKQ/g=

While we won’t get further into the minutiae of a DKIM-Signature header, the above example may help in understanding the next paragraph.

PKI relies on a pair of keys, one private and one public, in order to function properly, and for DKIM, the public key is necessary for the recipient to validate the cryptographic hashes, and it is published in DNS at a location that is generically known as:

selector._domainkey.signingDomain

Above we mentioned that a DKIM-Signature header “contains … enough information for the message receiver to validate the hashes”, and that information is primarily found in the d= and s= fields of the header:

d=greenarrowemail.com; s=default2

Those two fields tell the message receiver the selector (s=) and signingDomain (d=) for the message, and so the receiver can find the public key for this message in a DNS TXT record published at default2._domainkey.greenarrowemail.com, like so:

$ host -tTXT default2._domainkey.greenarrowemail.com
default2._domainkey.greenarrowemail.com descriptive text "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCYV6GTvl+qQIFFnjuWbl2njjPeDz6f8+QqYEBtHKqoRl60E3TkhbsvMZzaLN4S3STKbzIRgn4cpVgcktxKPQ+FdfpTcu2JvhGCx/fGpiGfnwSSQehmGC3aDmraRq/jxCwKHXLxbIemxqGDt61NfPUMndouQb7fTM/Dc8HJvF6MIwIDAQAB"

Every DKIM key is uniquely identified by its domain name/selector combination. There can be multiple DKIM keys for the same domain name, as long as each of these keys has a unique selector. Similarly, there can be multiple DKIM keys using the same selector, as long as each of those keys is for a unique domain. The remainder of this section is GreenArrow-centric, but if you’d like to learn more about DKIM in general, the DKIM.org website provides a good overview of this technology, and the advantages of using it.

This page’s child pages contain details on how to configure DKIM within GreenArrow Engine:

GreenArrow Engine’s Default DKIM Signing Behavior

GreenArrow Engine’s default behavior when selecting which DKIM key to use for signing is to first check a message for a Sender header. If a Sender header is present, GreenArrow Engine will attempt to sign the message using the default signing key for the domain of the Sender header’s value. If a Sender header is not present, GreenArrow Engine will attempt to sign the message using the default signing key for the domain in the RFC5322.From header.

This default behavior can be changed by inserting an X-GreenArrow-DKIM Header into an individual email, or applying it as a setting within GreenArrow itself. See the X-GreenArrow-DKIM Header page for details.

The default selector name that’s used when you create a new DKIM key with GreenArrow Engine is literally, default, but you are free to choose any name instead, so long as it does not match another selector name for the domain in question.

Selecting a Cryptographic Hash

GreenArrow performs DKIM signing using the sha256 cryptographic hash by default but also supports sha1. You can specify which hash to use by updating the /var/hvmail/control/dkim/hashfunc configuration file. For example, to restore the default of sha256, run:

echo sha256 > /var/hvmail/control/dkim/hashfunc

We recommend using sha256, both because it’s cryptographically stronger and because RFC 8301 removed sha1 support from DKIM.