]> Yahoo

rclayton@yahooinc.com

Google

weihaw@google.com

Fastmail Pty Ltd

Level 2, 114 William Street 3000 Australia +61 457 416 436 brong@fastmailteam.com

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

Introduction DomainKeys Identified Mail v2 (DKIM2) permits a person, role, or organization to document that they have handled an email message by associating a domain name with the message . A public key signature is used to record that they have been able to read the contents of the message and write to it. Verification of claims is achieved by fetching a public key stored in the DNS under the relevant domain and then checking the signature. Message transit from author to recipient is through Forwarders that typically make no substantive change to the message content and thus preserve the DKIM2 signature. Where they do make a change the changes they have made are documented so that these can be "undone" and the original signature validated. When a message is forwarded from one system to another an additional DKIM2 signature is added on each occasion. This Chain of Custody assists Verifiers in distinguishing between messages that were intended to be sent to a particular email address and those that are being "replayed" to that address. The Chain of Custody can also be used to ensure that Delivery Status Notifications are only sent to entities that were involved in the transmission of a message. Organizations that process a message can add to their signature a request for feedback as to any opinion (for example, that the message was considered to be spam) that the eventual recipient of the message wishes to share.

Other DKIM2 documents Readers are advised to be familiar with the material in which provides deployment and operations guidance and advice along with which provides details on how DKIM keys are stored within the Domain Name System.

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. DKIM2 is designed to operate within the Internet Mail service, as defined in . Basic email terminology is taken from that specification. DKIM2 inherits many ideas from DKIM () which, for clarity we refer to in this specification as DKIM1. In addition, some features were influenced by the experimental ARC protocol () and the lessons learned from that experiment (). Syntax descriptions use Augmented BNF (ABNF) , together with the %s"..." notation for case-sensitive strings defined in . This document uses JSON to encode the Recipes which record changes made to the message header fields or the message body. The JSON objects are then base64 encoded. This means that a standard JSON parser can be used to create what may be quite complex data structures. Keys in the top-level JSON object other than "h" and "b" are reserved for future specifications, which may define new kinds of Recipe with their own syntax. If present, unrecognized top-level keys will be ignored. Within "h" and "b" only the structures defined in this document are permitted; in particular each Recipe step MUST contain exactly one of the keys "c", "d" or "u".

Signer 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 point is that a message is signed before it leaves the administrative domain of the Signer.

Forwarder defines a Relay as transmitting or retransmitting a message but states that it will not modify the envelope information or the message content semantics. It also defines a Gateway as a hybrid of User and Relay that connects heterogeneous mail services. In this document we use the concept of a Forwarder which is an MTA that receives a message and then, as an alternative to delivering it into a destination mailbox, can forward it on to another system in an automated, pre-determined, manner.

Reviser As will be seen, a Forwarder may alter the message content or header fields, in such a way that existing signatures on the message will no longer validate. If so, then a record will be made of these changes. We call a Forwarder that makes such changes a Reviser.

Verifier Elements in the mail system that verify signatures are referred to as Verifiers. These may be Forwarders, Revisers, MTAs, Mail Delivery Agents (MDAs), or MUAs. It is an expectation of DKIM2 that a recipient of a message will wish to verify some or all signatures before determining whether or not to accept the message or pass it on to another entity.

Signing Domain A domain name associated with a signature. This domain may be associated with the author of an email message, their organization, a company hired to deliver it, a mailing list operator, or some other entity that handles email messages. What they have in common is that at some point they had access to the entire contents of the message and were in a position to add their signature to the message.

Originator The entity that creates and sends the initial form of a message. The Originator adds the first Message-Instance header field (m=1) and the first DKIM2-Signature header field (i=1) to the message.

Header field As defined in , a header field is a single logical line in the message header consisting of a field name, a colon, and a field body (value). In this document "header field" always refers to a single field; "header fields" (plural) refers to multiple fields. The unqualified term "header" is avoided to prevent ambiguity.

Tag A named element within a header field (see and ). A tag consists of a tag-name and a tag-value separated by an equals sign. Tags are separated by semicolons within the header field.

Message body The content of an email message that follows the blank line after the header fields, treated as a sequence of octets. In this document, the terms "body" and "message body" are used interchangeably.

Hash A fixed-length value produced by applying a cryptographic hash function (such as SHA-256) to an input. DKIM2 uses hashes to create a compact, verifiable representation of message header fields and the message body.

Glossary The following terms are used throughout this document:

DKIM1

The original DomainKeys Identified Mail protocol as specified in .

DKIM Replay

An attack in which messages with valid signatures but with malicious content are sent from third party systems at scale, with the intent that the validity of the signature will ensure they are delivered.

DKIM2-Signature

A header field containing a cryptographic signature over the Message-Instance and DKIM2-Signature header fields of a message, along with metadata about the Signing Domain, SMTP envelope, and timestamp.

Message-Instance

A header field containing cryptographic hashes of the message header fields and body, along with optional Recipes that permit the reversal of changes made at that hop.

Recipe

A set of instructions encoded as a JSON object within the r= tag of a Message-Instance header field. Recipes allow a Verifier to reconstruct the previous state of a message from its current state, by specifying which parts of the header fields or body to copy and which literal values to substitute.

Chain of Custody

The sequence of DKIM2-Signature header fields on a message, each recording the SMTP envelope addresses (MAIL FROM and RCPT TO) used at each hop. A valid Chain of Custody demonstrates that the message followed a plausible path from Originator to the current recipient.

Selector

A subdivision of the key namespace for a Signing Domain, used to look up the public key in DNS. The Selector value is combined with the Signing Domain to form the DNS query name; for example, Selector "foo.bar" and Signing Domain "example.com" give "foo.bar._domainkey.example.com".

Authentic

A From header field is Authentic if, when it is placed into a message (either at message creation or later modification), the next DKIM2-Signature header field created for the message uses a Signing Domain that can be matched to the domain within the email address in the From.

Domain Policy Record

The Domain Policy Record holds a flag to indicate whether or not subdomains can assert that parent domain From header fields are Authentic. The Domain Policy Record for example.com lives at _domainkey.example.com.

Fully Verified DKIM2 Message

A Fully Verified DKIM2 Message is one which meets all the requirements set out in this specification on Signers, particularly those for generating DKIM2-Signature and Message-Instance header fields. Further, when transmitted, the SMTP MAIL FROM and RCPT TO will match the values recorded in the most recent DKIM2-Signature header field.

Provisionally Verified

A message is said to be Provisionally Verified if a cryptographic check shows that the hash and signature values in the highest numbered Message-Instance and DKIM2-Signature header fields correspond with the message to hand, along with some consistency checks on these header fields. This is a precondition for the message being a Fully Verified DKIM2 Message but not a guarantee that it is.

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 The "Domain" token is imported from . Other 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. Note that the definition of base64string allows for the presence of FWS, which simplifies folding header fields to an allowable line length. FWS within base64strings will be ignored when their value is being used. Values that match textstring, such as the names of hash algorithms, signature algorithms and flags that may be defined in the future, are case-sensitive.

Signing and verification cryptographic algorithms DKIM2 supports multiple hashing and digital signature algorithms. Two hashing algorithms (SHA256 and SHA512) and three signing algorithms (RSA-SHA256, Ed25519-SHA256 and ML-DSA-44) are defined in this specification. Signers MAY implement either or both of the two hashing algorithms and any or all of the signing algorithms. Verifiers MUST implement all five algorithms.

The SHA256 and SHA512 hashing algorithms The SHA256 hashing algorithm may be used to compute body and header hashes as defined in and . As an alternative SHA512 may be used. Both hash functions are specified in . The resultant values are identified by the text string "sha256" or "sha512" as appropriate and are placed into Message-Instance header fields.

