]> Google

weihaw@google.com

dkim Internet-Draft 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.

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 normative references to , this document copies over the relevant text from and updates it as necessary. However, this document still normatively references for the IANA registrations. This document and the other DKIM2 documents do not deprecate as it is expected that both DKIM and DKIM2 will co-exist for at least some period of time. INFORMATIVE NOTE FOR DKIM2: another reason for separating the DKIM2 DNS specification from DKIM, is that in the future, it is likely that DKIM2 will diverge from the parent specification. There are other updated DomainKeys Identified Mail (DKIM2) documents as well: describes the protocol and header fields, describes the Best Current Practice (BCP) for DKIM2.

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) . 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 In DKIM2, the Identity corresponds to an organization, whereas DKIM permitted a person or role as well. In the context of the email architecture specification , this corresponds to an ADministrative Management Domain (ADMD). Some examples include 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 DKIM2 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 ).
• LWSP is linear whitespace, defined as WSP plus CRLF (formal definition in ).
• FWS is folding whitespace. It allows multiple lines separated by CRLF followed by at least one whitespace, to be joined. The definition of FWS is identical to that in except for the exclusion of obs-FWS.

The formal ABNF for these is (WSP and LWSP are given for information only):

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

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

The following tokens are imported from :

• "sub-domain" (a single domain label)

Tokens not defined herein are imported from . 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 . NOTE: This section must be read in the context of those elements.

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 the selector namespace. ABNF: 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.

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. 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 text in tag=value lists. Formally, the ABNF syntax rules are as follows: 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 significant. Tags 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. Three algorithms are referenced by this specification at this time: rsa-sha256, ed25519-sha256 and mldsa44-ed25519-sha512. rsa-sha256 is specified in while ed25519-sha256 is specified in .
mldsa44-ed25519-sha512 is specified in .
Signers and Verifiers MUST implement rsa-sha256 and SHOULD implement ed25519-sha256 and mldsa44-ed25519-sha512. Further they MUST NOT validate the legacy DKIM rsa-sha1 algorithm i.e. ignore the public key and signatures associated with it. The following describes the mapping of key type "k=" values found in to the digital signature algorithms given in : Mapping of key type to digital signature algorithm

key type value	digital signature algorithms
rsa	rsa-sha256
ed25519	ed25519-sha256
mldsa44-ed25519-sha512	mldsa44-ed25519-sha512

INFORMATIVE RATIONALE FOR DKIM2: 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. ML-DSA in mldsa44-ed25519-sha512 is a Post-Quantum Cryptography (PQC) algorithm that provides protection against a Cryptographically Relevant Quantum Computer (CRQC) that would otherwise make RSA and ECDSA algorithms vulnerable. mldsa44-ed25519-sha512 is a composite construction to provide backstop protection for ML-DSA in case it has a latent undiscovered vulnerability. Support for at least three algorithms provides algorithmic diversity that provides defense against some unforeseen future algorithm breakage. Thus implementation of ed25519-sha256 and mldsa44-ed25519-sha512 will be changed to MUST upon the completion of the DKIM2 specification. The rsa-sha1 algorithm is deprecated for DKIM2 as SHA-1 is demonstrably 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 (defaulting to DNS TXT in DKIM2), the domain of the Signer (the "d=" tag of the DKIM2-Signature header field), and the selector (from the "s=" tag of the DKIM2-Signature header field). 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 . The current valid tags are described below. Other tags MAY be present and MUST be ignored by any implementation that does not understand them. Several tags are retired from DKIM2, though remain documented for compatibility with DKIM1. Conforming DKIM2 implementations SHOULD ignore retired tags.

v=

Version of the DKIM key record (plain-text; RECOMMENDED, default is "DKIM1"). If specified, this tag MUST be set to "DKIM1" (without the quotes). This tag MUST be the first tag in the record. Records beginning with a "v=" tag with any other value MUST be discarded. Note that Verifiers must do a string comparison on this value; for example, "DKIM1" is not the same as "DKIM1.0".

NOTE FOR DKIM2: DKIM2 reuses a subset of the DKIM textual representation including this version number for compatibility with existing key deployment. Consequently DKIM2 does not increment the version number. ABNF:

h=

Acceptable hash algorithms (plain-text). This is retired from DKIM2 and SHOULD be ignored.

ABNF:

k=

