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.