]> Google

weihaw@google.com

Yahoo

rclayton@yahooinc.com

dkim Internet-Draft DomainKeys Identified Mail (DKIM) permits the owner of a signing domain to document that they have handled an email message by associating their domain with the message. One part of this involves publishing a public key to a Domain Name System (DNS) record associated with the domain. Signing with the associated private key establishes their connection to the message. This document describes how to find the relevant DNS record and how information is recorded within it. This document updates RFC 6376, which describes DKIM, by clarifying the RSA public key format and by deprecating key record features that have not turned out to be useful. It also describes which parts of the key record are relevant to DomainKeys Identified Mail v2 (DKIM2) and describes a new Domain Policy Record for DKIM2 that can hold domain-wide settings.

Introduction DomainKeys Identified Mail permits the owner of a signing domain to document that they have handled an email message by associating their domain with the message by means of a cryptographic signature. describes how this is achieved in a protocol we will call, for the purposes of this document, DKIM1. describes DomainKeys Identified Mail v2, which we will call DKIM2. Usage of the term DKIM should be understood as referring to both DKIM1 and DKIM2. DKIM1 and DKIM2 use the same method of storing public key values in the Domain Name System (DNS). This document serves two purposes. It describes all the features of the key storage system used by DKIM1 as updated by and (along with errata) but then deprecates various features which have turned out to be of little practical use. It also states which of these features DKIM2 uses. Further, a new DKIM2-only Domain Policy Record is defined. DKIM1 does not use this.

Terminology and Definitions This section defines terms used in the rest of the document. 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 BCP 14 when, and only when, they appear in all capitals, as shown here. Terms such as Signer, Verifier, Signing Domain and Selector are used as defined in . Basic email terminology is taken from . Syntax descriptions use Augmented BNF (ABNF) , together with the %s"..." notation for case-sensitive strings defined in .

Whitespace There are two forms of whitespace used in this specification:

• WSP represents simple whitespace, i.e. a space or a tab character (formal definition in ).
• 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 given for information only): The definition of FWS is identical to that in except for the exclusion of obs-FWS.

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

• "qp-section" (a single line of quoted-printable-encoded text) is imported from .
• "sub-domain" (a single domain label) is imported from .

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: Note that base64strings are defined in , but that document does not contain any ABNF. A base64string MUST be padded with zero bits and trailing = characters provided if needed. This allows implementations to compare base64string values without decoding them. FWS may appear anywhere within a base64string and is ignored when the value is used.

Tag=Value Lists Key records use the "tag=value" syntax defined in the "Tag=Value Lists" section of , including its rules on whitespace, case sensitivity, duplicate tags, unrecognized tags, empty values and default values.

Public key management DKIM links a public key to the Signing Domain by fetching a public key value from the DNS. Selectors permit a Signing Domain to use multiple public keys, possibly using different cryptographic algorithms. Selectors allow keys to be rotated or distributed to third parties. DKIM keys are stored in a subdomain named "_domainkey". Given a Signing Domain "example.com" and a Selector of "foo.bar", the DNS query will be for "foo.bar._domainkey.example.com". Keys are held in a TXT RR at the selector name. Strings in a TXT RR MUST be concatenated together before use with no intervening whitespace. TXT records that begin with a "v=" tag with a value other than "DKIM1" are ignored. If more than one record then remains, this is an error. ABNF:

Key records The overall syntax is a Tag=Value list as described in . Key records are defined for three key types: Key types

Key type	Algorithm	DKIM1 usage	DKIM2 usage
"rsa"	RSA	,
"ed25519"	Ed25519
"mldsa44"	ML-DSA-44	not defined

The algorithms used with these keys, and the RSA key sizes, are specified in ; for DKIM1 see . The current valid tags for key records are described below. The p= tag MUST be present; all other tags are optional. It is RECOMMENDED to provide a v= tag. The h=, n=, s= and t= tags are deprecated: they SHOULD NOT be used in DKIM1 key records, and DKIM2 ignores them if they are present.

v= Version of the DKIM key record If specified, this tag MUST be set to "DKIM1" (without the quotes) and an exact match with those characters is required. If absent, the record is processed as if v=DKIM1 were present. This tag MUST be the first tag in the record. Records beginning with a "v=" tag with any other value MUST be discarded. ABNF:

k= Key type This tag indicates what type of key is present. If omitted then the value "rsa" is used. The p= tag is interpreted for the different key types as follows: rsa: p= is an ASN.1 DER-encoded RSAPublicKey (, Sections 3.1 and A.1.1) or a SubjectPublicKeyInfo containing one (, ). ed25519: p= is the 32-octet Ed25519 public key . mldsa44: p= is the 1312-octet ML-DSA-44 public key output by ML-DSA.KeyGen (Algorithm 1 of , encoded by pkEncode, Algorithm 22), with no SubjectPublicKeyInfo or other wrapper. DKIM1 Signers and Verifiers MUST support "rsa". DKIM2 Verifiers MUST support all three key types. ABNF:

p= Public-key data The public key data is a base64string whose format depends on the k= tag. An empty value means that this public key has been revoked. An "ed25519" key that is not 32 octets, or an "mldsa44" key that is not 1312 octets, is malformed. ABNF:

h= Acceptable hash algorithms A colon-separated list of the hash algorithms that may be used with this key. When absent all are allowed. Note that forbids the use of "rsa-sha1" for DKIM1. ABNF:

n= Notes that might be of interest to a human The notes text MUST be in quoted-printable format. DKIM does not use this text for any purpose. ABNF:

s= Service type A colon-separated list of service types to which the record applies (default ""). DKIM1 Verifiers ignore the key record if the list does not contain either "" or "email". ABNF:

t= Flags A colon-separated list of flags (default none). The flags are "y" (the domain is testing DKIM1) and "s" (DKIM1 requires an i= domain to be the same as d=). Unrecognized flags are ignored. ABNF:

Domain Policy Record The Domain Policy Record for a domain is a TXT RR at "_domainkey" under that domain (for "example.com", "_domainkey.example.com"). This record is used by DKIM2 and not by DKIM1. It is a Tag=Value list (see ). The two current valid tags are described below. The v= tag MUST be present; the f= tag is optional. TXT records at that name that do not begin with v=DKIM1 are ignored. If more than one remains, this is an error. If the "strict" flag is absent, or there is no f= tag, or there is no Domain Policy Record, subdomains are authorized. The record applies only to the domain that holds it; it is not inherited by subdomains or parents.

v= Version of the Domain Policy Record This tag MUST be set to "DKIM1" (without the quotes) and an exact match with those characters is required. This tag MUST be the first tag in the record. ABNF:

f= Flags for the Domain Policy Record A colon-separated list of flags (default none). One flag is defined, "strict": subdomains of the domain are not authorized to make From header fields that use the domain Authentic (see ). Unrecognized flags are ignored. ABNF:

Updates to RFC 6376 This document updates as follows:

• The h=, n=, s= and t= tags are deprecated (see ).
• An "rsa" key may be either an RSAPublicKey or a SubjectPublicKeyInfo containing one. This resolves errata 3017, 6674 and 7001.
• TXT records at a selector name that begin with v= other than "DKIM1" are ignored; more than one remaining record is an error.

IANA Considerations IANA is requested to make the following changes to registries in the "DomainKeys Identified Mail (DKIM) Parameters" group. As set out in , the status of an entry is either "active" or "historic".

_domainkey DNS TXT Record Tag Specifications IANA is requested to update the following entries and add the "f" entry. Other entries are unchanged.

TYPE	REFERENCE	STATUS
v	, RFC XXXX	active
h	, RFC XXXX	historic
k	, RFC XXXX	active
n	, RFC XXXX	historic
p	, RFC XXXX	active
s	, RFC XXXX	historic
t	, RFC XXXX	historic
f	RFC XXXX	active

IANA is also requested to add a note to the registry: "Tags in this registry are used in DKIM key records and in the DKIM2 Domain Policy Record. A tag name is registered once and has one meaning."

DKIM Key Type IANA is requested to update the "rsa" entry and to add the "mldsa44" entry as follows:

TYPE	REFERENCE	STATUS
rsa	, RFC XXXX	active
mldsa44	, RFC XXXX	active

DKIM Service Types IANA is requested to update both entries as follows:

TYPE	REFERENCE	STATUS
email	, RFC XXXX	historic
*	, RFC XXXX	historic

DKIM Selector Flags IANA is requested to update both entries as follows:

TYPE	REFERENCE	STATUS
y	, RFC XXXX	historic
s	, RFC XXXX	historic

DKIM2 Domain Policy Flags IANA is requested to create a new registry, "DKIM2 Domain Policy Flags", in the same group, for the flags used in the f= tag of the Domain Policy Record (see ). New entries are assigned by IETF Review . Each entry has a TYPE, a REFERENCE and a STATUS ("active" or "historic"). The initial entry is:

TYPE	REFERENCE	STATUS
strict	RFC XXXX	active

Underscored and Globally Scoped DNS Node Names IANA is requested to update the "_domainkey" entry for the TXT RR type in the "Underscored and Globally Scoped DNS Node Names" registry as follows. This document places the Domain Policy Record at the "_domainkey" name itself, in addition to the key records beneath it.

RR Type	_NODE NAME	Reference
TXT	_domainkey	, RFC XXXX

Security Considerations An "mldsa44" key of the wrong length is malformed (see p=); accepting one would lose the strong unforgeability ML-DSA provides (Section 3.6.2 of ). See also the Security Considerations of and .

References Normative References This initial document specifies the various headers used to describe the structure of MIME messages. [STANDARDS-TRACK] 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] This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [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 extends the base definition of ABNF (Augmented Backus-Naur Form) to include a way to specify US-ASCII string literals that are matched in a case-sensitive manner. 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 describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided. The cryptographic algorithm and key size requirements included when DomainKeys Identified Mail (DKIM) was designed a decade ago are functionally obsolete and in need of immediate revision. This document updates DKIM requirements to those minimally suitable for operation with currently specified algorithms. 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. Yahoo Google Fastmail Pty Ltd DomainKeys Identified Mail v2 (DKIM2) permits the owner of a signing domain to document that they have 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 "chain" that receivers can validate. This permits verifiers to identify the nature of changes made by intermediaries and apply a reputation to the systems that made changes. 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. ITU-T National Institute of Standards and Technology 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. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References 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. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Formally, any DNS Resource Record (RR) may occur under any domain name. However, some services use an operational convention for defining specific interpretations of an RRset by locating the records in a DNS branch under the parent domain to which the RRset actually applies. The top of this subordinate branch is defined by a naming convention that uses a reserved node name, which begins with the underscore character (e.g., "_name"). The underscored naming construct defines a semantic scope for DNS record types that are associated with the parent domain above the underscored branch. This specification explores the nature of this DNS usage and defines the "Underscored and Globally Scoped DNS Node Names" registry with IANA. The purpose of this registry is to avoid collisions resulting from the use of the same underscored name for different services.

Acknowledgments {#acks :numbered="false"} 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. Thanks goes to Hannah Stern and Mauro De Gennaro for their valuable review comments.

Changes from Earlier Versions RFC Editor: please remove this section before publication.

draft-ietf-dkim-dkim2-dns-03

• Substantial rework.