Key type (plain-text; OPTIONAL, default is "rsa"). Signers and Verifiers MUST support the "rsa" key type. The "rsa" key type indicates that an ASN.1 DER-encoded RSAPublicKey (see , Sections 3.1 and A.1.1) or SubjectPublicKeyInfo-RSAPublicKey (see and ) is being used in the "p=" tag. (Note: discusses the RSA public key format in more detail.) The "p=" value encodes the rsa public key using the base64 algorithm. In addition Signers and Verifiers SHOULD support the "ed25519" key type (See ) and "mldsa44-ed25519-sha512" key type (See ). The "p=" value encodes the Ed25519 public key or the mldsa44-ed25519-sha512 public key composite in base64.

ABNF:

n=

Notes that might be of interest to a human. This is retired from DKIM2 and SHOULD be ignored.

ABNF:

p=

Public-key data (base64; REQUIRED). An empty value means that this public key has been revoked. The syntax and semantics of this tag value before being encoded in base64 are defined by the "k=" tag.

INFORMATIVE RATIONALE: If a private key has been compromised or otherwise disabled (e.g., an outsourcing contract has been terminated), a Signer might want to explicitly state that it knows about the selector, but all messages using that selector are invalid. ABNF: INFORMATIVE NOTE: A base64string is permitted to include whitespace (FWS) at arbitrary places; however, any CRLFs must be followed by at least one WSP character. Implementers and administrators are cautioned to ensure that selector TXT RRs conform to this specification.

s=

Service Type (plain-text). This is retired from DKIM2 and SHOULD be ignored.

ABNF:

t=

Flags, are retired from DKIM2 and SHOULD be ignored, but documented here for completeness. They are represented as a colon-separated list of names (plain- text; OPTIONAL, default is no flags set). Unrecognized flags MUST be ignored. The defined flags are as follows:

y

This domain is testing DKIM. Verifiers MUST NOT treat messages from Signers in testing mode differently from unsigned email, even should the signature fail to verify. Verifiers MAY wish to track testing mode results to assist the Signer.

s

Any DKIM signature header fields using the "i=" tag MUST have the same domain value on the right-hand side of the "@" in the "i=" tag and the value of the "d=" tag. That is, the "i=" domain MUST NOT be a subdomain of "d=". Use of this flag is RECOMMENDED unless subdomaining is required.

ABNF:

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 a selector of "foo.bar" (in the "s=" tag), 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 .

IANA Considerations This document reuses the IANA registrations in

Security Considerations This document recommends thorough review and adherence to the Security Considerations in

