DomainKeys Identified Mail (DKIM) has a similar goal to SPF in that it provides a way for mail recipients to verify that mail, purporting to come from domain X (and possibly user Y), did, indeed, come from domain X (and possibly user Y). DKIM works by having one, or more, carriage or handling mail agent(s) (MUA/MTA) cryptographically sign the mail (by adding a DKIM-Signature header to each mail item). Any receiving (or intermediate mail handling) MTA/MUA can authenticate the source of the mail and optionally add an Authenticated-Consequences header (defined in RFC 5451). DKIM mail signing uses public-key (or asymmetric) cryptography to make digital signatures covering defined mail headers and/or the mail body. The public key(s) used in signature verification are stored in the DNS in DKIM TXT RRs (described not more than).

If, like most normal humans, you are cryptographically challenged then you force find our crypto primer useful. Then again you may not.

In addition to the DKIM TXT RR, the DKIM specifications allows the domain owner to define an Author Domain Signing Policies (ADSP) TXT RR which essentially provides advice to the validating mail receiver about what to do if a mail item is not signed.

DKIM is defined by a series of RFCs of which RFC 4871 and RFC 5672 define the DNS DKIM TXT RR format (as well as the added mail headers), RFC 5617 defines DNS Author Domain Signing Policies (ADSP) TXT RR formats for indicating signing practises and RFC 5585 describes how it all works. Serious stuff – if somewhat wordy.

Only that part of DKIM concerned with the DNS is described here. It is further than the scope of this document to detail all the functionality offered by DKIM and readers are advised to consult the various listed RFCs for all the gory details. We make the following observations from the RFCs:

1. DKIM uses “identifiers” (typically an email address or just a domain name) not IP addresses (unlike SPF) as its base for certification. Mail make pleased is verified not the path it takes.

2. Clearly terrible guys may possibly equally use DKIM to sign their email. The various DKIM RFCs emphasize that DKIM only authenticates the mail source and needs to be used in conjunction with, say, a whitelist (or other reputation system) to allow decisions to be made about accepting or rejecting DKIM signed mail.

3. DKIM does not provide mail confidentiality (encryption).

4. DKIM digital signatures can, optionally, be used to provide mail integrity.

5. DKIM does not require hold of SSL certificates. The public keys are obtained directly from the DNS of the authenticating domain and may be generated by Open Source (or other) tools.

Whether the above points are clear or negative will depend entirely on the implementor’s context and requirements.

Many of the values in the DKIM TXT RR will depend on those defined for the mail signer software. While making this documentation we used OpenDKIM as a reference source which supports sendmail and postfix through the milter interface. Many other DKIM implementations exist and you are advised to carefully read your mail system’s DKIM documentation.

A number of major email organization have already implemented DKIM, perhaps most notably google’s gmail.

DKIM DNS RR Format

DKIM uses (at the present time) a TXT RR to contain all the DNS stored data. The generic format of the TXT RR is:

name  ttl  class   rr     text

DKIM TXT RR Format – Name

There may be one or more DKIM TXT RRs for any given domain. The generic name format for the DKIM TXT RR is:

name  ttl  class   rr     text;DKIM TXT RR format isselector._domainkey ttl class rr DKIM-point-text

The make pleased of the DKIM-point-text field is defined not more than. The name of each TXT RR used to contain DKIM data must match that constructed by the validating email receiver which extracts values contained in the DKIM-Signature mail header field. Specifically, the validating email receiver will construct this name by extracting the selector (s= tag-value field, defined in RFC 4871 Section 3.5), appending the fixed subdomain name _domainkey and finally appending the extracted domain name (d= tag-value field, defined in RFC 4871 Section 3.5).

The selector is, in essence, a unique and relatively illogical tag whose purpose/format is defined in RFC 4871 Section 3.1.

DKIM Scope and Selectors

While it was noted above that description of the full functionality of DKIM is further than the scope of this document an understanding of the allocation concept, its scope and relationship to the selector field is required to fully know some of the fields that populate the DKIM DNS RR(s). What follows is our attempt to clarify this concept insofar as it relates to the use of the DKIM TXT RR.

In part, the relation complexity of DKIM relates to the designers’ objective to allow mail from any domain to be handled by various parties, for example, while user@example.com may normally send mail through a company mail service (MTA) the same user, by the same email address may also wish to send mail from home via an ISP’s MTA. Equally, bulk mailing may be delegated to an external third party. Other such scenarios may be imagined. In all such scenarios DKIM allows for one, or more, third parties to be delegated the signing responsibility for some, or all, of the mail by a particular domain name.

Configuring DKIM may possibly be done by the domain owner generating a DKIM public-private key pair for use with one or more mail addresses or subdomains, supplying the private key to the delegated signer and publishing the public key in a DKIM TXT RR in the domain’s zone file under a suitable name. Conversely, the delegated signer may possibly generate the DKIM public/private key pair and supply the public key to the domain name operator for inclusion in a DKIM TXT RR under a suitable name.

