HOWTO define DKIM/ADSP RRs

DomainKeys Identified Mail (DKIM) allows a receiving mail handler to authenticate one or more entities that have signed the mail item. The SPF (Sender Policy Framework) RR offers either an alternative or complimentary approach to DKIM by defining one or more IP addresses from which mail from any domain may be sent. DKIM is significantly more complex than SPF but also provides significantly more functionality. Finally, the DMARC RR provides a method by which a domain can advise the mail receiver whether mail originating from a domain will have DKIM, SPF or both, what to do with mail that fails either DKIM or SPF checks and whether it wishes failure reports from the mail receiving MTA. DMARC essentially extends and replaces the ADSP feature of DKIM.

In DKIM, any sending or handling mail agent - either an MTA (Mail Transfer Agent) or a MUA (Mail User Agent) - can cryptographically sign mail by adding a DKIM-Signature mail header to the mail item. The DKIM-Signature mail header contains a number of fields of which the most important are:

Signer: identifies the mail signing source - either the originator of the mail or a delegated third party acting on their behalf.
Coverage: describes what parts of the mail item are covered--such as nominated mail headers, the mail body or specific parts of the mail body.
Scope: defines the mail signers scope, for example, a single email address, mail for the whole domain, or some subset of the domain.

The DKIM-Signature mail header is protected and authorized by the mail signers digital signature. Any DKIM compliant receiving (or intermediate) mail handler will read a DKIM-Signature header (there may be more than one), extract the fields describing the signing source and construct a domain name. A DNS query is used to read the DKIM TXT RR, containing, among other fields, a public key at the constructed domain name. The public key obtained is then used to validate both the integrity of the DKIM-Signature and authenticate the mail signer. The mail handler, if an intermediate (or relay), can simply pass the message on, add another DKIM-Signature header and/or add an Authenticated-Results header (defined in RFC 5451). In the case of a final delivery mail handler the mail can be accepted or even rejected based on the trustworthiness of the mail signer.

If, like most normal humans, you are cryptographically challenged then you might 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. ADSP functionality is extended and enhanced by the DMARC RR which essentially supersedes it.

DKIM is defined by a series of RFCs of which RFC 6376 defines 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 beyond 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. The following observations are made from the many, wordy and worthy RFCs:

DKIM authenticates the signer of the mail item and does not use any IP addresses (unlike SPF) as its base for validation. Mail content is verified not the path it takes.
Clearly bad guys could equally use DKIM to sign email. The various DKIM RFCs emphasize that DKIM only authenticates the mail signer and needs to be used in conjunction with, say, a whitelist or other reputation system, for example, Vouch By Reference (RFC 5518), to allow decisions to be made about accepting or rejecting DKIM signed mail.
DKIM does not provide mail confidentiality (encryption).
DKIM digital signatures can, if the signature covers the mail body, be used to provide mail integrity - verifying that the mail item received is exactly the same as that sent.
DKIM does not require purchase of SSL certificates. The public keys are obtained directly from the DNS of the authenticating domain and may be generated using OpenSSL (or other) tools.

Whether the above points are positive 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 creating this documentation we used OpenDKIM as a reference source which supports (currently) 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 a TXT RR to contain DNS data. The generic format of the TXT and DKIM TXT RR is:

; Generic TXT RR format
name  ttl  class   TXT     "text"
;DKIM TXT RR format
selector._domainkey ttl class TXT "DKIM-specific-text"

The content of the DKIM-specific-text field is defined in detail below but its principal role is to supply the public key to be used to authenticate arriving mail for the domain. The validating email receiver constructs the name of a DKIM TXT RR by extracting values contained in the DKIM-Signature mail header field (present in all DKIM signed mail). Specifically, the validating email receiver will construct this name by extracting the selector (s= tag-value field, defined in RFC 4871 Section 3.1 and 3.5, essentially a unique, but arbitary, value), appending the fixed subdomain name _domainkey and finally appending the extracted domain-name (d= tag-value field, defined in RFC 4871 Section 3.5). Thus, if the selector field contains the value all-mail and the domain-name field is example.net then a DNS TXT query is issued for all-mail._domainkey.example.net.

In part, the relative complexity of DKIM relates to the designers' objective to allow mail from a domain to be handled, and possibly signed, by various parties. For example, while user@example.com may normally send mail through a company mail service (MTA) the same user, using 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 scenarios may be imagined. DKIM's architecture thus allows for the domain owner or one, or more, trusted third parties to sign some, or all, of the mail from a given domain name. Trusted third parties may thus be said to be delegated signing responsibility for a domain's email.