The RSA-SHA256 signing algorithm The RSA-SHA256 signing algorithm computes a hash over all the Message-Instance and DKIM2-Signature header fields as described in using SHA-256 . That hash is then signed by the Signer using the RSA algorithm (defined in PKCS#1 version 1.5 ) supplied with the Signer's private key. The hash MUST NOT be truncated or converted into any form other than the native binary form before being signed. The signing algorithm MUST use a public exponent of 65537. Signers MUST use RSA keys of at least 1024 bits and SHOULD use keys of at least 2048 bits (as has been the case for DKIM1 since ). Verifiers MUST be able to validate signatures with keys ranging from 1024 bits to 4096 bits, and they MAY be able to validate signatures with larger keys. The signature value (expressed in base64) is placed (with the identifying text string "rsa-sha256") into DKIM2-Signature header fields.

The Ed25519-SHA256 signing algorithm The Ed25519-SHA256 signing algorithm computes a hash over all the Message-Instance and DKIM2-Signature fields as described in using SHA-256 as the hash-alg. It signs the hash with the PureEdDSA variant Ed25519, as defined in Section 5.1 of . The signature value (expressed in base64) is placed (with the identifying text string "ed25519-sha256") into DKIM2-Signature header fields.

The ML-DSA-44 signing algorithm The ML-DSA-44 algorithm computes a signature over all the Message-Instance and DKIM2-Signature fields as described in . DKIM2 uses "pure" ML-DSA, ML-DSA.Sign and ML-DSA.Verify (Algorithms 2 and 3 from ). DKIM2 does not use HashML-DSA, the field values are input directly into the signature algorithm without being hashed first. The five ASCII octets "DKIM2" (0x44 0x4B 0x49 0x4D 0x32, with no terminator) are used as the context string (ctx), for both signing and verifying. The signature value (expressed in base64) is placed (with the identifying text string "mldsa44") into DKIM2-Signature header fields. Such a signature is 3228 characters long when encoded, so FWS will need to be inserted into the base64string to allow header fields to be folded. Signers SHOULD use the default hedged (randomized) variant of ML-DSA.Sign. The deterministic variant SHOULD NOT be used on platforms where side-channel attacks are a concern and they cannot be otherwise mitigated. Both variants are verified in the same way.

Other algorithms Other algorithms may be defined in the future.

Selectors To support multiple concurrent public keys per Signing Domain, the key namespace is subdivided using Selectors. The number of public keys and corresponding Selectors for each domain is determined by the domain owner. Many domain owners will use just one Selector, whereas administratively distributed organizations can choose to manage disparate Selectors and key pairs in different regions or on different MTAs. Selectors can also be used to delegate a signing authority, which can be withdrawn at any time. Selectors also make it possible to seamlessly replace keys on a routine basis by signing with a new Selector, while keeping the key associated with the old Selector available. Periods are allowed in Selectors and are component separators. Periods in Selectors define DNS label boundaries in a manner similar to the conventional use in domain names. This will allow portions of the Selector namespace to be delegated. ABNF:

Key management Some level of assurance is required that a public key is associated with the claimed Signer. DKIM2 does this by fetching the key from the DNS for the Signing Domain specified in the d= field of the DKIM2-Signature header field. DKIM2 keys are stored in a subdomain named "_domainkey". Given a DKIM2-Signature field with a "d=" tag of "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. 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. NOTE: these keys are no different, and are stored in the same locations as those for DKIM1 (). Further details can be found in .

Domain Policy Record Many domain owners have delegated a subdomain to intermediaries that send email on their behalf. This subdomain allows the intermediary to set up a range of DNS records associated with the sending of email messages. It has become commonplace for the use of these subdomains as DKIM1 Signing Domains to be regarded as equivalent to using the parent domain. To preserve this behavior, DKIM2 takes account of the DKIM1 convention when assessing whether or not From header fields are Authentic. Authorizing subdomains to be able to make From header fields Authentic may be entirely inappropriate. Hence, DKIM2 introduces a Domain Policy Record to hold a flag to record when subdomains are not authorized to do this. The Domain Policy Record is stored in the "_domainkey" location itself (i.e. for "example.com" the record is at "_domainkey.example.com"). This is the location where the original DomainKeys algorithm () placed a "Policy Statement". It is a Tag=Value list (see ) held in a TXT RR. It always begins with the tag v=DKIM1 (for consistency with key records and to avoid any confusion with material). An optional f= tag holds a colon-separated list of flags. The flag "strict" indicates that subdomains are not authorized to make From header fields that use the domain Authentic. If the strict flag is absent, or there is no f= tag, they are authorized. Unrecognized flags are ignored. Purported Domain Policy Records that do not begin with v=DKIM1 are ignored; if more than one remains the relevant match result is a PERMERROR. If there is no Domain Policy Record then subdomains are authorized. If the Domain Policy Record cannot be retrieved because of a temporary DNS failure the relevant match result is a TEMPERROR. Note that the Domain Policy Record applies only to the domain that holds it. There is no inheritance of policy either "up" or "down" the DNS hierarchy. Further details can be found in .

Unsigned header fields As explained in detail below, DKIM2 will provide a cryptographic signature for all header fields that are present within a message, whether they have a standardized meaning or are just placed there at the whim of a particular sender. In order to simplify message handling some header fields are not signed and processing of the message by Signers and Verifiers will be performed as if they were not present. The exceptions fall into three classes: Trace header fields "Received" or "Return-Path" header fields are ignored. These are trace header fields as described in and serve only to document details of the SMTP transmission process. The experimental "Delivered-To:" header field () is also ignored. Other specifications designate further header fields as trace fields. A survey of such specifications, using the methodology of , identifies "DL-Expansion-History", "Original-Recipient", "SIO-Label-History" and "X400-Trace", which are also ignored. The same survey records header fields which are added by handling agents in transit even though no specification designates them as trace fields: "Apparently-To" and "X400-Received". For DKIM2 it is that behavior, rather than any formal designation, which matters, so these are also ignored. Any header field whose field name starts with "Received-", such as "Received-SPF" (), is ignored. This allows future specifications to create new trace header fields of this form without affecting DKIM2 processing. Other email authentication mechanisms "DKIM-Signature" header fields and the "ARC-Authentication-Results", "ARC-Message-Signature" and "ARC-Seal" header fields () are ignored. Not including DKIM1 and ARC header fields means that systems that wish to add other types of signature as well as a DKIM2 signature are free to do this in any convenient order. Header fields with purely local meaning "Authentication-Results" header fields are ignored. These header fields are defined in where it is made clear that their contents are only intended for use within the "trust boundary" of an "Administrative Management Domain". As they can only be used reliably within that trust boundary there has been no need to secure them cryptographically and given how they may be added or removed as messages cross trust boundaries it is inconvenient and unnecessary for DKIM2 to sign them. Header fields with a header field name starting with "X-" are ignored. Currently deployed email systems use these fields as proprietary trace header fields or for other proprietary reasons. They have no defined meaning for other systems and it considerably simplifies reporting on changes to header fields to ignore them. Note that the recommendations in mean that it is most unlikely that any header field name starting "X-" will be developed within the IETF.

Summary These header fields are not signed:

Recipes A set of Recipes is used to recreate the previous version of the body and/or header fields of a message. The Recipes are provided within a JSON object with the schema:

Note that the specification of JSON schemas is maintained by the JSON Schema organization, and the relevant specification document is linked to by the $schema field in each JSON schema. The JSON keys (property names) MUST be in lower case and they MUST be unique within any JSON object. These rules cannot be expressed within the JSON schema, so implementations will need to take other steps to ensure conformance. Particular care needs to be taken to ensure uniqueness. Strings in JSON are always composed of UTF-8 characters. Breaking out the "utf8-line" into a definition allows the schema to apply a pattern to it. This pattern ensures that the strings do not contain CR or LF characters. Since it may be necessary for a Recipe to deal with text that is not valid UTF-8, the "u" step is provided as an alternative to a "d" step. The pattern provided in the schema ensures that each string is a valid "base64string" as set out in including the restrictions on padding. However, there is one difference from "base64string" in that the schema does not allow FWS to appear within the string. This does not create any practical issues because the JSON object will be base64 encoded before being placed into a header field, and that encoded value can have FWS and hence can be folded in order to conform to header field length limits. Note that the restrictions on CR and LF characters apply to "u" step strings (once they are decoded) just as for "d", but this restriction cannot be expressed within the schema. It will be noted that the strings in a "u" step will be encoded twice. To avoid unnecessary extra processing a "u" step SHOULD NOT be used when a "d" step would suffice.

Header Recipes A Header Recipe is an array of instructions applied to the specified header fields with the given header field name. These Recipes are applied in order to the message which has been received so as to recreate the message as it was before modifications were made. Recipes MUST be provided for any relevant header field (see for header fields that are not relevant) that is changed; i.e. it is not possible to indicate that the previous state of the header fields cannot be recreated. If there is no "h" field in the JSON object then there was no modification to the header fields. Header field names in the JSON keys are matched with the message without regard to case. Recipes MUST NOT be specified for header fields that will not be signed (see ). A header field name MUST NOT be present more than once. If a header field name is not present in the JSON object then all header fields with that header field name are to be retained. If the Recipe array for a header field name that is present in the JSON object is empty then all instances of that header field are to be removed to reinstate the previous state of the message. Header fields are numbered "bottom up" (the opposite direction to the body lines). That is to say, when walking the header fields from the top of the message to the end of the header fields then the last header field instance encountered with any particular header field name is numbered 1, the header field (with the same header field name) above that is numbered 2, and so on. The header fields MUST be counted as if they were unfolded (in the normal manner). That is, all of the physical lines that form a single header field are processed under the same logical number. The Recipes are processed in order and the resulting header fields are emitted so that later header fields will appear above earlier header fields in the recreated message. Each Recipe step is a JSON object with exactly one key: A "c" step has the form {"c": [start, end]}. The relevant header field instances numbered from start to end inclusive, are to be emitted. The start value of each "c" step MUST be in ascending order and MUST be greater than the end value of all preceding "c" steps for this header field name. The end value MUST NOT be less than the start value. If they are equal, just one header field instance is to be emitted. A "d" step has the form {"d": ["value1", "value2", ...]}. Each string in the array is treated as a value to which the relevant header field name and a colon is prepended and a CRLF is appended and the resultant string is then emitted. Note that the way in which hashes are calculated (see ) means that no heed needs to be taken of wrapping or the case of the header field name. The text strings MUST NOT contain CR or LF characters. If a string is empty then the CRLF will immediately follow the header field name and colon. A "u" step is semantically identical to a "d" step except that each string value is in base64 and will be decoded before use. Since the values in a "d" step MUST be valid UTF-8, a "u" step MUST be used if that is not the case. It should be noted that a Header Recipe can conform to the JSON schema and still break the restrictions in this section.

Body Recipes A Body Recipe is an array of instructions applied to the message body which can recreate the message as it was before modifications were made. If there is no "b" field in the JSON object then there was no modification to the message body. Note that the JSON schema requires either "h" or "b" to be present. If the "b" field is null (there are no Recipes) then the previous state of the message body cannot be recreated. Verifiers of the message may be able to determine, by seeing which entity makes this declaration, that this is acceptable to them because, for example, that entity is providing a contractually arranged service. Body lines are numbered "top down" (the opposite direction to the header fields). The first line of the body (immediately after the blank line that indicates that there are no more header fields) is numbered 1. The Recipes are processed in order and the resulting body lines are emitted so that later lines will appear below earlier lines in the recreated message. Each Recipe step is a JSON object with exactly one key: A "c" step has the form {"c": [start, end]}. The message body lines from start to end, inclusive, are to be emitted. The start value of each "c" step MUST be in ascending order and MUST be greater than the end value of all preceding "c" steps. The end value MUST NOT be less than the start value. If they are equal, just one message body line is to be emitted. A "d" step has the form {"d": ["line1", "line2", ...]}. Each string in the array has a CRLF appended and the resultant string is emitted. The text strings MUST NOT contain CR or LF characters. If a string is empty then just a CRLF is emitted. A "u" step is semantically identical to a "d" step except that each string value is in base64 and will be decoded before use. Since the values in a "d" step MUST be valid UTF-8, a "u" step MUST be used if that is not the case. It should be noted that a Body Recipe can conform to the JSON schema and still break the restrictions in this section.

Message hash values A set of cryptographic "hashes" is used to record the current message body and header fields. The hashes are placed into the h= tag of a Message-Instance header field. Since Message-Instance header fields are ignored when calculating the header hash value, the body hash and header hash may be calculated in any convenient order.

Computing the body hash The body of messages is treated as merely a string of octets. DKIM2 messages can be either in plain-text or in MIME format; no special treatment is afforded to MIME content. Message attachments in MIME format MUST be included in the content that is signed. The DKIM2 body hash is calculated in the same manner as DKIM1's "simple" scheme: All empty lines at the end of the message body are ignored. An empty line is a line of zero length after removal of the line terminator. If there is no body or no trailing CRLF on the message body, a CRLF is added. That is "*CRLF" at the end of the body is converted to "CRLF". No other changes are made to the body, which is then processed by the relevant hash algorithm(s). The name of the hash and the hash value (converted to base64 form) is then inserted into (Signers) or compared to (Verifiers) the value of the "h=" tag of the Message-Instance header field that is being created/verified. If multiple hashes are calculated then multiple entries within the "h=" value will be inserted/compared.

Computing the header fields hash The header fields hash calculation done by a Signer MUST apply the following steps in the order given. A Verifier will need to do the equivalent steps in order to check that the hash they have received is correct. Convert all header field names (not the header field values) to lowercase. For example, convert "SUBJect: AbC" to "subject: AbC". Unfold all header field continuation lines as described in ; in particular, lines with terminators embedded in continued header field values (that is, CRLF sequences followed by WSP) MUST be interpreted without the CRLF. Implementations MUST NOT remove the CRLF at the end of the header field value. Ignore the header fields listed in . When calculating the header field hash any "Message-Instance" or "DKIM2-Signature" header fields MUST be ignored. These header fields will be included in the hash value that will be signed by a DKIM2-Signature header field and it simplifies implementations if they are not included twice, especially when determining whether all modifications to a message have been correctly declared. Convert all sequences of one or more WSP characters to a single SP character. WSP characters here include those before and after a line folding boundary. Delete all WSP characters at the end of each unfolded header field value. Delete any WSP characters remaining before and after the colon separating the header field name from the header field value. The colon separator MUST be retained. Place the header fields in ascending order of the octet values of their (lower-cased) header field names. If there is more than one header field with the same header field name then the header fields are placed in the order in which they would have been placed into the message header, that is from the last within the header upward (the same ordering as is used in the header Recipes (see )). It is sometimes suggested that some MTAs re-order header fields after they receive a message. If an MTA does change the order of header fields with the same header field name (and those header fields will be included in the hash calculation) then it is their responsibility to recover the original order before verifying an existing signature or passing a previously signed message to another MTA that may wish to do such verification. The hash(es) of the concatenated header fields are calculated. The name of the hash and the hash value (converted to base64 form) is then inserted into (Signers) or compared to (Verifiers) the value of the "h=" tag of the Message-Instance header field that is being created/verified. If multiple hashes are calculated then multiple entries within the "h=" value will be inserted/compared.

The relaxed domain match algorithm The relaxed domain match algorithm is used for several purposes in the DKIM2 protocol. The match algorithm is asymmetric in that attention needs to be paid to which value is "first" (Parameter1) and which is "second" (Parameter2). The aim is to allow a Signing Domain to be able to sign not only for itself but also for subdomains. As well as simplifying key handling for organizations that use subdomains, this also allows existing "bounce-handling" mechanisms that utilize subdomains to continue to work alongside DKIM2. For From header fields the match is also made in the other direction (see and Item below). The algorithm operates in such a way that there is no need to consider issues such as the different numbers of labels in so-called "public suffixes". The organization operating the "suffix" can determine whether they are part of the DKIM2 ecosystem or not. In practice, few if any "Top Level Domains" will act as a Signing Domain. Where the algorithm has to match rt= or mf= values from a DKIM2-Signature header field the values are base64 encoded. The description of the algorithm assumes that they have been decoded.

Uses of the relaxed domain match algorithm The relaxed domain match algorithm is used for four purposes: To assist in addressing the DKIM Replay problem DKIM2 provides a Chain of Custody for every message. There are several different cases in checking the Chain of Custody where a relaxed domain match is required. The i=1 DKIM2-Signature header field is not checked, nor is any DKIM2-Signature header field that follows one with an nd= tag. The remaining DKIM2-Signature header fields can be considered in ascending numeric order. If the mf= value recorded in a DKIM2-Signature header field is not null then a match is sought between the mf= value and a recipient address in the next lower numbered DKIM2-Signature header field. The mf= value is Parameter1 for the algorithm, the rt= value is Parameter2. If the mf= value is null (<>) then a match is sought between the Signing Domain (d=) and a recipient address in the next lower numbered DKIM2-Signature header field. The rt= value is Parameter1 for the algorithm, the d= value is Parameter2. A DKIM2-Signature header field with an nd= tag has no mf= or rt= tag. A match is sought between the Signing Domain (d=) and a recipient address in the next lower numbered DKIM2-Signature header field. The rt= value is Parameter1 for the algorithm, the d= value is Parameter2. The next numbered DKIM2-Signature header field will not be checked with this algorithm. Instead its d= value is required to be exactly the same as the nd= value (see ). It is necessary to check DKIM2-Signature header fields for a match between the Signing Domain (specified in the d= tag) and the MAIL FROM domain (mf=). The highest numbered DKIM2-Signature header field is checked to establish if the message is Provisionally Verified. All the DKIM2-Signature header fields are checked to establish if the message is capable of being a Fully Verified DKIM2 Message. The (decoded) mf= value is Parameter1 for the algorithm, the d= value is Parameter2. When the mf= value is null (mf=<>) or missing (nd= tag present) the matching algorithm is not used. To check that a From header field is Authentic, the domain from the addr-spec in the From header field will be matched with the Signing Domain of the relevant DKIM2-Signature header field (see ). The value from the From header field is Parameter1 for the algorithm, the d= value is Parameter2. If the algorithm finds that there is no match then the algorithm is re-run with the d= value as Parameter1 and the value from the From header field as Parameter2. If this second check gives a match but the Domain Policy Record (see ) for the domain from the From header field indicates that subdomains are not authorized to make this From header field Authentic, then there is no match. To ensure that a DSN (see ) is not forged, the Signing Domain used to send the DSN needs to match a recipient address of the message being reported on. That is, a domain from the rt= value of the highest numbered DKIM2-Signature in the message being reported on will have to match with the d= value in the i=1 DKIM2-Signature header field of the DSN. Signers of DSNs use this match when choosing d=; receivers of DSNs use it to check that the DSN has not been forged. The (decoded) value from rt= is Parameter1 to the algorithm, the d= value is Parameter2.

Details of the relaxed domain match algorithm The relaxed domain match algorithm proceeds as follows: If one of the values being compared is an rt= value then the algorithm is operated for each email address within the (decoded) rt= value in turn until one matches or all fail to match. If one of the values being compared is an email address then only the domain part of the value is used for the matches. The local part, any comments, mail parameters (along with the @ and any angle brackets) are ignored. A domain literal (e.g. <x@[192.0.2.1]>) never matches. and should be consulted for the exact syntax of email addresses and the complications that can arise through the use of comments and source routes. If there is an exact (caseless) match between Parameter1 and Parameter2 then the algorithm exits with a successful match result. Otherwise, if Parameter1 contains no dot there is no match. Otherwise, remove the leftmost label (the characters up to and including the first dot) from Parameter1 and return to step 3.

Tag=Value Lists DKIM2 uses a simple "tag=value" syntax in the Message-Instance and DKIM2-Signature header fields. It is also used in the DNS TXT records for public key values and the Domain Policy Record. Values are a series of strings containing either text or a base64string (see ). The name of the tag will determine the encoding and structure of each value. 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. Semicolon (";") characters MUST NOT occur in the tag value, since that separates tag-specs. The semicolon at the end of the tag-list is optional. Each tag-spec MUST match one of the ABNF rules provided when a tag-spec is being used in a specification. However, to allow specifications to be updated, a tag-spec that is not recognized is ignored. A specification that uses a Tag=Value list will make it clear whether tag-names or tag-values are case-sensitive or not. Absent any statement to the contrary both items are case-sensitive. The specification may also prescribe that whitespace within a tag-value is to be ignored. Tags may appear in any order, unless otherwise specified. 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. Tags that have an empty value are not the same as omitted tags. An empty value explicitly designates the empty string as the value. An omitted tag is treated as having the default value, should one be defined for that particular tag-spec. Tag=value pairs that represent the default value MAY be included to aid legibility.

The Message-Instance header field A Message-Instance header field documents the current contents of the message and, in the case of a Reviser, records any relevant changes that have been made to the incoming message. The Message-Instance header field is a trace header field (see Section 3.6.7 of ). The Message-Instance header field is a Tag=Value list (see ). No tags have default values and all tag-names MUST be in lower case. The m= and h= tags MUST be present. The r= tag is optional. ABNF:

m= the revision number of the Message-Instance header field The Originator of a message uses the value 1. Further Message-Instance header fields are added with a value one more than the current highest numbered Message-Instance header field. A message with gaps or duplicates in the numbering is not a Fully Verified DKIM2 Message. ABNF:

r= Recipes to recreate the previous instance of the message The r= tag value is the base64 encoded version of the JSON object that contains the Recipes that allow the previous instance of the message to be recreated (see ). ABNF:

h= the hash values for the message The h= tag value records one or more sets of hashes each made up of the cryptographic algorithm name, a header hash value and a body hash value. The hash values are base64strings. Calculating the hash values is explained in and the algorithms are described in . To provide for algorithmic agility more than one pair of hash values, using a different algorithm MAY be supplied in the same Message-Instance header field. An algorithm MUST NOT be present more than once in a single Message-Instance header field; if the hash values were the same this would be pointless and if they differ then the Signer is presumably attempting to confuse a Verifier. Hash-sets separated by "," form a group which passes if all the hash-sets in the group pass. Groups are separated by "|" and the overall result is a pass if any group is a pass. A "," binds more tightly than "|" (so a,b|c is a pass if both a and b pass or c does). If a Verifier has not implemented an algorithm then the hash result is not a pass. Signers using a new hash algorithm can use the "|" syntax to provide alternatives that the Verifier is more likely to understand. Signers who prefer "hybrid" cryptographic algorithms can use the "," to indicate that both the algorithms they provide are required to pass. ABNF:

The DKIM2-Signature header field The signature information for the message along with information linking the signed message to its delivery over SMTP is stored in a DKIM2-Signature header field. The DKIM2-Signature header field is a trace header field (see Section 3.6.7 of ). This header field is a Tag=Value list (see ). No tags have default values and all tag-names MUST be in lower case. The i=, m=, t=, d= and s= tags MUST be present. There MUST be either an nd= tag or both mf= and rt= tags. The other tags are optional. ABNF:

It will be noted that we have not included a version number. Experience from IMF onward shows that it is essentially impossible to change version numbers. If it becomes necessary to change DKIM2 in the sort of incompatible way that a v=2 / v=3 version number would support, it is expected that header fields will be labeled as DKIM3 instead.

i= the sequence number of the DKIM2-Signature header field The Originator of a message uses the value 1. Further DKIM2-Signature header fields are added with a value one more than the current highest numbered DKIM2-Signature header field. A message with gaps or duplicates in the numbering is not a Fully Verified DKIM2 Message. ABNF:

m= the highest numbered Message-Instance header field This value allows Verifiers to determine which entity made a particular revision to the message header fields or body. The value specifies the highest numbered Message-Instance header field in the message at the point at which this DKIM2-Signature header field was added. ABNF:

n= nonce value This text value, if present, is for the creator of the DKIM2-Signature header field to use for any purpose they wish. For example, it can be used as an index into a database to assist in handling Delivery Status Notifications received after delivery failures. To discourage use of this tag field as an alternative to the use of more appropriate header fields, the length of the string is restricted to 64 characters. Note the value MUST be simple ASCII and MUST NOT contain semicolon. ABNF:

t= signature timestamp The time that this header field was created. The format is the number of seconds since 00:00:00 on January 1, 1970 in the UTC time zone. The value is expressed as an unsigned integer in decimal ASCII. This value is not constrained to fit into a 31- or 32-bit integer. It is expected that values up to at least 10^12 will occur (this fits into 40 bits and will cover messages sent until approximately 33,700 AD). ABNF:

mf= the MAIL FROM used when the message was sent DKIM2 records the MAIL FROM value that was used when the message was transmitted over an SMTP link from the signing MTA. Note that MAIL FROM may be just "<>", for example for a Delivery Status Notification. The value is recorded as the base64 encoding of the reverse-path because of the complex syntax of reverse-path values (which can include characters which would confuse naive parsers of DKIM2-Signature header fields). The angle brackets MUST be included, but any "Mail-parameters" that were present after the reverse-path MUST NOT be included. ABNF:

rt= the RCPT TO value(s) used when the message was sent DKIM2 records the RCPT TO value(s) that were used when the message was transmitted over an SMTP link from the signing MTA. The value is recorded as the base64 encoding of the Forward-path because of the complex syntax of Forward-path values (which can include characters which would confuse naive parsers of DKIM2-Signature header fields). The angle brackets MUST be included, but any "Rcpt-parameters" that were present after the Forward-path MUST NOT be included. When a message is intended for more than one recipient then the rt= tag MAY include all of the recipients so that a single copy of the message can be sent to all of the recipients in one SMTP transaction. Alternatively, multiple copies of the message MAY be generated, each recording only the RCPT TO values used for that copy. However, a blind carbon copy (bcc) email address MUST NOT appear in the rt= tag of any copy of the message delivered to a recipient that is not a bcc recipient (see Section 3.6.3). ABNF:

nd= the domain that will appear in the next DKIM2-Signature header field This tag is used in order to provide a valid Chain of Custody when a message is being forwarded from a different domain than the one to which it arrived. The domain MUST be a valid DNS name under which a DKIM2 key record is published. The domain name in the nd= tag MUST exactly match the domain name of the d= tag of the next DKIM2-Signature in sequence (i=) order. Note that when an nd= tag is present both mf= and rt= MUST be omitted. It is permissible to have a sequence of more than one DKIM2-Signature header fields with an nd= tag, but this sequence (in unbroken ascending numeric order of i= tags) MUST end with a DKIM2-Signature that contains mf= and rt= tags. ABNF:

d= the Signing Domain associated with this signature This domain is used to form the query for the public key. The domain MUST be a valid DNS name under which the DKIM2 key record is published. The domain name in the d= tag MUST exactly match the rightmost labels of the domain name of the mf= tag. That is to say, the domain name of the mf= tag MUST either match the d= domain exactly or be a subdomain of the d= domain name. When the mf= domain is empty (it decodes to "<>"), as will be the case for Delivery Status Notifications (DSNs), then no match is required. ABNF:

s= the signature value(s) for the message The s= tag value records one or more signatures each made up of a Selector, the cryptographic algorithm name and the signature value in base64. Calculating the signature value is explained in and the algorithms are described in . The Selector values subdivide the namespace for the domain being used for signing. Note that the DNS lookup for the public key will check that the k= algorithm value is a match for the algorithm supplied in the tag. A Selector MUST NOT be present more than once in a single DKIM2-Signature header field; if the signature values differed then the Signer is presumably attempting to confuse a Verifier. To provide for algorithmic agility more than one signature, using different algorithms, MAY be supplied. More than one signature using the same algorithm (perhaps with a different key length) MAY be present provided that a different Selector is used for each. Signatures separated by "," form a group and a group of signatures passes if all of the signatures in that group pass. Groups of signatures are separated by "|" and the overall result is a pass if any group is a pass. A "," binds more tightly than "|" (so a,b|c is a pass if both a and b pass or c does). If a Verifier has not implemented an algorithm then the signature result is not a pass. Signers using a new signature algorithm can use the "|" syntax to provide alternatives that the Verifier is more likely to understand. Signers who prefer "hybrid" cryptographic algorithms can use the "," to indicate that both the algorithms they provide are required to pass. ABNF:

f= flags Flags serve two purposes; they either report what has been done to the message by the system creating the DKIM2-Signature or they make a request to systems that handle the mail thereafter. Flags are separated by commas, and optional white-space allows systems to add several flags without creating long lines. If a flag value is not recognized it has no effect. The flag values that report things are: "exploded": this message is being sent to more than one email address. This flag is of importance when detecting DKIM Replay attacks (see ). The flag values that make requests are: "feedback": this Signer requests feedback about how this message is handled during delivery and thereafter. This document does not describe what such feedback might be or where it might be delivered. If this flag is absent then feedback is explicitly not required. "feedhere": this Signer requests that any feedback about how this message is handled during delivery and thereafter is relayed via this hop. This flag will be set by privacy-conscious Forwarders when a message has a "feedback" flag set and the Forwarder does not wish the identity of systems to which the message is forwarded to be revealed to the requestor of feedback. ABNF:

From header fields are required to be Authentic Email addresses that appear in From header fields () will be displayed by MUAs to users. It needs to be clear that the use of that email address was authorized -- this specification expresses this as a requirement that the From header field is "Authentic". A From header field is Authentic when there is a relaxed domain match (see ) between the email address in the From header field and the Signing Domain found in the d= tag of the relevant DKIM2-Signature header field. The Authentic property is demonstrated by the ability to use the domain to sign. When the From header field has not been modified since the message was signed for the very first time, i.e. when the i=1 DKIM2-Signature field was created, then that From and that DKIM2-Signature are the relevant header fields for the comparison. If another system modifies the From header field, which will be apparent by inspecting the header Recipes (see ), then the lowest numbered (i=) DKIM2-Signature header field whose m= value is greater than or equal to the m= value of the Message-Instance header field with the Recipe will, along with the new From header field, be the relevant header fields for comparison. A From header field with more than one email address, or one that uses domain-literals (IP addresses instead of domains), can never be Authentic. If a message has such a From header field it will not be possible for a Verifier to conclude that it is a Fully Verified DKIM2 Message.

Using subdomains to make From header fields Authentic As explained in , custom and practice has been to permit subdomains to act as a Signing Domain on behalf of a parent domain. To avoid considerable disruption DKIM2 also allows this when determining whether or not a From header field is Authentic. Hence the relaxed domain match is operated both "downwards" and "upwards" when comparing the Signing Domain and the domain from the From header field. When this is not appropriate a parent domain can publish a Domain Policy Record (see ) to prevent the "upwards" comparison from occurring.

Signer actions This section gives the actions that need to be undertaken by the Signer of a message. They may be done in any appropriate order. If a message is not the initial form of a message (that is, it already contains DKIM2-Signature or Message-Instance header fields) then a Signer MUST NOT sign the message unless it is a Fully Verified DKIM2 Message (see ), or there is an out-of-band arrangement covering the situation (see ).

Add any necessary Message-Instance header fields If a system is generating the initial form of a message or if it is a Reviser that has made changes to the message body and/or header fields then it MUST compute the body hash as described in and the hash of the header fields as described in . If the message does not contain a Message-Instance header field then one MUST be added. If hashing the message body or relevant header fields does not give the same hash values as those recorded in the highest version (m=) Message-Instance header field then a new Message-Instance header field MUST be added. Such a Message-Instance header field MUST contain Recipes to allow recreation of the message corresponding to the hash values in the previously highest numbered Message-Instance header field. Alternatively, it could contain a null Recipe to indicate that recreating the previous version of the message body will not be possible. Null Recipes cannot be used in respect of header field changes. Using a null Recipe will impact the extent to which a message can be verified (see ). A system may add more than one Message-Instance header field if it wishes to do so, but the DKIM2 design allows all modifications made by any single system to be documented in a single Message-Instance header field. Note that the first (m=1) Message-Instance header field MAY contain Recipes if it is wished to record any changes made to a message as it enters the DKIM2 ecosystem. Adding a Message-Instance field with no Recipes (and thus the same hash values as the previously highest numbered Message-Instance field) is not forbidden; however, it is most likely to be pointless and a waste of time and energy for all concerned.

Provide a Chain of Custody for the message The DKIM2-Signature header field contains the MAIL FROM and RCPT TO values that will be used when the message is transmitted, so these "envelope" values MUST be available to (or deducible by) a Signer. The receiver of a message will check for an exact match (including the local parts of the email addresses) between the MAIL FROM / RCPT TO protocol values and the mf= and rt= values in the highest numbered (most recent) DKIM2-Signature header field. The matching will be case sensitive for the local part (before the @) and case insensitive for the domain (after the @). A Signer MUST ensure that this Chain of Custody check will succeed. It is acceptable for there to be more RCPT TO email addresses recorded in rt= than are actually used in the SMTP conversation, but any RCPT TO value which is used MUST be present in the rt= tag. Verifiers will check for a relaxed domain match (see ) between the Signing Domain (d=) and the domain in the MAIL FROM value. When the message being signed already has a DKIM2-Signature header field (i.e. it has already been transmitted at least once) then the Signer MUST ensure that the message has a valid Chain of Custody, as set out in Item . This Chain of Custody contributes to the way in which DKIM2 tackles DKIM Replay attacks. It may be that an MTA does not change anything in the message which would require a new Message-Instance header field and, additionally, it could forward it in such a manner that a Verifier would be able to verify the existing message (that is to say the MAIL FROM and RCPT TO will have appropriate values). In such a case, the MTA could choose not to add a DKIM2-Signature header field. To put this another way, an essentially transparent SMTP forwarding system need not be made "DKIM2 aware".

Chain of Custody for imaginary hops If a message is being forwarded then the MAIL FROM on the outgoing message (and the mf= tag which records this value) MUST be set in such a way that the Chain of Custody is not broken. However, it may be that the domains used for the delivery of the incoming message and the domains used for sending the message onward are not the same. For example, the incoming message might have been addressed to example.com, but the outgoing message will be sent from example.net. One way of ensuring that the Chain of Custody remains valid would be to generate an extra DKIM2-Signature header field that causes values to match, i.e. a record is fabricated that documents the mail being passed from one domain to another with appropriate "mf=" and "rt=" tag values which document the imaginary transfer of the message from one domain to the next. Alternatively the "nd=" tag may be used. When present the next higher sequence numbered DKIM2-Signature header field MUST be signed by the specified domain. However, since there are no mf= or rt= tag values there is no need to provide imaginary values for the imaginary "hop" between the domain used for receiving the message and the domain used to forward it. It will be noted that the creation of an extra DKIM2-Signature header field (whether the nd= scheme is used or not) will require the Signer to have access to a private key for the domain in the RCPT TO entry of the message as it arrived, or for a parent of that domain. Access to this private key is often achieved by the Signer creating the private key and never sharing it. One of two approaches is then taken to publishing the public key. The first is to provide the public key (and Selector value) to the domain owner who creates an appropriate DNS entry. The alternative is for the Signer to create a public key DNS entry within a part of the DNS that they control and the domain owner publishes a CNAME pointing at this. The general expectation is that signatures with an nd= tag have been applied by the same system as the next DKIM2-Signature field without an nd= tag. However, as a special case (where arrangements have been put in place to cover the situation) a message with an nd= tag in the highest numbered DKIM2-Signature header field may be sent over an SMTP connection. The receiving system will not be able to validate the MAIL FROM and RCPT TO values, so the message will not be a Fully Verified DKIM2 Message; whether it is acceptable will depend on out-of-band arrangements. The system MUST then provide a DKIM2-Signature header field with a d= tag that exactly matches the nd= tag. Adding such a header field will signal that the break in the Chain of Custody is intentional.

Ensure that From header fields are Authentic The Signing Domain to be used has to be consistent with the requirements already outlined for creating a valid Chain of Custody. Furthermore, if the original message is being signed, or the From header field has been modified, the Signing Domain MUST be chosen so that the From header field in the message will be Authentic (see ). If no Signing Domain can make the From header field Authentic, the message cannot ever be a Fully Verified DKIM2 Message. In simple terms, the Signing Domain will be equal to, or a parent of, the MAIL FROM domain. It will also be equal to, or a parent of, the From header field domain, or a subdomain of it if the From header field domain permits that to occur (see ). A Signer without access to a suitable private key cannot make the From header field Authentic, and nor can any Signer when the From header field has more than one address or a domain-literal.

Determine if an "exploded" flag is required An intermediary that receives a message and then sends copies of the message to more than one email address is said to have "exploded" it. In such a case the exploded flag MUST be set in the DKIM2-Signature header field that is being created to sign the outgoing messages. The flag MUST be set even if the outgoing messages differ. The flag MUST NOT be set on the very first DKIM2-Signature header field (i=1). The purpose of the flag is to give receivers information that could assist in the detection of DKIM Replay attacks (see ).

Record an accurate timestamp Verifiers check the timestamps in DKIM2-Signature header fields and if the message is "too old" or "from the future" will classify the message as not being a Fully Verified DKIM2 Message. These checks are made to allow systems to safely discard cached information that they may be using to handle DSNs or to detect DKIM Replay. Hence, a Signer MUST provide an accurate timestamp (t=) value, albeit Verifiers only check it against the limits set out in .

Determine which Selector value(s) to use The Signer has to record Selector value(s) in the DKIM2-Signature header field. Those Selector values allow a Verifier to fetch public key values. The Signer will need to have access to the corresponding private key to calculate the signature(s). How this is achieved is not a matter for this specification.

Calculate a signature value A Signer calculates a signature solely over the Message-Instance and DKIM2-Signature header fields of the message. The hashes of the body and other header fields are covered by the hashes in the highest version (m=) Message-Instance header field and hence the signature will in practice be signing the message as a whole. Most cryptographic schemes proceed by first calculating a hash value and then signing the hash value, but the DKIM2-Signature header field only provides the final signature value. This means that there is no difficulty if the hash value is inordinately long, or is not emitted by the cryptographic routine being used. The Signer MUST apply the following steps in the order given (which are not quite the same as the steps undertaken in calculating header hashes). Convert all relevant header field names (not the header field values) to lowercase. For example, convert "DKIM2-signature" to "dkim2-signature". Unfold all header field continuation lines as described in ; in particular, lines with terminators embedded in continued header field values (that is, CRLF sequences followed by WSP) MUST be interpreted without the CRLF. Implementations MUST NOT remove the CRLF at the end of the header field value. Delete all WSP characters. This means all WSP characters before and after the colon separating the header field name from the header field value, all WSP characters within the unfolded header field value and all trailing WSP characters before the CRLF. The colon separator and the CRLF MUST be retained. Place the header fields in order. First come the Message-Instance header fields in ascending instance (m=) order. Second are the DKIM2-Signature header fields in ascending sequence (i=) order. Last of all is an incomplete DKIM2-Signature header field (the one that this system is creating) with all tags present except that the signature value(s) within the (s=) value are set to the null string (""). The selector values, the algorithm name and the : , | punctuation remain. The incomplete header field MUST be unfolded, MUST have a trailing CRLF and MUST have WSP removed in just the same way as the complete header fields being processed. The concatenated header fields are then fed to the signature algorithm(s). Once all the values are available the null signature value strings are replaced by the base64 values of the signatures.

Verification A Verifier determines whether or not a message is a Fully Verified DKIM2 Message. That is whether or not the message meets all the requirements set out in this specification on Signers, particularly those for generating DKIM2-Signature and Message-Instance header fields. Further, when a Fully Verified DKIM2 Message is transmitted over SMTP, the MAIL FROM and RCPT TO values need to be consistent with values in the highest numbered DKIM2-Signature header field. However, it is not only the highest numbered header fields that need to give a PASS. The hashes in each Message-Instance header field are compared with the message recreated by applying, in descending order, the Recipes in every Message-Instance header field numbered higher than it. The signatures in each DKIM2-Signature header field are checked over the Message-Instance header fields numbered up to and including its m= value and the DKIM2-Signature header fields numbered below its i= value. The message is a Fully Verified DKIM2 Message only when all of these give a PASS. The body hashes in Message-Instance header fields numbered below one with a null Recipe cannot be checked, so such a message is not a Fully Verified DKIM2 Message. Whether it is nevertheless acceptable (for example, because there is a contractual relationship in place) is a matter for local policy. The specific checks that a Verifier makes and a sensible order in which to make them are discussed in . This section considers how a Verifier fits into the DKIM2 ecosystem.

Messages that are not Fully Verified DKIM2 Messages It is entirely a matter for local policy whether a message being a Fully Verified DKIM2 Message makes any difference to whether or not a message is accepted for delivery. However, if the message contains DKIM2-Signature or Message-Instance header fields but it is not a Fully Verified DKIM2 Message then it MUST NOT be sent to another system (without some local arrangement being in place). The reason for this is that the receiving system will be able to determine that the message is not a Fully Verified DKIM2 Message and that this would have been entirely apparent at the previous hop. To put it another way, it is not possible for an intermediary to "patch up" a message that is not a Fully Verified DKIM2 Message to make it into one, so an attempt to forward the message, without prior arrangement, could well fail and adverse conclusions could be drawn from that failure. Of course, discarding all the DKIM2 header fields and starting again (at i=1 m=1) will mean that whatever the previous history of the message might be, there will be a new Chain of Custody starting at this point. Naturally, attention will need to be paid to the provision that From header fields are required to be Authentic (see ).

Provisionally Verified messages In order to allow receivers of messages to operate efficiently, they MAY make an initial assessment of the likelihood that the message is a Fully Verified DKIM2 Message and accept delivery. This assessment is made by examining only the highest numbered DKIM2-Signature header field and the highest numbered Message-Instance header field and is straightforward to achieve. If the checks, set out below, all pass then the message is said to be Provisionally Verified. If the receiver then determines, upon closer inspection, that the message is not a Fully Verified DKIM2 Message after all, or they have some other reason for not wishing to accept the message -- perhaps based on analysis of its contents -- then they MAY generate a Delivery Status Notification (DSN) and send that back to the MAIL FROM address used for the delivery. The details of this procedure appear in . The checks are intended to be made while the SMTP connection is still open and the message can be rejected and not delivered. A DSN for a message that has been Provisionally Verified will go to a system that took part in the delivery, so it cannot become "backscatter". For a message that has not been Provisionally Verified there is no such assurance: a DSN generated after the message has been accepted may go to a third party whose address was forged, and that can be problematic. Hence, the best strategy for a message that is not wanted or is clearly invalidly signed is to reject it (with a 5xx error code) while the relevant SMTP conversation is still ongoing. It will then be for the sending system to determine what happens thereafter. A Verifier needs to perform the following checks to determine that a message is Provisionally Verified: The m= value in the highest numbered DKIM2-Signature header field is identical to the m= value of the highest numbered Message-Instance header field. The signatures (s=) in the highest numbered (i=) DKIM2-Signature header field give a PASS (see ). The hashes (h=) in the highest numbered (m=) Message-Instance header field give a PASS (see ). The MAIL FROM and RCPT TO values are consistent with the mf= and rt= values in the highest numbered DKIM2-Signature header field. Unless the (decoded) mf= value in the highest numbered DKIM2-Signature header field is null (<>), there is a relaxed domain match between the d= value and the mf= value (see Item ). If a Verifier gives a TEMPERROR result (it is not possible with the information to hand to determine whether or not the message is a Fully Verified DKIM2 Message, see ) a 4xx error code SHOULD be used in the SMTP conversation to allow the sending MTA to understand the situation. If the message passed Provisional Verification then further attempts to obtain the missing information could be made before deciding to send the DSN. If multiple attempts to obtain the information have all failed the TEMPERROR might usefully be upgraded to a PERMERROR before being recorded in any DSN that is sent. The mechanism set out in envisages out-of-band arrangements to allow the sending of messages with the highest numbered DKIM2-Signature header field containing an nd= tag. If no such arrangements are in place then the message is not Provisionally Verified. If the arrangements are in place and later analysis shows that the message cannot be converted into a Fully Verified DKIM2 Message then further out-of-band arrangements will be needed to deal with reporting this (using a Delivery Status Notification message or otherwise) because the provisions in this specification will not be adequate.

SMTP return codes Any 4xx or 5xx return code is sufficient to signal that a message cannot currently be delivered and whether or not a retry could succeed. However, if an MTA wishes to specifically signal that it is rejecting a message where signatures are missing or do not verify, a 550/5.7.x reply code SHOULD be used. If an MTA wishes to explicitly signal that it has not been possible to fetch a public key because of an apparently temporary DNS issue then a 451/4.7.5 reply code SHOULD be used. Enhanced status codes are defined in , including X.7.5 (cryptographic failure). adds codes for email authentication failures, such as 5.7.20 (no passing DKIM signature found).

Further observations on verification If the message has been modified since its original creation then the Message-Instance header fields will usually enable a Verifier to "undo" those modifications and reconstruct each preceding version of the message. In particular, a receiving system may wish to assess the original form of the message. All Recipes recorded in Message-Instance header fields could be undone in order (provided no null Recipe is present) and an assessment then made of whether the original message was a Fully Verified DKIM2 Message and in particular whether the From header field is Authentic. This assessment of the initial form of the message can be done without considering any other signatures and hash values except those on the i=1 and m=1 header fields and the simplicity of this check may be useful to some receivers. However, determining that the original message was a Fully Verified DKIM2 Message is only one part of determining whether the message being delivered is a Fully Verified DKIM2 Message; other checks will need to be made (see and ).

Verifier actions This section discusses the detail of the actions taken by a Verifier to determine whether or not a message is a Fully Verified DKIM2 Message.

Output states For compatibility with the Authentication-Results header field defined in a verification will result in one of five states. The states report whether or not the message has traveled to the destination without undeclared modifications and along a delivery path consistent with this specification. They do not attest in any way as to whether the message will be of value to the recipient or whether any modifications that have been declared are or are not benign. The five states are: NONE: The message does not contain any DKIM2-Signature or Message-Instance header fields. PASS: The message is a Fully Verified DKIM2 Message. FAIL: Verification of the message was completed but concluded that it was not a Fully Verified DKIM2 Message. PERMERROR: The message could not be verified due to some error that is unrecoverable, such as a required header field being absent or malformed. TEMPERROR: The message could not be verified due to a temporary inability to retrieve a DNS record. A later attempt may produce a different result. A Verifier MAY cease verifying once the outcome of the verification is known. Verifiers wishing to communicate the results of verification to other parts of the mail system may do so in whatever manner they see fit. If they wish to provide a human-readable string to describe a result that is not a PASS then, in order to provide the maximum possible assistance to senders, they SHOULD use the text strings specified in this document. These human-readable messages are described with m=<x> or tag=<y> placeholders; the <x> and <y> MUST be replaced with the relevant ordinal or tag name (without the < and > characters). Similarly <value> MUST be replaced by a relevant string for the particular message; and <s1> and <s2> MUST be replaced by appropriate Selector names. If the verification is being performed during an SMTP protocol conversation the human-readable string SHOULD be part of the 5xx or 4xx response string. If the results of the verification are being communicated in a Delivery Status Notification message () the human-readable string SHOULD be included. If a system wishes to record the results returned by a Verifier into a message then the Authentication-Results header field () is available for this purpose. DKIM2 specific values are defined in . It should be noted that this header field is ignored when calculating header hash values. If verification results are recorded then that record SHOULD include the human-readable string.

Ensure that the DKIM2 header fields are valid Verifiers will need to meticulously validate the format and values of all relevant Message-Instance and DKIM2-Signature header fields. They will also need to ensure that all required instances of these header fields are present and that all required tags are present and tags that cannot appear together do not do so. Unknown tags are to be ignored as set out in . No Fully Verified DKIM2 Message will contain a Message-Instance field with a higher m= value than occurs in any DKIM2-Signature field. There are also requirements on not repeating hash algorithms or Selectors. To assist debugging, errors in a JSON object specifying Recipes SHOULD be called out specifically and the text of invalid Recipe steps placed into error messages as appropriate. If the JSON is valid but the Verifier is not prepared to handle the complexity of the Recipes then a failure MAY be returned but the error message SHOULD NOT confuse this situation with other JSON errors. What "unacceptably complex" might mean is a local policy decision. When a message has a null Recipe a Verifier will be unable to complete all of the checks on the message, and a PERMERROR will result. Whether such a message is nevertheless acceptable is a matter for local policy (see ). A message with no DKIM2 header fields at all will be reported as NONE. It may of course contain DKIM1 signatures, or it may not be signed at all. Possible errors:

missing PERMERROR: Message-Instance m= is duplicated PERMERROR: Message-Instance m= syntax error PERMERROR: Message-Instance m= tag= missing PERMERROR: Message-Instance m= is not signed PERMERROR: Message-Instance m= has a duplicate hash algorithm PERMERROR: Message-Instance m= contains invalid JSON PERMERROR: Message-Instance m= recipe is invalid PERMERROR: Message-Instance m= JSON is unacceptably complex PERMERROR: Message-Instance m= has a null recipe PERMERROR: DKIM2-Signature i= missing PERMERROR: DKIM2-Signature i= is duplicated PERMERROR: DKIM2-Signature i= syntax error PERMERROR: DKIM2-Signature i= tag= missing PERMERROR: DKIM2-Signature i= tag= was unexpected PERMERROR: DKIM2-Signature i=1 has an exploded flag PERMERROR: DKIM2-Signature i= has a duplicate selector NONE: No DKIM2 header fields found ]]>