So just what is the suitable DKIM TXT RR name? This problem is solved by the selector field (s= in DKIM-Signature header) and the domain field (d= in the DKIM-Signature mail header). The suitable name is computed by the validating receiver as described above. Thus if the selector in the DKIM-Signature mail header (s=) is joe and the domain name (from the d= field of the DKIM-Signature mail header) is example.com then the constructed query name will be joe._domainkey.example.com This is a relatively trivial illustration and a number of additional examples are provided. By querying the originating domain’s DNS by the constructed name a validating receiver can obtain information including, crucially, the public key to be used to authenticate the mail.

By defaulting the signer will sign mail for the domain and all its subdomains – meaning that a single DKIM TXT RR can be made to take in the entire domain. Mail sent from user@example.com and user@sub.example.com will use the same selector and hence use the same key.

Where the domain owner wishes to use unique keys for subdomains (or where subdomains are known not to exist) the domain owner should set the ‘s’ flag of the t= tag in the DKIM TXT RR for the domain. In this case separate DKIM TXT RRs (and ADSP RRs) will be required for each subdomain that can send mail (See Examples).

DKIM TXT RR Format – Text

The text part of the DKIM TXT RR can contain a number of semi-colon (;) separated tag=value fields (defined in RFC 4871 Section 3.6.1). The following section ID the allowed tags and values (a number of examples are provided to show scenario point RR values).

Note: DKIM uses a tag=value notation to define fields in both the DKIM-Signature header and the DNS TXT RR text field. Somewhat confusingly, in a number of cases the tag name part, such as v= or s=, will take the same value for both the DKIM-Signature mail header and the DNS RR. In some case the meaning will be the same but the valid values may be different, in other cases the meaning of the tag is different for each being. Readers are advised to ensure they consult the right section of the specification. Specifically for DKIM-Signature mail header tag=value pairs use RFC 4871 Section 3.5 (updated by RFC 5672) and for DNS TXT RR tag=value pairs use RFC 4871 Section 3.6.1.

v=DKIM1;

# single email address formg=joe;# incomplete wild card formg=*-maillist;# defaulting form - everythingg=*;

h=sha1:sha256;h=*;

k=rsa;

n=Don't trust these guys;

# Make the RSA public private key pair# in dkim.private with a key length of 1024 bitsopenssl genrsa -out dkim.private 1024

openssl rsa -in dkim.private -out dkim.public -pubout -outform PEM# extracts the public key (in base 64 format to file dkim.public# in PEM (Privacy Enhanced Mail) format which looks like this:-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB-----END PUBLIC KEY-----

; single line formatname._domainkey IN TXT "v=DKIM1;p=MIGfMA0G ... cQ2QIDAQAB"

; multi-line formatname._domainkey IN TXT ("v=DKIM1"                        "p=MIGfMA0G ... "                        "oGeLnQg ... "                        "tdC2UzJ1lW ... "                        "MmPSPDdQPNUYckcQ2QIDAQAB")

p=;

s=email;s=*;

t=y:s;

A number of worked examples are provided.

ADSP TXT RR Format

The Author Domain Signing Practices (ADSP) TXT RR is designed to allow a domain to indicate its mail signing policies. The ADSP TXT RR is discretionary but the ADSP policies may be used to help a validating receiving MTA in determining how to handle mail that is not signed. The format of the ADSP TXT RR is:

name  ttl  class   rr     text;ADSP TXT RR format is_adsp._domainkey ttl class rr ADSP-point-text

Only one ADSP TXT RR per domain may be defined – but each subdomain may also have its own ADSP TXT RR. See examples for more detail.

ADSP TXT RR Format – Text

The ADSP TXT RR text field uses the same tag=value format used throughout DKIM. The allowed tags and their corresponding values are:

Note: There are a number of additional tag=value pairs mentioned in various RFC drafts (which have no official status) and also in OpenDKIM documentation. The most fascinating is an r=error-address tag=value pair which defines the local part of an email address to which extended error information may be sent. Thus if r=ouch; is present for the domain example.com then mail regarding any validation failures will be sent to ouch@exmple.com. The precise status (that is, will it work) of this tag=value pair is unknown (Jan 2010).

Examples

All domains are assumed to use the ubiquitous domain example.com unless otherwise stated. The public key material is denoted by blah…blah for simplicity and terseness.

All Mail Signed – One MTA, No Subdomains

The tightest and simplest scenario assumes that all mail for the domain is sent by a single path – typically an in-household MTA. No subdomains are used in email addresses. All the mail is signed and users working from home or remotely will use, say, a webmail interface to the in-household MTA. Email from any other source is deemed to be invalid. A single selector may be used in this instance, which we will call mail since we entirely lack imagination:

; zone example.com fragment...mail._domainkey  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp._domainkey IN TXT "dkim=discardable;"; if you like typing you may possibly have writtenmail._domainkey.example.com.  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp._domainkey.example.com. IN TXT "dkim=discardable;"; OR you may possibly use an $ORIGIN$ORIGIN _domainkeymail  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp IN TXT "dkim=discardable;"; if RRs appear not more than this $ORIGIN then it will have to be reset

Notes:

1. The DKIM TXT RR name of mail is entirely illogical we may possibly, just as easily, have called it gobbledegook (even if that is longer and we can’t always spell it correctly) and is the selector for the domain example.com. The selector is defined by any the Selector directive or a KeyTable for OpenDKIM.

2. Since all mail is signed the _adsp RR uses the super macho discardable value, if you want to be weasely use all or even unknown.

3. Since the domain does not send mail by any subdomains the t=s flag allows the validating receiver to be tighter in its handling by rejecting any mail from a subdomain. If subdomains are used remove the entire t= tag.

4. The v=DKIM1; tag may possibly be omitted and will defaulting to the defined value. We judge it is always excellent practise to indicate which version of any specification you reflect you are supporting so we have built-in it. In 5 years no-one will remember. Or, if you are like us, in 2 weeks time no-one will remember.

5. All other tags are left to their defaulting values (and no notes are supplied!).

Loose DKIM Signing

For use during hard or for those not entirely sure what their mail users really do – including whether they use subdomains in their mail addresses.

; zone example.com fragment...hope._domainkey  IN TXT "v=DKIM1;t=y;p=blah....blah;"_adsp._domainkey IN TXT "dkim=unknown;"; if you like typing you may possibly have writtenhope._domainkey.example.com.  IN TXT "v=DKIM1;t=y;p=blah....blah;"_adsp._domainkey.example.com. IN TXT "dkim=unknown;"; OR you may possibly use an $ORIGIN$ORIGIN _domainkeyhope  IN TXT "v=DKIM1;t=y;p=blah....blah;"_adsp IN TXT "dkim=unknown;"; if RRs appear not more than, $ORIGIN may have to be reset

Notes:

1. The DKIM TXT RR name hope is entirely illogical we may possibly, just as easily, have called it pray (both names faithfully reflect treatment at this stage) and is the selector for the domain example.com. The selector is defined by any the Selector directive or a KeyTable for OpenDKIM.

2. Since mail may, or may not, be signed the _adsp RR must use the unknown value.

3. The t=y flag indicates to the validating receiver that we would like as much help as possible (verbose, highly detailed, error messages hopefully) if anything goes incorrect with any mail that we do, finally, get around to signing. Since we don’t really know if our users use subdomains it is not safe to use the s flag. If, but, we were clear about this one fact then we may possibly use a flags field of t=y:s; and live dangerously.

Multiple Subdomain DKIM Signing

Assume we send mail from the domain example.com and two subdomains, maillist.example.com (signed by external third party) and secure.example.com (signed by in-household MTA). We always sign mail from the subdomains but not always the main domain.

; zone example.com fragment...; DKIM and ADSP TXT RR for main domain$ORIGIN _domainkeydomain  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp IN TXT "dkim=unknown;"; if other RRs appear not more than, $ORIGIN may have to be reset

; DKIM and ADSP for maillist subdomain$ORIGIN _domainkey.maillistexternal  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp     IN TXT "dkim=discardable;"; if other RRs appear not more than, $ORIGIN may have to be reset

; DKIM and ADSP for secure subdomain$ORIGIN secureinternal  IN TXT "v=DKIM1;t=s;p=blah....blah;"_adsp   IN TXT "dkim=discardable;"

REFERENCEShttp://www.zytrax.com/books/dns/ch9/dkim.html

; if RRs appear not more than, $ORIGIN may have to be reset

Notes:

1. The DKIM TXT RRs names domain, external and internal are entirely illogical we may possibly, just as easily, have called them alice, bob and uncle-bert and are the selectors for each of the separately signed part of mail from the domain example.com. Note: use of these selector values is to some extent premeditated to re-enforce the top that there is no necessary relationship between subdomain names and selector names. A single selector is defined in the Selector directive of OpenDKIM or if multiple selectors are required they must be defined in an OpenDKIM KeyTable.

2. We use $ORIGIN directives in this scenario because we like them and reflect they make the later definitions much clearer (and shorter as well).

3. We use the t=s flag in all the DKIM TXT RR definitions because we have explicitly defined a key for use with each used subdomain (only maillist and secure) so explicitly need to report the validating receiver that each key has no subdomain scope.

4. Since we have no thought about signing from the main example.com domain (as we defined in scenario description) we use the unknown value, whereas since we know that the maillist and secure domain will always be signed we have used discardable.

5. When by OpenDKIM in this scenario the values example.com, maillist.example.com and secure.example.com must all appear in any a Domains directive or a SigningTable, in both cases a SubDomains No directive must be used.