Domain Name Specification for DKIM2

Introduction The updated DomainKeys Identified Mail (DKIM2) permits an organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message through a digital signature. This is done by publishing to Domain Name Service (DNS) of the domain a public key that is then associated to the domain and where messages can be signed by the corresponding private key. Assertion of responsibility is validated through a cryptographic signature and by querying the Signer’s domain directly to retrieve the appropriate public key. This document describes DKIM2 DNS record format and how to find the record. The updated DomainKeys Identified Mail (DKIM2) adopts a subset of the DKIM DNS specification, but to prevent ambiguity from using the using normative references to RFC6376, this document copies over the RFC6376 and updates as necessary. However, this document still does normatively reference RFC6376 for the IANA registrations. This document and the other DKIM2 documents do not deprecate RFC6376 as it is expected that both DKIM and DKIM2 will co-exist for at least some period of time. There are other updated DomainKeys Identified Mail (DKIM2) documents as well: the first document describes the motivation; the second document describes the headers.

Terminology and Definitions This section defines terms used in the rest of the document. DKIM2 is designed to operate within the Internet Mail service, as defined in . Basic email terminology is taken from that specification. Syntax descriptions use Augmented BNF (ABNF) [RFC5234]. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . These words take their normative meanings only when they are presented in ALL UPPERCASE.

Signers Elements in the mail system that sign messages on behalf of a domain are referred to as Signers. These may be MUAs (Mail User Agents), MSAs (Mail Submission Agents), MTAs (Mail Transfer Agents), or other agents such as mailing list exploders. In general, any Signer will be involved in the injection of a message into the message system in some way. The key issue is that a message must be signed before it leaves the administrative domain of the Signer.

Verifiers Elements in the mail system that verify signatures are referred to as Verifiers. These may be MTAs, Mail Delivery Agents (MDAs), or MUAs. In most cases, it is expected that Verifiers will be close to an end user (reader) of the message or some consuming agent such as a mailing list exploder.

Identity This specification DKIM2 calls for the Identity to correspond to an organization while DKIM permitted person, or role as well. In the context of email architecture specification , this corresponds to an ADministrative Management Domain (ADMD). Some examples include the the author’s organization, an ISP along the handling path, an independent trust assessment service, and a mailing list operator.

Identifier A label that refers to an identity.

Signing Domain Identifier (SDID) A single domain name that is the mandatory payload output of DKIM and that refers to the identity claiming some responsibility

Identity Assessor An element in the mail system that consumes DKIM2’s payload, which is the responsible Signing Domain Identifier (SDID). The Identity Assessor is dedicated to the assessment of the delivered identifier. Other DKIM2 (and non-DKIM2) values can also be used by the Identity Assessor (if they are available) to provide a more general message evaluation filtering engine. However, this additional activity is outside the scope of this specification.

Whitespace There are three forms of whitespace:

WSP represents simple whitespace, i.e., a space or a tab character (formal definition in [RFC5234])
LWSP is linear whitespace, defined as WSP plus CRLF (formal definition in [RFC5234]).
FWS is folding whitespace. It allows multiple lines separated by CRLF followed by at least one whitespace, to be joined.

The formal ABNF for these are (WSP and LWSP are given for information only): The definition of FWS is identical to that in except for the exclusion of obs-FWS.

Imported ABNF Tokens The following tokens are imported from other RFCs as noted. Those RFCs should be connsidered definitive. The following tokens are imported from :

"qp-section" (a single line of quoted-printable-encoded text)

Tokens not defined herein are imported from [RFC5234]. These are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF, etc.

Common ABNF Tokens The following ABNF tokens are used elsewhere in this document:

Protocol Elements Protocol Elements are conceptual parts of the protocol that are not specific to either Signers or Verifiers. The protocol descriptions for Signers and Verifiers are described in later sections ("Signer Actions" (Section 5) and "Verifier Actions" (Section 6)). NOTE: This section must be read in the context of those sections.