To illustrate this process, assume that mail with an address of user@example.com when originated from the office is sent from, and signed by, the example.com MTA which maintains a single private/public key pair for this purpose. The example.com domain publishes the public key in its DNS in a DKIM TXT RR under the name onlyone._domainkey.example.com. The DKIM-Signature mail header from mail originating from the example.com MTA will therefore contain (among others) an s=onlyone (selector) field and a d=example.com (domain-name) field from which the receiving or validating mail server can construct the DKIM TXT RR name as defined above and authenticate the email.

Now assume further that user@example.com will also send mail from home via an ISP's MTA whose domain name is example.net and which publishes its DKIM public key under the name publicmail._domainkey.example.net. In this case the DKIM-Signature mail header covering mail sent from the mail address, say, user@example.com (and perhaps all other mail originating from this MTA) will contain an s=publicmail (selector) field and a d=example.net (domain-name) field from which, again, the receiving or validating mail server can construct the DKIM TXT RR name as defined above and authenticate the email. By default the signer will sign mail for the domain and all its subdomains - meaning that a single DKIM TXT RR can be created to cover the entire domain. Mail sent from user@example.com and user@sub.example.com can 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 documents the allowed tags and values (a number of examples are provided to show scenario specific 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 entity. Readers are advised to ensure they consult the correct 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= (version)

Optional. Defines the DKIM version number and may only (at this time) take the (defaulted) value DKIM1. While it may be safely omitted our advice is to include it.

v=DKIM1;

g= (granularity)

Optional. Granularity defines the user (local) part of the email (everything to the left hand side of the @) to which this DKIM TXT RR applies. A single wild card (*) value may be used anywhere in the field. Defaults to g=*(all user - local - part addresses match). This value (after any wild card processing) must exactly match the mail From: user (local) part. However, assuming you are not doing anything too fancy (good luck if you are) it may be safely omitted.

# single email address form
g=joe;
# partial wild card form 
g=*-maillist;
# default form - everything
g=*;

h= (hash algorithm)

Optional. Defines one or more colon (:) separated hash (digest) algorithms that will be used for the purpose of creating digital signatures (in conjunction with k= below) covering either or both of the defined mail headers or the mail body (including, optionally, MIME attachments). Allowable values are from the set sha1 and sha256. Default is h=* (all). Since all implementations of DKIM are mandated to support both sha1 and sha256 hash (digest) algorithms it may be safely omitted.

h=sha1:sha256;
h=*;

k= (key type)

Optional. Defines the public key algorithm being used. Defaults to k=rsa. Since rsa is the only algorithm currently supported it may be safely omitted.

k=rsa;

n= (notes)

Optional. Defines human readable text that may be used by validating receiver administrators. Unless this imparts significant, perhaps world-stopping, knowledge - such as a contact phone number or email address - it may be safely omitted.

n=We are really, really trustworthy (snigger, snigger);

p= (public key material)

Defines the public key (in base64 text format) for the algorithm defined by the k= tag whose private key was used to digitally sign user defined parts of the mail item. The data for the public key may be created by openssl using the following command sequence (taken from RFC 6376 Appendix C and reproduced here only for convenience):

# Create the RSA public private key pair
# in dkim.private with a key length of 1024 bits
openssl 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/DkM
oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R
tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI
MmPSPDdQPNUYckcQ2QIDAQAB
-----END PUBLIC KEY-----

Remove the lines beginning with "-" and edit the remaining text in any of the following formats (most key material replaced with ' ... ' for brevity):

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

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

See TXT RR for additional information on layout and formatting of text.

If a key is to be revoked (declared invalid) then setting the p= tag to a null value will achieve this:

p=;

s= (service type)

Optional. Defines the service type to which DKIM is applied. At this time the only valid value is email but clearly the designers had their sights set on greater goals. The default is s=* (all). Since email is, currently, the only DKIM supported service it may be safely omitted.

s=email;
s=*;

t= (flags)

Optional. Defaults to no flags set. A colon (:) separated list of flags to be used by the validator. Two flags are currently defined:

y	Indicates test mode. If set it may (hopefully does) generate additional diagnostic messages from the validating receiver, but still permits the validator to treat the mail normally, that is, a validation failure must still be treated as a failure - no validation leniency is implied by setting this flag.
s	If defined this flag indicates that this key is not valid for subdomains of the domain name (defined in the d= tag of the DKIM-Signature). To inhibit subdomain signing behavior in OpenDKIM you must set SubDomains No.

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 optional but the ADSP policies may be used to assist 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-specific-text