Check the timestamps A message is not a Fully Verified DKIM2 Message if any of its DKIM2-Signature header fields was created more than 14 days before the message was accepted over SMTP. This limit is intended to assist in the design of schemes that attempt to detect DKIM Replay without impacting transmission of messages on today's highly reliable and highly connected Internet. It might be expected that the timestamps on the DKIM2-Signature fields were in an ascending order. However, many systems do not always keep their clocks tightly synchronized with reality, and interworking will be impacted if sub-second accuracy is required of MTAs. That said, a timestamp that comes from the far future may be an attempt to confuse DKIM Replay systems. Hence a message is not a Fully Verified DKIM2 Message if any timestamp is from more than one day ahead of when the message was accepted over SMTP. It should be noted that checking timestamps requires accurate information about when a message was accepted over SMTP and a Verifier cannot assess the message otherwise. Possible errors:

signature expired FAIL: DKIM2-Signature i= signature is from the future ]]>

Check the Chain of Custody As explained in to check for a valid Chain of Custody a Verifier will need to check for an exact match between the MAIL FROM and RCPT TO parameters used when delivering a message and the values found in the mf= and rt= tags of the highest numbered DKIM2-Signature header field. There may be extra values in the rt= value, but all RCPT TO values actually used for delivery will need to be present. When comparing with SMTP protocol values the local part of the email address is checked as well as the domain. The domains are compared without regard to case and need to match exactly. As is usual in email protocols the case of the local part of an email address is assumed to matter (and see also ), so the local parts need to match exactly. Note that the decoded mf= and rt= values used for these matches include the angle brackets around the email addresses. A Verifier will also need to check, for every DKIM2-Signature field, that there is a relaxed domain match (see ) between the d= Signing Domain and the mf= value. However, if the (decoded) mf= value is null (mf=<>) or mf= is absent (there is an nd= tag present) then no match is performed. A Verifier then needs to check the Chain of Custody from start to finish. The steps for this are set out in Item and are not repeated here. If out-of-band arrangements (as explained in ) apply then there may not be a "next DKIM2-Signature" in the message -- it is about to be added. Hence, although the message is not presently a Fully Verified DKIM2 Message, the intention is that the receiving system will add a DKIM2-Signature header field whose d= matches the nd= value, to fix this. Possible errors:

MAIL FROM did not match FAIL: DKIM2-Signature i= RCPT TO did not match FAIL: DKIM2-Signature i= mf= and d= do not match FAIL: DKIM2-Signature i= nd= does not match FAIL: DKIM2-Signature i= unexpected nd= tag FAIL: DKIM2-Signature i= mf= does not match the rt= of i= FAIL: DKIM2-Signature i= d= does not match the rt= of i= ]]>

Fetch the public key The public keys of the signatures in DKIM2-Signature fields are needed to complete the verification process. Details of key management and representation are described in and . A key record that is malformed cannot be used and the result is a PERMERROR. Note that DNS timeouts are considered to be a TEMPERROR but a DNS result that indicates the key is absent is considered to be a PERMERROR. Additionally, if more than one record remains from the processing set out in , this is an error. Any human-readable error message that results from key fetching errors SHOULD provide the Selector value so that it is clear which key has a problem. notes that an ML-DSA-44 key that is not exactly 1312 octets (1752 characters once encoded as a base64string) is to be considered malformed. Similarly, Ed25519 keys are exactly 32 octets (44 characters as a base64string), see . Note that deprecates the h=, n=, s= and t= tags; DKIM2 ignores them if they are present. Possible errors:

public key could not be fetched PERMERROR: DKIM2-Signature i= public key does not exist PERMERROR: DKIM2-Signature i= public key has multiple records PERMERROR: DKIM2-Signature i= public key has a syntax error PERMERROR: DKIM2-Signature i= public key algorithm mismatch PERMERROR: DKIM2-Signature i= public key has been revoked PERMERROR: DKIM2-Signature i= public key is malformed ]]>

