Domain Name Specification for DKIM2

2.1. 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.¶

2.2. 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.¶

2.3. 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 [RFC5598], 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.¶

2.4. Identifier

A label that refers to an identity.¶

2.5. 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¶

2.6. 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.¶

2.7. 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):¶

WSP = SP / HTAB
LWSP = *(WSP / CRLF WSP)
FWS = [*WSP CRLF] 1*WSP

The definition of FWS is identical to that in [RFC5322] except for the exclusion of obs-FWS.¶

2.8. 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 [RFC2045]:¶

• "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.¶

2.9. Common ABNF Tokens

The following ABNF tokens are used elsewhere in this document:¶

hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ]
ALPHADIGITPS = (ALPHA / DIGIT / "+" / "/")
base64string = ALPHADIGITPS *([FWS] ALPHADIGITPS)
[ [FWS] "=" [ [FWS] "=" ] ]

3.1. 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.¶

INFORMATIVE NOTE: A key may also be revoked as described below. The distinction between revoking and removing a key selector record is subtle. When phasing out keys as described above, a signing domain would probably simply remove the key record after the transition period. However, a signing domain could elect to revoke the key (but maintain the key record) for a further period. There is no defined semantic difference between a revoked key and a removed key.¶

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

INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key (for example, changing the key associated with a user’s name) makes it impossible to tell the difference between a message that didn’t verify because the key is no longer valid and a message that is actually forged. For this reason, Signers are ill-advised to reuse selectors for new keys. A better strategy is to assign new keys to new selectors.¶

3.2. 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 [RFC2045], 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.¶

INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined below (as "tag-value") only includes 7-bit characters, an implementation that wished to anticipate future standards would be advised not to preclude the use of UTF-8-encoded [RFC3629] text in tag=value lists.¶

Formally, the ABNF syntax rules are as follows:¶

tag-list = tag-spec *( ";" tag-spec ) [ ";" ]
tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
tag-name = ALPHA *ALNUMPUNC
tag-value = [ tval *( 1*(WSP / FWS) tval ) ]
; Prohibits WSP and FWS at beginning and end
tval = 1*VALCHAR
VALCHAR = %x21-3A / %x3C-7E
; EXCLAMATION to TILDE except SEMICOLON
ALNUMPUNC = ALPHA / DIGIT / "_"

Note that WSP is allowed anywhere around tags. In particular, any WSP after the "=" and any WSP before the terminating ";" is not part of the value; however, WSP inside the value is signicant.¶

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

3.3. 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 [RFC6376] while ed25519-sha256 is specified in [RFC8463]. Signers and Verifiers MUST implement rsa-sha256 and SHOULD implement ed25519-sha256. Futher they MUST NOT validate the legacy DKIM [RFC6376] 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.¶

3.4. 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).¶

public_key = dkim2_find_key(q_val, d_val, s_val)

This document defines a single binding, using DNS TXT RRs to distribute the keys. Other bindings may be defined in the future.¶

ABNF:
key-v-tag = %x76 [FWS] "=" [FWS] %x44.4B.49.4D.31

ABNF:
key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg
*( [FWS] ":" [FWS] key-h-tag-alg )
key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg
x-key-h-tag-alg = hyphenated-word ; for future extension

ABNF:
key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type
key-k-tag-type = "rsa" / x-key-k-tag-type
x-key-k-tag-type = hyphenated-word ; for future extension

ABNF:
key-n-tag = %x6e [FWS] "=" [FWS] qp-section

ABNF:
key-p-tag = %x70 [FWS] "=" [ [FWS] base64string]

ABNF:
key-s-tag = %x73 [FWS] "=" [FWS] key-s-tag-type
*( [FWS] ":" [FWS] key-s-tag-type )
key-s-tag-type = "email" / "*" / x-key-s-tag-type
x-key-s-tag-type = hyphenated-word ; for future extension

ABNF:
key-t-tag = %x74 [FWS] "=" [FWS] key-t-tag-flag
*( [FWS] ":" [FWS] key-t-tag-flag )
key-t-tag-flag = "y" / "s" / x-key-t-tag-flag
x-key-t-tag-flag = hyphenated-word ; for future extension