Note: ADSP is extended and enhanced by the DMARC RR and may thus be regarded as essentially deprecated - though this is not formally documented and represents (at this time) only the author's opinion.

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

Note: While trusted third parties may sign some, or all, of a domain's mail (and therefore the DKIM TXT RR containing the public key will appear in the signers domain zone file) an ADSP TXT RR, if present, can only appear in the domain owner's zone file.

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:

Tag

Values

dkim=

A single value from the following set of permissible values is allowed:

unknown	The domain, as it appears in the email address, does not sign all mail. This is the most common setting during testing, but if used in a production environment will essentially nullify the use of DKIM. Having a domain which, in a production environment, only signs some of its mail is probably not terribly useful.
all	The domain, as it appears in the email address, signs all mail. This setting leaves the validating receiver free to carry out its own policies if it receives unsigned mail.
discardable	The domain, as it appears in the email address, signs all mail. This is the macho setting because it also advises the validating receiver that unsigned mail should be discarded. The sleepless-nights-for-mail-administrators setting.

dkim=discardable;

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 interesting 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).
While trusted third parties may sign some, or all, of a domain's mail (and therefore the DKIM TXT RR containing the public key will appear in the signers domain zone file) an ADSP TXT RR, if present, can only appear in the mail originator's zone file. Thus, if mail with the name user@example.com is signed by example.net then the DKIM TXT RR, containing the signer's public key, will appear in the example.net zone, but any DKIM ADSP TXT RR, containing the sender's signing policy, can only appear in the example.com zone.

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 brevity.

All Mail Signed - One MTA, No Subdomains

The tightest and simplest scenario assumes that all mail for the domain is sent using a single path - typically an in-house 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-house MTA. Email from any other source is deemed to be invalid. A single selector will be used in this instance, called mail whose choice, as is true for any selector, is arbitrary but unique. In this case its value, while perfectly valid, may indicate a singular lack of imagination:

; zone example.com fragment
...
; DKIM TXT RR
mail._domainkey  IN TXT "v=DKIM1;t=s;p=blah....blah;"
; ADSP TXT RR
_adsp._domainkey IN TXT "dkim=discardable;"
; if you like typing you could have written
mail._domainkey.example.com.  IN TXT "v=DKIM1;t=s;p=blah....blah;"
_adsp._domainkey.example.com. IN TXT "dkim=discardable;"
; OR you could use an $ORIGIN
$ORIGIN _domainkey
mail  IN TXT "v=DKIM1;t=s;p=blah....blah;"
_adsp IN TXT "dkim=discardable;"
; if RRs appear below this $ORIGIN then it will have to be reset

Notes:

The DKIM TXT RR name of mail is entirely arbitrary we could, just as easily, have called it gobbledegook (though that is longer and we can't always spell it correctly) and is the selector for the domain example.com. The selector is defined using either the Selector directive or a KeyTable for OpenDKIM.
Since all mail is signed the ADSP TXT RR uses the super macho discardable value, if you want to be more weasely use all.
Since the domain does not send mail using 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.
The v=DKIM1; tag could be omitted and will default to the defined value. It is always good practice to indicate which version of any specification you think you are supporting. In 5 years no-one will remember. Or, if you are like us, in 2 weeks time no-one will remember.
All other tags are left to their default values (and no notes (n=) are supplied!).

Loose DKIM Signing

For use during testing or for those not entirely sure what their mail users actually do - including whether, or not, they use subdomains in their mail addresses.

; zone example.com fragment
...
; DKIM TXT RR
hope._domainkey  IN TXT "v=DKIM1;t=y;p=blah....blah;"
; ADSP TXT RR
_adsp._domainkey IN TXT "dkim=unknown;"
; if you like typing you could have written
hope._domainkey.example.com.  IN TXT "v=DKIM1;t=y;p=blah....blah;"
_adsp._domainkey.example.com. IN TXT "dkim=unknown;"
; OR you could use an $ORIGIN
$ORIGIN _domainkey
hope  IN TXT "v=DKIM1;t=y;p=blah....blah;"
_adsp IN TXT "dkim=unknown;"
; if RRs appear below, $ORIGIN may have to be reset

Notes:

The DKIM TXT RR name hope is entirely arbitrary we could, just as easily, have called it pray (both names faithfully reflect usage at this stage) and is the selector for the domain example.com. The selector is defined using either the Selector directive or a KeyTable for OpenDKIM.
Since mail may, or may not, be signed the ADSP TXT RR must use the unknown value.
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 wrong with any mail that we do, finally, get around to signing. Since we don't actually know if our users use subdomains it is not safe to use the s flag. If, however, we were positive about this one fact then we could use a flags field of t=y:s; and live dangerously.

Multiple Subdomain DKIM Signing

Assume the domain example.com sends mail from the domain with a format of, for illustration, user@example.com and two subdomains, secure.example.com with a format of user@secure.example.com and maillist.example.com with a format of, for instance, newsletter@maillist.example.com. Mail from example.com and secure.example.com is signed by the in-house MTA but mail from the subdomain maillist.example.com is delegated to, and signed by, the domain example.net. We always sign mail from the subdomains but not always the main domain.

; zone example.com fragment
$ORIGIN example.com.
...
; DKIM and ADSP TXT RR for main domain
; DKIM TXT RR
domain._domainkey  IN TXT "v=DKIM1;t=s;p=blah....blah;"
; ADSP TXT RR
_adsp._domainkey IN TXT "dkim=unknown;"

; DKIM and ADSP for secure subdomain
; DKIM TXT RR
internal._domainkey.secure  IN TXT "v=DKIM1;t=s;p=blah....blah;"
; ADSP TXT RR
_adsp._domainkey.secure   IN TXT "dkim=discardable;"
; OR, using an $ORIGIN
$ORIGIN _domainkey.secure
internal  IN TXT "v=DKIM1;t=s;p=blah....blah;"
_adsp   IN TXT "dkim=discardable;"
; if RRs appear below, $ORIGIN may have to be set to a new value

; ADSP for maillist subdomain
; ADSP TXT RR
_adsp._domainkey.maillist   IN TXT "dkim=discardable;"
; OR, using an $ORIGIN
$ORIGIN _domainkey.maillist
_adsp     IN TXT "dkim=discardable;"
; if other RRs appear below, $ORIGIN may have to be set to a new value

Notes:

We use $ORIGIN directives in this scenario because we like them and think they make the subsequent definitions much clearer (and shorter as well). Entirely a matter of taste. The above shows the DKIM TXT RR definitions for the subdomains secure and maillist within the example.com zone using a virtual (or pseudo) subdomain structure. Alternatively, if the domains are fully delegated the definitions would appear within the delegated subdomains' zone file.
The DKIM TXT RR for the domain example.com and the subdomain secure.example.com both use the s flag (t=s;) since each RR has its own scope. Thus, the DKIM-Signature mail header for mail with addresses of the form user@secure.example.com will have a selector field of s=secure and domain-name field d=secure.example.com, whereas mail with addresses of the form user@example.com will have a selector field of s=domain and a domain-name field d=example.com.
The DKIM TXT RRs names domain and external are entirely arbitrary we could, just as easily, have called them alice and uncle-bert and are the selectors for each of the separately signed part of mail from the domain example.com. 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. Note: use of these selector values re-enforces the point that there is no necessary relationship between subdomain names and selector names. However, (and you may want to take a deep breath before continuing) it is also possible that both the main domain and the subdomain secure could both use the same, say, domain._domainkey.example.com DKIM TXT RR. In this case mail addresses of the form user@example.com and user@secure.example.com would both have a selector of s=domain and a domain-name of d=example.com in the DKIM-Signature mail header (and would require a t=s; flag as well). This is a legitimate, if somewhat confusing, construct. As long as the s= and d= fields of the DKIM-Signature allow the receiver to generate and obtain a public key which will validate the mail header everything works.
Since we have no idea 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. Wimps could use all.
The subdomain maillist does not have a DKIM TXT RR in the zone example.com. This is because mail for this subdomain is signed by a external third party (assumed to be example.net as defined in the scenario description). DKIM-Signature mail headers will be authenticated by the public key published in a DKIM TXT RR in the DNS of the signing domain. Thus, if the external signing third party has a domain name of example.net and uses an arbitrary selector value for example.com's mail, say, of example-com-maillist then the DKIM-Signature mail headers will contain a selector field s=example-com-maillist and a domain-name field d=example.net and will publish a DKIM TXT RR in its zone file at the name example-com-maillist_domainkey.example.net even though the mail being signed may have addresses, such as, newsletter@maillist.example.com. The ADSP TXT RR is always defined in the zone file of the mail originator, in this case maillist.example.com and therefore the validating mail receiver can construst a DNS address of _adsp._domainkey.maillist.example.com.
When using OpenDKIM in this scenario the values example.com, maillist.example.com and secure.example.com must all appear in either a Domains directive or a SigningTable, in both cases a SubDomains No directive must be used.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.