Perform the signature verification calculation Verifying a signature consists of actions semantically equivalent to the following steps: Prepare a canonicalized version of the Message-Instance and DKIM2-Signature header fields as described in . When checking a DKIM2-Signature header field only the Message-Instance header fields numbered up to and including its m= value and the DKIM2-Signature header fields numbered below its i= value are considered. The highest numbered DKIM2-Signature header field being checked needs to be put back to the state it was in when the signature was created. That is, the signature value(s) themselves are set to a null string (leaving everything else in the s= tag unchanged) and this "unsigned" version of the header field is used in the signature calculation. Use the relevant public key value(s) to check the signature(s). If the signature is correct then the intermediate result for that signature is PASS. If the signature does not match then the intermediate result is FAIL. If the value cannot be checked because of an issue with the key then the intermediate result is either TEMPERROR or PERMERROR. An algorithm which a Verifier has not implemented, or which it regards as insecure, or a public key it regards as too short, is given a PERMERROR intermediate result. Determine whether the signatures specified in the s= tag provide an overall PASS for the signing of the message. The "sig-all" (comma separated list) is checked and then the "sig-any" groups (lists separated by "|" characters). Of course there may be just one signature and no groups, which means there is no need to combine results to do the following steps. Examine each "sig-all" list of signatures. If every signature is a PASS then the intermediate result is PASS. If every signature that is not a PASS is a TEMPERROR then the intermediate result is TEMPERROR. If any signature is a FAIL then the intermediate result is FAIL, otherwise the intermediate result is PERMERROR. Now examine the "sig-any" groups. If any group is a PASS the result is PASS. If any group is TEMPERROR the result is TEMPERROR. If any group is FAIL then the result is FAIL, otherwise the result is PERMERROR. The human-readable text for any error SHOULD provide the relevant Selector values. The different "AND/OR" rules for combining signatures are to allow phased deployment of new algorithms alongside "hybrid" schemes should algorithms not be fully trusted. Note that the way in which results are reported means that if a retry could result in a PASS then TEMPERROR is reported and FAIL is reported when a signature does not match and no (sig-any) PASS overrides this. Possible errors (noting that there are many possible ways in which a complex combination of signatures can fail to give a PASS result and so this document does not try to provide text for all of them):