Selectors To support multiple concurrent public keys per signing domain, the key namespace is subdivided using "selectors". For example, selectors might indicate the names of office locations (e.g., "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date (e.g., "january2005", "february2005", etc.), or even an individual user. Selectors are needed to support some important use cases. For example:

Domains that want to delegate signing capability for a specific address for a given duration to a partner, such as an advertising provider or other outsourced function.
Domains that want to allow frequent travelers to send messages locally without the need to connect with a particular MSA.
"Affinity" domains (e.g., college alumni associations) that provide forwarding of incoming mail, but that do not operate a mail submission agent for outgoing mail.

Periods are allowed in selectors and are component separators. When keys are retrieved from the DNS, periods in selectors define DNS label boundaries in a manner similar to the conventional use in domain names. Selector components might be used to combine dates with locations, for example, "march2005.reykjavik". In a DNS implementation, this can be used to allow delegation of a portion of he selector namespace. ABNF: selector = sub-domain *( "." sub-domain ) The number of public keys and corresponding selectors for each domain is determined by the domain owner. Many domain owners will be satisfied with just one selector, whereas administratively distributed organizations can choose to manage disparate selectors and key pairs in different regions or on different email servers. Beyond administrative convenience, selectors make it possible to seamlessly replace public keys on a routine basis. If a domain wishes to change from using a public key associated with selector "january2005" to a public key associated with selector "february2005", it merely makes sure that both public keys are advertised in the public-key repository concurrently for the transition period during which email may be in transit prior to verification. At the start of the transition period, the outbound email servers are configured to sign with the "february2005" private key. At the end of the transition period, the "january2005" public key is removed from the public-key repository. While some domains may wish to make selector values well-known, others will want to take care not to allocate selector names in a way that allows harvesting of data by outside parties.

Tag=Value Lists DKIM2 uses a simple "tag=value" syntax in several contexts, including in messages and domain signature records. Values are a series of strings containing either plain text, "base64" text (as defined in , Section 6.8), or "qp-section" (ibid, Section 6.7). The name of the tag will determine the encoding of each value. Unencoded semicolon (";") characters MUST NOT occur in the tag value, since that separates tag-specs. Formally, the ABNF syntax rules are as follows: MUST be interpreted in a case-sensitive manner. Values MUST be processed as case sensitive unless the specific tag description of semantics specifies case insensitivity. Tags with duplicate names MUST NOT occur within a single tag-list; if a tag name does occur more than once, the entire tag-list is invalid. Whitespace within a value MUST be retained unless explicitly excluded by the specific tag description. Tag=value pairs that represent the default value MAY be included to aid legibility. Unrecognized tags MUST be ignored. Tags that have an empty value are not the same as omitted tags. An omitted tag is treated as having the default value; a tag with an empty value explicitly designates the empty string as the value.

Signing and Verification Algorithms DKIM2 supports multiple digital signature algorithms. Two algorithms are referenced by this specification at this time: rsa-sha256 and ed25519-sha256. rsa-sha256 is specified in while ed25519-sha256 is specified in . Signers and Verifiers MUST implement rsa-sha256 and SHOULD implement ed25519-sha256. Futher they MUST NOT validate the legacy DKIM rsa-sha1 algorithm i.e. ignore the public key and signatures associated with it. INFORMATIVE NOTE: rsa-sha256 enjoys virtually universal deployment while ed25519-sha256 has very little deployment at the creation of this draft. It does provide better capability in reduced key size, and faster signing and verification speed. Support for at least two algorithms provides algorithmic diversity that provides defense against some unforeseen future algorithm breakage. Thus implementation of ed25519-sha256 will be changed to MUST upon the completion of the DKIM2 specification. rsa-sha1 algorithm is deprecated for DKIM2 as sha1 is demonstrateably broken.

Key Management and Representation Signature applications require some level of assurance that the verification public key is associated with the claimed Signer. Many applications achieve this by using public-key certificates issued by a trusted third party. However, DKIM2 can achieve a sufficient level of security, with significantly enhanced scalability, by simply having the Verifier query the purported Signer’s DNS entry (or some security-equivalent) in order to retrieve the public key. DKIM2 keys can potentially be stored in multiple types of key servers and in multiple formats. The storage and format of keys are irrelevant to the remainder of the DKIM2 algorithm. Parameters to the key lookup algorithm are the type of the lookup (the "q=" tag), the domain of the Signer (the "d=" tag of the DKIM2 signature header field), and the selector (the "s=" tag). This document defines a single binding, using DNS TXT RRs to distribute the keys. Other bindings may be defined in the future.

Textual Representation It is expected that many key servers will choose to present the keys in an otherwise unstructured text format (for example, an XML form would not be considered to be unstructured text for this purpose). The following definition MUST be used for any DKIM2 key represented in an otherwise unstructured textual form. The overall syntax is a tag-list as described in Section . The current valid tags are described below. Other tags MAY be present and MUST be ignored by any implementation that does not understand them.

DNS Binding A binding using DNS TXT RRs as a key service is hereby defined. All implementations MUST support this binding.

Namespace All DKIM2 keys are stored in a subdomain named "_domainkey". Given a DKIM2 signature header field with a "d=" tag of "example.com" and an "s=" tag of "foo.bar", the DNS query will be for "foo.bar._domainkey.example.com".

Resource Record Types for Key Storage The DNS Resource Record type used is specified by an option to the query-type ("q=") tag. The only option defined in this base specification is "txt", indicating the use of a TXT RR. A later extension of this standard may define another RR type. Strings in a TXT RR MUST be concatenated together before use with no intervening whitespace. TXT RRs MUST be unique for a particular selector name; that is, if there are multiple records in an RRset, the results are undefined. TXT RRs are encoded as described in Section {textualrepresentation}.

IANA Considerations This document reuses the IANA registrations in in Section 7.

Security Considerations This document recommends thorough review and adherence to the Security Consideration in in Section 8.