References Normative References This RFC is the revised basic definition of The Domain Name System. It obsoletes RFC-882. This memo describes the domain style names and their used for host address look up and electronic mail forwarding. It discusses the clients and servers in the domain name system and the protocol used between them. This initial document specifies the various headers used to describe the structure of MIME messages. [STANDARDS-TRACK] In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document supplements RFC 3279. It describes the conventions for using the RSA Probabilistic Signature Scheme (RSASSA-PSS) signature algorithm, the RSA Encryption Scheme - Optimal Asymmetric Encryption Padding (RSAES-OAEP) key transport algorithm and additional one-way hash functions with the Public-Key Cryptography Standards (PKCS) #1 version 1.5 signature algorithm in the Internet X.509 Public Key Infrastructure (PKI). Encoding formats, algorithm identifiers, and parameter formats are specified. [STANDARDS-TRACK] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] This document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK] This document specifies the Internet Message Format (IMF), a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. This specification is a revision of Request For Comments (RFC) 2822, which itself superseded Request For Comments (RFC) 822, "Standard for the Format of ARPA Internet Text Messages", updating it to reflect current practice and incorporating incremental changes that were specified in other RFCs. [STANDARDS-TRACK] DomainKeys Identified Mail (DKIM) permits a person, role, or organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message. This can be an author's organization, an operational relay, or one of their agents. DKIM separates the question of the identity of the Signer of the message from the purported author of the message. Assertion of responsibility is validated through a cryptographic signature and by querying the Signer's domain directly to retrieve the appropriate public key. Message transit from author to recipient is through relays that typically make no substantive change to the message content and thus preserve the DKIM signature. This memo obsoletes RFC 4871 and RFC 5672. [STANDARDS-TRACK] This document provides recommendations for the implementation of public-key cryptography based on the RSA algorithm, covering cryptographic primitives, encryption schemes, signature schemes with appendix, and ASN.1 syntax for representing keys and for identifying the schemes. This document represents a republication of PKCS #1 v2.2 from RSA Laboratories' Public-Key Cryptography Standards (PKCS) series. By publishing this RFC, change control is transferred to the IETF. This document also obsoletes RFC 3447. This document adds a new signing algorithm, Ed25519-SHA256, to "DomainKeys Identified Mail (DKIM) Signatures" (RFC 6376). DKIM verifiers are required to implement this algorithm. ITU-T Informative References ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279. Over its thirty-five-year history, Internet Mail has changed significantly in scale and complexity, as it has become a global infrastructure service. These changes have been evolutionary, rather than revolutionary, reflecting a strong desire to preserve both its installed base and its usefulness. To collaborate productively on this large and complex system, all participants need to work from a common view of it and use a common language to describe its components and the interactions among them. But the many differences in perspective currently make it difficult to know exactly what another participant means. To serve as the necessary common frame of reference, this document describes the enhanced Internet Mail architecture, reflecting the current service. This memo provides information for the Internet community. GreenArrow Email [DKIM2] and its associated documents describe the DomainKeys Identified Mail v2 (DKIM2) email authentication protocol. DKIM2 is designed to address shortcomings in email authentication protocols and mechanisms released prior to DKIM2, specifically SPF [RFC7208], DKIM [RFC6376], DMARC [RFC9989], and ARC [RFC8617]. This document discusses best practices for signing, handling, and validating messages that carry DKIM2 signatures, and for interoperating with the authentication protocols and mechanisms that preceded DKIM2. Yahoo Google Fastmail Pty Ltd DomainKeys Identified Mail v2 (DKIM2) permits a person, role, or organization that owns a signing domain to document that it has handled an email message by associating their domain with the message. This is achieved by providing a hash value that has been calculated on the current contents of the message and then applying a cryptographic signature that covers the hash values and other details about the transmission of the message. Verification is performed by querying an entry within the signing domain's DNS space to retrieve an appropriate public key. As a message is transferred from author to recipient systems that alter the body or header fields will provide details of their changes and calculate new hash values. Further signatures will be added to provide a validatable "chain". This permits validators to identify the nature of changes made by intermediaries and apply a reputation to the systems that made changed. DKIM2 also allows recipients to detect when messages have been unexpectedly "replayed" and will ensure that Delivery Status Notifications are only sent to entities that were involved in the transmission of a message. Entrust Limited Entrust Limited OpenCA Labs Bundesdruckerei GmbH Cisco Systems This document defines combinations of US NIST Module-Lattice-Based Digital Signature Algorithm (ML-DSA) in hybrid with traditional algorithms RSASSA-PKCS1-v1.5, RSASSA-PSS, ECDSA, Ed25519, and Ed448. These combinations are tailored to meet regulatory guidelines in certain regions. Composite ML-DSA is applicable in applications that use X.509 or PKIX data structures that accept ML-DSA, but where the operator wants extra protection against breaks or catastrophic bugs in ML-DSA, and where existential unforgeability (EUF-CMA) level security is acceptable.

RSA Key Format Considerations The description of the RSA key format in is ambiguous as it cites RSAPublicKey but implies usage of SubjectPublicKeyInfo-RSAPublicKey. Deployment since publication of is for SubjectPublicKeyInfo-RSAPublicKey. This document specifies supporting both RSAPublicKey and SubjectPublicKeyInfo-RSAPublicKey, and updates to support both. The following is a more detailed discussion of the errata and the basis for supporting both formats. During the development of DKIM2, Christian Rößner posted an issue #9 in the DKIM2 GitHub repository Clarify DKIM2 RSA p= encoding: SPKI reflector keys fail a strict verifier. The errata says that and earlier drafts of this document specify parsing RSA keys as RSAPublicKey; however, the OpenSSL instructions in Appendix C of generate SubjectPublicKeyInfo. RSAPublicKey is defined in as: SubjectPublicKeyInfo is defined by (PKIX) as: SubjectPublicKey with RSA key content is then defined to be RSAPublicKey in examples use SubjectPublicKeyInfo-RSAPublicKey instead of the specified RSAPublicKey. Bron Gondwana notes that there are three errata on : 3017, 6674 and 7001. Issue #9 and Errata 3017 and 7001 state to use SubjectPublicKeyInfo. Errata 6674 and 7001 fix the example in .
Bron and Errata 3017 suggest that both formats should be supported for interoperability.

Acknowledgments The parent document to this is DKIM from which the vast majority of content is copied with only slight editing to update for DKIM2. The DKIM RFC was edited by Dave Crocker, Tony Hansen, and Murray Kucherawy. In addition, another source for this document is the Ed25519 extension to DKIM with content transferred verbatim directly. The Ed25519 extension RFC was written by John Levine. Credit for the content and specification for DKIM and the Ed25519 extension, from which DKIM2 is derived, goes to them. Thanks goes to Christian Rößner for writing a detailed errata on RSA encoding in , and to Bron Gondwana for working through the errata history including those on the DKIM WG errata database.