selector incorrect signature FAIL: DKIM2-Signature i= no group of signatures passed PERMERROR: DKIM2-Signature i= selector algorithm unknown PERMERROR: DKIM2-Signature i= selector algorithm insecure PERMERROR: DKIM2-Signature i= public key too short ]]>

Validating body and header hashes Verifying a hash value requires a Verifier to repeat the hash calculation performed by the Signer as set out in and . The hash values (for each relevant hash algorithm) can then be directly compared with the values in a Message-Instance header field and the PASS/FAIL calculated as follows: Compare the header and body hashes with the values in each of the hash-sets in the h= value in turn. If both match the intermediate result is PASS, otherwise the intermediate result is FAIL. A hash algorithm which a Verifier has not implemented, or which it regards as insecure, has a PERMERROR intermediate result. If there is just one hash-set then the intermediate result is the result. Otherwise examine each "hash-all" list of hash-sets separated by "," in the h= value. If every hash-set has an intermediate result of PASS then the intermediate result for that list is PASS. If any hash-set has an intermediate result of FAIL then the intermediate result for that list is FAIL, otherwise the intermediate result is PERMERROR. Now examine the "hash-any" groups. If any group has an intermediate result of PASS the result is PASS. If any group has an intermediate result of FAIL then the result is FAIL, otherwise the result is PERMERROR. Since there may be more than one hash algorithm present, the human-readable error message SHOULD indicate which algorithm's result failed to match and possibly also a fragment of its value. The different "AND/OR" rules for combining hashes are to allow phased deployment of new algorithms alongside "hybrid" schemes should algorithms not be fully trusted. Note that the way in which results are reported means that FAIL is reported when a hash-set does not match and no (hash-any) PASS overrides this. Possible errors (noting that there are many possible ways in which a complex combination of hash-sets can fail to give a PASS result and so this document does not try to provide text for all of them):

header hash mismatch FAIL: Message-Instance m= body hash mismatch FAIL: Message-Instance m= no group of hashes passed PERMERROR: Message-Instance m= algorithm unknown PERMERROR: Message-Instance m= algorithm insecure ]]>

Check for Authentic From header fields The From header fields within a Fully Verified DKIM2 Message are required to be Authentic. A Verifier will need to inspect the currently present From header field and any previous From header fields that Recipes show have been present since the message was first signed. To determine if a From header field is Authentic the relaxed domain match comparison () is used to compare the domain(s) in the From header field(s) with the relevant DKIM2-Signature field(s). Details of how to identify the relevant header fields are given in . Note that a From header field with more than one address, or with a domain-literal, can never be Authentic. Possible errors:

matching From is not authentic FAIL: DKIM2-Signature i= From forbids subdomain signing FAIL: DKIM2-Signature i= From has more than one address FAIL: DKIM2-Signature i= From uses a domain literal TEMPERROR: DKIM2-Signature i= policy for unavailable PERMERROR: DKIM2-Signature i= multiple records for policy ]]>

DKIM Replay attacks In a DKIM Replay attack a message with a valid signature but containing malicious content is sent to large numbers of recipients. The original Signer may only have signed one message but, without their knowledge, the malicious message is "replayed" at scale by a third party. However, since the signature on the message is valid, reputation systems may allow the messages to be delivered. Clearly, a Signer that wishes to preserve their good name will want to avoid signing malicious content, but the reality is that identifying that an individual message is malicious can be difficult. Receivers hosting numerous mailboxes can expect to see large numbers of identical messages sent to them directly from the originating system. Mechanisms for dealing with DKIM Replay need to be aware of this and act appropriately. What distinguishes a DKIM Replay attack, where a third party forwards signed messages, from an attack by a Signer that sends many malicious messages itself is that the original Signer may have limited the number of messages it allows to be sent, and the replay sidesteps that limit.

Preventing and detecting DKIM Replay attacks In DKIM2 a number of mechanisms make DKIM Replay much more difficult to achieve than has been the case with DKIM1. The Chain of Custody ensures that any system that is replaying will have provided cryptographic proof that they were an intermediary, and this information can inform decisions about whether or not to accept a message. Systems that provide service for large numbers of mailboxes can track whether the same message has been received more than once, having passed via an intermediary, without an "exploded" flag being added to indicate that multiple copies are to be expected. A message will have passed via an intermediary if there is more than one DKIM2-Signature header field present. A message will be "the same" if the header and body hash values of the original message (Message-Instance m=1) both match. Alternatively, if an exploded flag is present this will pin down where a system is claiming to have sent multiple copies. Assessing whether the flag was expected can affect decisions about delivery. If a system only learns the details of a single replayed message then of course counting is of no value, but if the system doing bulk replay has added an exploded flag then this can still affect decisions regarding delivery. A Receiver can attempt to distinguish a DKIM Replay attack from bulk sending (if they view this as valuable) by considering whether the messages arrived via an unexpected route, via a third party. Receivers need to be aware that they may receive multiple copies of the same message if different recipients of an original all choose to forward the message to the receiver. Malicious DKIM Replay attacks generally happen at such volume that distinguishing this re-convergence case is unlikely to be especially complex. It should be noted, as explains, that duplicated messages can result from a protocol level issue but, with appropriately set timer values, duplication is rare on today's Internet.

Delivery Status Notifications in the DKIM2 ecosystem In the DKIM2 ecosystem, when a message cannot be delivered then this is reported to the sending machine by means of an return code or, if the SMTP session has completed, by generating a Delivery Status Notification (DSN), as defined in . A DSN is sent to the MAIL FROM address in the usual manner. This address can be found in the mf= tag value (decoded from base64) of the highest numbered DKIM2-Signature header field. If this value has no address ("<>") then a DSN MUST NOT be sent. DKIM2 requires that there is a relaxed domain match between the Signing Domain and the mf= value in the same DKIM2-Signature header field. Hence a DSN for a message that has been Provisionally Verified will not be "backscatter" to the forged address of a third party that was not involved in handling the message. DKIM2 expects failure reports (DSNs) to be passed back in turn to each previous (validated) hop that was taken on the message's outward journey until a system is reached that is prepared to take full responsibility for the failure event. This method of propagating DSNs gives MTAs that were involved in passing the message forward the opportunity to adjust their future sending behavior.

DSN contents As set out in , a DSN has a top-level MIME part of type multipart/report. A valid DSN generated by a DKIM2 system MUST always contain three sections, the human-readable text, the machine readable status (in a message/delivery-status MIME part) and either a MIME part of type message/rfc822 that holds the original message exactly as it was submitted by the sending system or text/rfc822-headers which has just the header fields of that message.

DSN header and SMTP parameters The DSN itself MUST have appropriate Message-Instance and DKIM2-Signature fields, noting that the MAIL FROM to be used will be null ("<>"). The assurances in this section depend on the message being reported upon having been Provisionally Verified. It is not necessary to determine that it is a Fully Verified DKIM2 Message and of course some DSNs will be sent precisely because that is not the case. When creating a DSN there MUST be a relaxed domain match between the Signing Domain (placed into the d= value of the DKIM2-Signature header field of the DSN) and a recipient address in the rt= value of the highest numbered DKIM2-Signature header field of the message being reported upon (see Item ).

DSN propagation A Forwarder which receives a DSN MAY propagate this DSN to the MAIL FROM address used to deliver the message to it (which can be found in the highest numbered DKIM2-Signature header field). When propagating the DSN back along the forwarding chain the first and second parts of the DSN MUST be rewritten so as to remove any information about the destination to which the message was sent. Additionally, the original message in the third part of the DSN MUST be converted back to the state the message was in when it originally arrived -- before it was forwarded. If the message was modified by the Forwarder on the outward journey, those modifications MUST be undone and the Message-Instance header field documenting those changes MUST be removed. All DKIM2-Signature header fields added by this Forwarder (including any with an nd= tag) MUST be removed. A good faith effort SHOULD also be made to remove any header fields that are not signed by DKIM2, such as Received header fields, that were not present when the message arrived on its outward journey. If it is impossible to regenerate the body of the message, because a "null Recipe" means that the previous version cannot be reconstructed, then the body MUST be removed from the third part of the DSN and a text/rfc822-headers MIME part MUST be supplied. The resultant DSN is sent to the MAIL FROM address from the now highest numbered DKIM2-Signature header field. The DSN itself MUST have only one DKIM2-Signature field and only one Message-Instance header field: i.e. it is a new message. Following these procedures will ensure that no details of where the message was forwarded to will be revealed to the previous hop and the previous hop will be able to apply the same procedure to return the DSN to its previous hop, if that is required.

Authentication of inbound DSNs When a system receives a DKIM2 signed DSN, and the included original message is also DKIM2 signed, it SHOULD verify that the returned message (or just the header fields if the body is not present) has not been altered. This means: There is a relaxed domain match (see Item ) between the Signing Domain (d=) of the i=1 DKIM2-Signature header field of the DSN and a recipient address of the returned message. Recipient addresses are located in the rt= tag of the last (highest i= tag) DKIM2-Signature in the returned message. The last (highest i= tag) DKIM2-Signature header field of the returned message will be one that was generated by the system receiving the DSN, determined by examining the d= and mf= tags of that DKIM2-Signature header field. The header fields of the embedded message (in the message/rfc822 MIME part) can be verified by checking the header hash values in the highest numbered Message-Instance header field. The h= value is evaluated as in , except that if the body is not present a hash-set passes if its header hash matches. If the verification fails then the DSN MUST NOT be propagated any further. If verification has been performed prior to accepting the DSN from the sender the DSN SHOULD be rejected with a 550/5.7.x return code. If the verification cannot be completed because of a temporary issue (with DNS lookups) then a 4xx return code SHOULD be used. If the returned message does not contain DKIM2-Signature and Message-Instance header fields then this specification does not apply and there is no expectation that the DSN will be sent to any other system.

Preventing transport conversions DKIM2's design is predicated on valid input. In order to be signed a message MUST be in "network normal" format, so that lines are separated with CRLF and any transfer encoding has been applied. A message that is not compliant with , , and other relevant message format standards can be subject to attempts by intermediaries to correct or interpret such content. See Section 8 of for examples of changes that are commonly made. Such "corrections" may invalidate DKIM2 signatures or have other undesirable effects, including some that involve changes to the way a message is presented to an end user. When calculating the hash on messages that will be transmitted using base64 or quoted-printable encoding, Signers MUST compute the hash after the encoding, and Verifiers will check the hash of the encoded form of text. However, the hash MUST be computed before transport-level encodings such as SMTP "dot-stuffing" (the modification of lines beginning with a "." to avoid confusion with the SMTP end-of-message marker, as specified in ). Further, if the message contains local encoding that will be modified before transmission, that modification to canonical form MUST be done before signing. In particular, bare CR or LF characters (used by some systems as a local line separator convention) MUST be converted to the SMTP-standard CRLF sequence before the message is signed. Any conversion of this sort MUST be applied to the message actually sent to the recipient(s), not just to the version presented to the signing algorithm. More generally, the Signer MUST sign the message as it is expected to be received by the Verifier rather than in some local or internal form.

EAI () considerations for DKIM2 SMTPUTF8 lets MTAs send and receive non-ASCII characters. For the most part DKIM2 works only in ASCII. Domain values used in the SMTP protocol (MAIL FROM and RCPT TO) MUST be mapped from U-labels to A-labels before being recorded in DKIM2-Signature header fields or used in comparisons (see and ). Local parts are recorded unchanged (the base64 encoding means no difficulties will arise). Non-ASCII characters can also appear in From header fields, which are recorded and compared when checking if they are Authentic. Again, a U-label must be mapped to an A-label before comparisons are made or a lookup for a Domain Policy Record is performed. Local parts are only ever compared in exact matches. It should be noted that although email standards generally require messages to be transported in simple ASCII (and provide numerous encoding mechanisms to ensure this can be done) nevertheless messages may contain non-ASCII characters. This is irrelevant for hashing functions which treat messages as a simple array of bytes, but it does have an impact on Recipes (see ). Accordingly, Recipes handle header fields and body lines as being in UTF-8 (a superset of ASCII) and provide "u" steps within Recipes for handling sequences of byte values that are not valid UTF-8.

IANA Considerations IANA is requested to add two header fields to the "Permanent Message Header Field Names" table of the "Message Headers" registry (see ).

Header field name:

DKIM2-Signature

Applicable protocol:

mail

Status:

standard

Trace:

yes

Author/Change controller:

IETF

Specification document(s):

RFC XXXX (this document)

Header field name:

Message-Instance

Applicable protocol:

mail

Status:

standard

Trace:

yes

Author/Change controller:

IETF

Specification document(s):

RFC XXXX (this document)

No other IANA actions are requested.

Security Considerations Unsigned header fields can be added or removed without detection, and so they cannot safely be relied upon for security decisions. In particular, conclusions may be drawn about whether email messages are authentic based on Authentication-Results header fields which are unsigned. Of course, a Fully Verified DKIM2 Message provides unambiguous information about authenticity. Although a DKIM2 message may only have a single Message-Instance header field and just one DKIM2-Signature field, this specification allows for many such header fields, multiple hashes and signatures and places no limits on the complexity of Recipes. Even if limits were set, malicious messages could ignore them. surveys denial-of-service attacks and provides guidance as to how to address them. Implementers should take notice of this document and much other advice. If a message has a null Recipe then it will be impossible to verify the nature of any modifications made to the message when the null Recipe was added. The expectation is that null Recipes will only be used when there is a contractual relationship between the operators doing the modification (perhaps a security gateway of some kind) and the next recipient of the message. It is unlikely that this contractual relationship will extend any further, so attempting to forward the message any further could be unsuccessful. This specification requires RSA keys to be at least 1024 bits. Longer keys may be more appropriate in the future, and the algorithms specified here may, in the course of time, become deprecated. Signers will need to pay attention to community advice as to whether cryptographic primitives are appropriate to use, regardless of what this specification might say. The default in this specification is that a subdomain is authorized to make a From header field that uses a parent domain Authentic by reason of the relaxed domain match (see Item ). A domain that lets others put DNS records in its subdomains, whether customers, tenants or users (hosting platforms, dynamic DNS services, some public-suffix-style registries), needs to publish a Domain Policy Record with an f=strict setting to prevent those parties from being able to do that. Note that sibling domains can never be matched and a Top Level Domain (TLD) does not need f=strict unless From addresses at the TLD are in use. It is of course unfortunate to have a security control that defaults to authorized, but this is the only viable way to avoid considerable disruption to existing custom and practice.

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] This particular document is the third document in the series. It describes extensions to RFC 822 to allow non-US-ASCII text data in Internet mail header fields. [STANDARDS-TRACK] This document defines a set of extended status codes for use within the mail system for delivery status reports, tracking, and improved diagnostics. In combination with other information provided in the Delivery Status Notification (DSN) delivery report, these codes facilitate media and language independent rendering of message delivery status. [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 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] This document is one of a collection that, together, describe the protocol and usage context for a revision of Internationalized Domain Names for Applications (IDNA), superseding the earlier version. It describes the document collection and provides definitions and other material that are common to the set. [STANDARDS-TRACK] This document is the revised protocol definition for Internationalized Domain Names (IDNs). The rationale for changes, the relationship to the older specification, and important terminology are provided in other documents. This document specifies the protocol mechanism, called Internationalized Domain Names in Applications (IDNA), for registering and looking up IDNs in a way that does not require changes to the DNS itself. IDNA is only meant for processing domain names, not free text. [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 memo splits message submission from message relay, allowing each service to operate according to its own rules (for security, policy, etc.), and specifies what actions are to be taken by a submission server. Message relay is unaffected, and continues to use SMTP over port 25. When conforming to this document, message submission uses the protocol specified here, normally over port 587. This separation of function offers a number of benefits, including the ability to apply specific security or policy requirements. [STANDARDS-TRACK] The multipart/report Multipurpose Internet Mail Extensions (MIME) media type is a general "family" or "container" type for electronic mail reports of any kind. Although this memo defines only the use of the multipart/report media type with respect to delivery status reports, mail processing programs will benefit if a single media type is used for all kinds of reports. This memo obsoletes "The Multipart/Report Content Type for the Reporting of Mail System Administrative Messages", RFC 3462, and marks RFC 3462 and its predecessor as "Historic". [STANDARDS-TRACK] Full use of electronic mail throughout the world requires that (subject to other constraints) people be able to use close variations on their own names (written correctly in their own languages and scripts) as mailbox names in email addresses. This document introduces a series of specifications that define mechanisms and protocol extensions needed to fully support internationalized email addresses. These changes include an SMTP extension and extension of email header syntax to accommodate UTF-8 data. The document set also includes discussion of key assumptions and issues in deploying fully internationalized email. This document is a replacement for RFC 4952; it reflects additional issues identified since that document was published. [STANDARDS-TRACK] Historically, designers and implementers of application protocols have often distinguished between standardized and unstandardized parameters by prefixing the names of unstandardized parameters with the string "X-" or similar constructs. In practice, that convention causes more problems than it solves. Therefore, this document deprecates the convention for newly defined parameters with textual (as opposed to numerical) names in application protocols. This memo documents an Internet Best Current Practice. This document registers code points to allow status codes to be returned to an email client to indicate that a message is being rejected or deferred specifically because of email authentication failures. This document updates RFC 7208, since some of the code points registered replace the ones recommended for use in that document. 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. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document specifies a message header field called "Authentication-Results" for use with electronic mail messages to indicate the results of message authentication efforts. Any receiver-side software, such as mail filters or Mail User Agents (MUAs), can use this header field to relay that information in a convenient and meaningful way to users or to make sorting and filtering decisions. This document obsoletes RFC 7601. Google 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. Information Technology Laboratory National Institute of Standards and Technology

US Gaithersburg

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. An examination of a synchronization problem in the Simple Mail Transfer Protocol (SMTP) is presented. This synchronization problem can cause a message to be delivered multiple times. A method for avoiding this problem is suggested. Nodding familiarity with the SMTP specification, RFC-821, is required. This specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Internet Architecture Board This document provides an overview of possible avenues for denial-of-service (DoS) attack on Internet systems. The aim is to encourage protocol designers and network engineers towards designs that are more robust. We discuss partial solutions that reduce the effectiveness of attacks, and how some solutions might inadvertently open up alternative vulnerabilities. This memo provides information for the Internet community. "DomainKeys" creates a domain-level authentication framework for email by using public key technology and the DNS to prove the provenance and contents of an email. This document defines a framework for digitally signing email on a per-domain basis. The ultimate goal of this framework is to unequivocally prove and protect identity while retaining the semantics of Internet email as it is known today. Proof and protection of email identity may assist in the global control of "spam" and "phishing". This memo defines a Historic Document for the Internet community. 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. Email on the Internet can be forged in a number of ways. In particular, existing protocols place no restriction on what a sending host can use as the "MAIL FROM" of a message or the domain given on the SMTP HELO/EHLO commands. This document describes version 1 of the Sender Policy Framework (SPF) protocol, whereby ADministrative Management Domains (ADMDs) can explicitly authorize the hosts that are allowed to use their domain names, and a receiving host can check such authorization. This document obsoletes RFC 4408. 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. The Authenticated Received Chain (ARC) protocol provides an authenticated "chain of custody" for a message, allowing each entity that handles the message to see what entities handled it before and what the message's authentication assessment was at each step in the handling. ARC allows Internet Mail Handlers to attach assertions of message authentication assessment to individual messages. As messages traverse ARC-enabled Internet Mail Handlers, additional ARC assertions can be attached to messages to form ordered sets of ARC assertions that represent the authentication assessment at each step of the message-handling paths. ARC-enabled Internet Mail Handlers can process sets of ARC assertions to inform message disposition decisions, identify Internet Mail Handlers that might break existing authentication mechanisms, and convey original authentication assessments across trust boundaries. The address to which email is delivered might be different than any of the addresses shown in any of the content header fields that were created by the email's author. For example, the address used by the email transport service is provided separately, such as through SMTP's "RCPT TO" command, and might not match any address in the To: or cc: fields. In addition, before final delivery, handling can entail a sequence of submission/delivery events, using a sequence of different destination addresses that (eventually) lead to the recipient. As well, a receiving system's delivery process can produce local address transformations. It can be helpful for a message to have a common way to record each delivery in such a sequence, noting each address used in the sequence to that recipient, such as for (1) analyzing the path a message has taken, (2) loop detection, or (3) formulating the author's address in a reply message. This document defines a header field for this information. Email handling information discloses details about the email infrastructure, as well as about a particular recipient; this can raise privacy concerns. A header field such as this is not automatically assured of widespread use. Therefore, this document is being published as an Experimental RFC, looking for constituency and for operational utility. This document was produced through the Independent Submission Stream and was not subject to the IETF's approval process. Fastmail Pty Ltd DomainKeys Identified Mail Signatures v2 (DKIM2) produces a verification result for an email message. This document defines how that result is reported in the Authentication-Results header field, registering the "dkim2" authentication method, the result values it can take, and two properties which identify the signing domain and the point in the chain at which verification failed. Diagnostic detail about each hop is carried in a human-readable comment. Proofpoint Taughannock Networks This document calls for a conclusion to the experiment defined by “The Authenticated Received Chain (ARC) Protocol” [RFC8617], and recommends that ARC no longer be deployed or relied upon between disparate senders and receivers. The document summarizes what ARC set out to do, reports on operational experience, and explains how the experience gained during the experiment is being incorporated into the proposed DKIM2 work as the successor to DomainKeys Identified Mail [RFC6376]. To avoid any future confusion, it is therefore requested that ARC [RFC8617] be reclassified as “Historic”. Fastmail The IANA "Message Headers" registries record, for each registered header field, the protocol it belongs to, its status, whether it is a trace field, and the documents that specify it. Many documents have added entries over more than two decades, and the metadata in the registries is less complete than the metadata those documents supplied. RFC 4021, which performed the largest single bulk registration, gave IANA an explicit status and an explicit specification document for each of the roughly ninety fields it registered. Neither was recorded. Those entries carry a blank status and cite RFC 4021 itself in place of the specification. This document updates RFC 4021 by directing IANA to record the values its registration templates supplied. The "Trace" column, added to both registries by the revision of RFC 5322, was deliberately left empty for existing entries so that it could be filled in later. This document reviews the definition of each registered header field and every subsequent update to it, and gives IANA a single set of instructions for completing and correcting each entry. Each recommended change, and each decision to leave a non-obvious entry unchanged, is justified from the instructions or the clear intent of the documents that defined or modified the field. 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.

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

draft-ietf-dkim-dkim2-spec-09 Added Domain Policy Record and up/down algorithm for Authentic From. Removed key length MUST from Verifiers. Ensured all Verification checks have error text suggestions. Clarified that there is only one key record allowed per selector. Verifiers may regard algorithms and key lengths as insecure. No DKIM2 header fields at all is now NONE rather than PERMERROR. Various minor changes and improvements.

draft-ietf-dkim-dkim2-spec-08 Switched to using "pure" ML-DSA-44 and specified it properly. Signatures now have AND/OR algebra. Inconsistent text removed. Hashes now have AND/OR algebra. Clarification on signing non-value parts of a signature. "Validly Signed DKIM2 Message" renamed "Fully Verified DKIM2 Message". IANA section added. Changes to the list of ignored header fields. Clarifications to DSN validation and constraints on creation. Multiple other improvements and corrections.

draft-ietf-dkim-dkim2-spec-07 Removed donotmodify and donotexplode. Added the composite PQ algorithm MLDSA44-Ed25519-SHA512. Required From header fields to be Authentic. Outlawed duplicate JSON keys. Added "u" steps in Recipes to handle non UTF-8 characters. Also added patterns to the JSON schema to aid validity checking. Resurrected tag=value definition. Substantial rework of verification text to ensure it only states how to check for a Validly Signed DKIM2 Message, moving consideration of what that means into its own section. Rework of several Signer requirements, tying down several loose ends. Substantial rework of the description of the relaxed domain match. Substantial rework of the description of DKIM Replay. Chain of Custody checking now deals with null MAIL FROM and nd=. New glossary entries. An EAI section has been added. A security considerations section has been added. Multiple other improvements and corrections.

draft-ietf-dkim-dkim2-spec-06 Corrected mentions of non-existent PERMFAIL. Clarified that PASS (etc) does not mean a message is valuable or that modifications are benign. Added instructions for Verifiers to check for DKIM Replay. Tweaks to text and errors relating to too many algorithms or selectors; or for when signatures/hashes fail.

draft-ietf-dkim-dkim2-spec-05 Updated list of unsigned header fields to align with . Added sha512 to allow testing of hash function agility. Removed SHOULD NOT for speciously added Message-Instance fields, we now just point out they are pointless. Added text to forbid repetition of the same hash algorithm or the same Selector in any given header field. Provided messages for reporting infractions. Now specifies that header field names in the JSON Recipes MUST be lower case; and Verifiers should now report JSON issues specifically. Made Capitalization Consistent.

draft-ietf-dkim-dkim2-spec-04 Provided summary of unsigned header fields. Added text for situation when the highest DKIM2-Signature field of a message has an nd= tag. Added text to clarify checking of Message-Instance in a DSN.

draft-ietf-dkim-dkim2-spec-03 Move list of ignored header fields into its own section. Added the experimental Delivered-To: header field to the list. Remove possibility of a null Recipe for header field changes. Add nd= tag as an alternative to mf= rt= for imaginary hops. Change DSN propagation rules so that a DSN always contains the message headers up to the point at which the DSN creator saw the message on the outward journey. "feedhere" flag added.

draft-ietf-dkim-dkim2-spec-02 Made explicit that base64strings must be padded with zero bits. Fixed header field description in JSON to be single string and moved the removed info into the textual discussion. Removed the z body Recipe since DSNs do not actually need this. Added text to emphasize that semi-colons are (easy to parse) separators in Message-Instance and DKIM2-Signature. Also fixed the syntax for extension tags. Added Authentication-Results to the list of headers that are excluded from being signed. Added text about what donotmodify means and added text to the verification section about this and the donotexplode flag.

draft-ietf-dkim-dkim2-spec-01 Additions to terminology. Improved ABNF. Removed definition of tag-list and placed relevant text in the two header field definitions. Untangled the description of what needs to be verified from the description of how to verify and provided a list of human-readable strings to generate for errors.

draft-ietf-dkim-dkim2-spec-00 Removed JSON for hashes, signatures and SMTP parameters. Provided valid JSON for Recipes and added "z" for truncated body. Changed algorithm names for signing. Simplified the canonicalization performed for the header fields signed by DKIM2-Signature. Changed v= to m= for message instance numbering. General tidying up of specifying tag=value specifications and associated ABNF. Various other fixes for issues flagged in WG.