idnits 2.17.1 draft-ietf-dkim-rfc4871bis-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5672, but the abstract doesn't seem to directly say this. It does mention RFC5672 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1337 has weird spacing: '... email elec...' -- The document date (June 15, 2011) is 4700 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'ITU-X660-1997' is defined on line 2869, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS-180-3-2008' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU-X660-1997' ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Downref: Normative reference to an Informational RFC: RFC 5598 -- Obsolete informational reference (is this intentional?): RFC 4409 (Obsoleted by RFC 6409) -- Obsolete informational reference (is this intentional?): RFC 4870 (Obsoleted by RFC 4871) -- Obsolete informational reference (is this intentional?): RFC 4871 (Obsoleted by RFC 6376) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5451 (Obsoleted by RFC 7001) -- Obsolete informational reference (is this intentional?): RFC 5672 (Obsoleted by RFC 6376) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Crocker, Ed. 3 Internet-Draft Brandenburg InternetWorking 4 Obsoletes: 4871, 5672 T. Hansen, Ed. 5 (if approved) AT&T Laboratories 6 Intended status: Standards Track M. Kucherawy, Ed. 7 Expires: December 17, 2011 Cloudmark 8 June 15, 2011 10 DomainKeys Identified Mail (DKIM) Signatures 11 draft-ietf-dkim-rfc4871bis-12 13 Abstract 15 DomainKeys Identified Mail (DKIM) permits a person, role, or 16 organization that owns the signing domain to claim some 17 responsibility for a message by associating the domain with the 18 message. This can be an author's organization, an operational relay 19 or one of their agents. DKIM separates the question of the identity 20 of the signer of the message from the purported author of the 21 message. Assertion of responsibility is validated through a 22 cryptographic signature and querying the signer's domain directly to 23 retrieve the appropriate public key. Message transit from author to 24 recipient is through relays that typically make no substantive change 25 to the message content and thus preserve the DKIM signature. 27 This memo obsoletes RFC4871 and RFC5672. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on December 17, 2011. 46 Copyright Notice 48 Copyright (c) 2011 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.1. DKIM Architecture Documents . . . . . . . . . . . . . . . 6 65 1.2. Signing Identity . . . . . . . . . . . . . . . . . . . . . 6 66 1.3. Scalability . . . . . . . . . . . . . . . . . . . . . . . 6 67 1.4. Simple Key Management . . . . . . . . . . . . . . . . . . 6 68 1.5. Data Integrity . . . . . . . . . . . . . . . . . . . . . . 7 69 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 7 70 2.1. Signers . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 2.2. Verifiers . . . . . . . . . . . . . . . . . . . . . . . . 7 72 2.3. Identity . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 2.4. Identifier . . . . . . . . . . . . . . . . . . . . . . . . 8 74 2.5. Signing Domain Identifier (SDID) . . . . . . . . . . . . . 8 75 2.6. Agent or User Identifier (AUID) . . . . . . . . . . . . . 8 76 2.7. Identity Assessor . . . . . . . . . . . . . . . . . . . . 8 77 2.8. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . 8 78 2.9. Imported ABNF Tokens . . . . . . . . . . . . . . . . . . . 9 79 2.10. Common ABNF Tokens . . . . . . . . . . . . . . . . . . . . 9 80 2.11. DKIM-Quoted-Printable . . . . . . . . . . . . . . . . . . 10 81 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 11 82 3.1. Selectors . . . . . . . . . . . . . . . . . . . . . . . . 11 83 3.2. Tag=Value Lists . . . . . . . . . . . . . . . . . . . . . 13 84 3.3. Signing and Verification Algorithms . . . . . . . . . . . 14 85 3.4. Canonicalization . . . . . . . . . . . . . . . . . . . . . 15 86 3.5. The DKIM-Signature Header Field . . . . . . . . . . . . . 19 87 3.6. Key Management and Representation . . . . . . . . . . . . 29 88 3.7. Computing the Message Hashes . . . . . . . . . . . . . . . 33 89 3.8. Input Requirements . . . . . . . . . . . . . . . . . . . . 36 90 3.9. Output Requirements . . . . . . . . . . . . . . . . . . . 36 91 3.10. Signing by Parent Domains . . . . . . . . . . . . . . . . 36 92 3.11. Relationship between SDID and AUID . . . . . . . . . . . . 36 93 4. Semantics of Multiple Signatures . . . . . . . . . . . . . . . 37 94 4.1. Example Scenarios . . . . . . . . . . . . . . . . . . . . 37 95 4.2. Interpretation . . . . . . . . . . . . . . . . . . . . . . 39 97 5. Signer Actions . . . . . . . . . . . . . . . . . . . . . . . . 40 98 5.1. Determine Whether the Email Should Be Signed and by 99 Whom . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 100 5.2. Select a Private Key and Corresponding Selector 101 Information . . . . . . . . . . . . . . . . . . . . . . . 40 102 5.3. Normalize the Message to Prevent Transport Conversions . . 41 103 5.4. Determine the Header Fields to Sign . . . . . . . . . . . 42 104 5.5. Recommended Signature Content . . . . . . . . . . . . . . 44 105 5.6. Compute the Message Hash and Signature . . . . . . . . . . 45 106 5.7. Insert the DKIM-Signature Header Field . . . . . . . . . . 46 107 6. Verifier Actions . . . . . . . . . . . . . . . . . . . . . . . 46 108 6.1. Extract Signatures from the Message . . . . . . . . . . . 47 109 6.2. Communicate Verification Results . . . . . . . . . . . . . 52 110 6.3. Interpret Results/Apply Local Policy . . . . . . . . . . . 52 111 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 112 7.1. DKIM-Signature Tag Specifications . . . . . . . . . . . . 54 113 7.2. DKIM-Signature Query Method Registry . . . . . . . . . . . 54 114 7.3. DKIM-Signature Canonicalization Registry . . . . . . . . . 55 115 7.4. _domainkey DNS TXT Record Tag Specifications . . . . . . . 56 116 7.5. DKIM Key Type Registry . . . . . . . . . . . . . . . . . . 56 117 7.6. DKIM Hash Algorithms Registry . . . . . . . . . . . . . . 56 118 7.7. DKIM Service Types Registry . . . . . . . . . . . . . . . 57 119 7.8. DKIM Selector Flags Registry . . . . . . . . . . . . . . . 57 120 7.9. DKIM-Signature Header Field . . . . . . . . . . . . . . . 58 121 8. Security Considerations . . . . . . . . . . . . . . . . . . . 58 122 8.1. Misuse of Body Length Limits ("l=" Tag) . . . . . . . . . 58 123 8.2. Misappropriated Private Key . . . . . . . . . . . . . . . 58 124 8.3. Key Server Denial-of-Service Attacks . . . . . . . . . . . 59 125 8.4. Attacks Against the DNS . . . . . . . . . . . . . . . . . 59 126 8.5. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 60 127 8.6. Limits on Revoking Keys . . . . . . . . . . . . . . . . . 60 128 8.7. Intentionally Malformed Key Records . . . . . . . . . . . 61 129 8.8. Intentionally Malformed DKIM-Signature Header Fields . . . 61 130 8.9. Information Leakage . . . . . . . . . . . . . . . . . . . 61 131 8.10. Remote Timing Attacks . . . . . . . . . . . . . . . . . . 61 132 8.11. Reordered Header Fields . . . . . . . . . . . . . . . . . 61 133 8.12. RSA Attacks . . . . . . . . . . . . . . . . . . . . . . . 61 134 8.13. Inappropriate Signing by Parent Domains . . . . . . . . . 62 135 8.14. Attacks Involving Addition of Header Fields . . . . . . . 62 136 8.15. Malformed Inputs . . . . . . . . . . . . . . . . . . . . . 63 137 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 138 9.1. Normative References . . . . . . . . . . . . . . . . . . . 64 139 9.2. Informative References . . . . . . . . . . . . . . . . . . 65 140 Appendix A. Example of Use (INFORMATIVE) . . . . . . . . . . . . 66 141 A.1. The User Composes an Email . . . . . . . . . . . . . . . . 66 142 A.2. The Email is Signed . . . . . . . . . . . . . . . . . . . 67 143 A.3. The Email Signature is Verified . . . . . . . . . . . . . 68 144 Appendix B. Usage Examples (INFORMATIVE) . . . . . . . . . . . . 69 145 B.1. Alternate Submission Scenarios . . . . . . . . . . . . . . 69 146 B.2. Alternate Delivery Scenarios . . . . . . . . . . . . . . . 71 147 Appendix C. Creating a Public Key (INFORMATIVE) . . . . . . . . . 73 148 C.1. Compatibility with DomainKeys Key Records . . . . . . . . 74 149 Appendix D. MUA Considerations (INFORMATIVE) . . . . . . . . . . 74 150 Appendix E. Changes since RFC4871 . . . . . . . . . . . . . . . . 75 151 Appendix F. Acknowledgements . . . . . . . . . . . . . . . . . . 77 152 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 77 154 1. Introduction 156 DomainKeys Identified Mail (DKIM) permits a person, role, or 157 organization to claim some responsibility for a message by 158 associating a domain name [RFC1034] with the message [RFC5322], which 159 they are authorized to use. This can be an author's organization, an 160 operational relay or one of their agents. Assertion of 161 responsibility is validated through a cryptographic signature and 162 querying the signer's domain directly to retrieve the appropriate 163 public key. Message transit from author to recipient is through 164 relays that typically make no substantive change to the message 165 content and thus preserve the DKIM signature. A message can contain 166 multiple signatures, from the same or different organizations 167 involved with the message. 169 The approach taken by DKIM differs from previous approaches to 170 message signing (e.g., Secure/Multipurpose Internet Mail Extensions 171 (S/MIME) [RFC5751], OpenPGP [RFC4880]) in that: 173 o the message signature is written as a message header field so that 174 neither human recipients nor existing MUA (Mail User Agent) 175 software is confused by signature-related content appearing in the 176 message body; 178 o there is no dependency on public and private key pairs being 179 issued by well-known, trusted certificate authorities; 181 o there is no dependency on the deployment of any new Internet 182 protocols or services for public key distribution or revocation; 184 o signature verification failure does not force rejection of the 185 message; 187 o no attempt is made to include encryption as part of the mechanism; 189 o message archiving is not a design goal. 191 DKIM: 193 o is compatible with the existing email infrastructure and 194 transparent to the fullest extent possible; 196 o requires minimal new infrastructure; 198 o can be implemented independently of clients in order to reduce 199 deployment time; 201 o can be deployed incrementally; 203 o allows delegation of signing to third parties. 205 1.1. DKIM Architecture Documents 207 Readers are advised to be familiar with the material in [RFC4686], 208 [RFC5585] and [RFC5863], which respectively provide the background 209 for the development of DKIM, an overview of the service, and 210 deployment and operations guidance and advice. 212 1.2. Signing Identity 214 DKIM separates the question of the identity of the signer of the 215 message from the purported author of the message. In particular, a 216 signature includes the identity of the signer. Verifiers can use the 217 signing information to decide how they want to process the message. 218 The signing identity is included as part of the signature header 219 field. 221 INFORMATIVE RATIONALE: The signing identity specified by a DKIM 222 signature is not required to match an address in any particular 223 header field because of the broad methods of interpretation by 224 recipient mail systems, including MUAs. 226 1.3. Scalability 228 DKIM is designed to support the extreme scalability requirements that 229 characterize the email identification problem. There are currently 230 over 70 million domains and a much larger number of individual 231 addresses. DKIM seeks to preserve the positive aspects of the 232 current email infrastructure, such as the ability for anyone to 233 communicate with anyone else without introduction. 235 1.4. Simple Key Management 237 DKIM differs from traditional hierarchical public-key systems in that 238 no Certificate Authority infrastructure is required; the verifier 239 requests the public key from a repository in the domain of the 240 claimed signer directly rather than from a third party. 242 The DNS is proposed as the initial mechanism for the public keys. 243 Thus, DKIM currently depends on DNS administration and the security 244 of the DNS system. DKIM is designed to be extensible to other key 245 fetching services as they become available. 247 1.5. Data Integrity 249 A DKIM signature associates the d= name with the computed hash of 250 some or all of the message (see Section 3.7) in order to prevent the 251 re-use of the signature with different messages. Verifying the 252 signature asserts that the hashed content has not changed since it 253 was signed, and asserts nothing else about "protecting" the end-to- 254 end integrity of the message. 256 2. Terminology and Definitions 258 This section defines terms used in the rest of the document. 260 DKIM is designed to operate within the Internet Mail service, as 261 defined in [RFC5598]. Basic email terminology is taken from that 262 specification. 264 Syntax descriptions use Augmented BNF (ABNF) [RFC5234]. 266 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 267 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 268 "OPTIONAL" in this document are to be interpreted as described in 269 [RFC2119]. These words take their normative meanings only when they 270 are presented in ALL UPPER CASE. 272 2.1. Signers 274 Elements in the mail system that sign messages on behalf of a domain 275 are referred to as signers. These may be MUAs (Mail User Agents), 276 MSAs (Mail Submission Agents), MTAs (Mail Transfer Agents), or other 277 agents such as mailing list exploders. In general, any signer will 278 be involved in the injection of a message into the message system in 279 some way. The key issue is that a message must be signed before it 280 leaves the administrative domain of the signer. 282 2.2. Verifiers 284 Elements in the mail system that verify signatures are referred to as 285 verifiers. These may be MTAs, Mail Delivery Agents (MDAs), or MUAs. 286 In most cases it is expected that verifiers will be close to an end 287 user (reader) of the message or some consuming agent such as a 288 mailing list exploder. 290 2.3. Identity 292 A person, role, or organization. In the context of DKIM, examples 293 include the author, the author's organization, an ISP along the 294 handling path, an independent trust assessment service, and a mailing 295 list operator. 297 2.4. Identifier 299 A label that refers to an identity. 301 2.5. Signing Domain Identifier (SDID) 303 A single domain name that is the mandatory payload output of DKIM and 304 that refers to the identity claiming some responsibility for the 305 message by signing it. It is specified in Section 3.5. 307 2.6. Agent or User Identifier (AUID) 309 A single identifier that refers to the agent or user on behalf of 310 whom the Signing Domain Identifier (SDID) has taken responsibility. 311 The AUID comprises a domain name and an optional . The 312 domain name is the same as that used for the SDID or is a sub-domain 313 of it. For DKIM processing, the domain name portion of the AUID has 314 only basic domain name semantics; any possible owner-specific 315 semantics are outside the scope of DKIM. It is specified in 316 Section 3.5. 318 Note the constraint on the value of "i=" that can be imposed by the 319 "t=s" tag of the stored key record. (See Section 3.6.1.) 321 2.7. Identity Assessor 323 A module that consumes DKIM's mandatory payload, which is the 324 responsible Signing Domain Identifier (SDID). The module is 325 dedicated to the assessment of the delivered identifier. Other DKIM 326 (and non-DKIM) values can also be delivered to this module as well as 327 to a more general message evaluation filtering engine. However, this 328 additional activity is outside the scope of the DKIM signature 329 specification. 331 2.8. Whitespace 333 There are three forms of whitespace: 335 o WSP represents simple whitespace, i.e., a space or a tab character 336 (formal definition in [RFC5234]). 338 o LWSP is linear whitespace, defined as WSP plus CRLF (formal 339 definition in [RFC5234]). 341 o FWS is folding whitespace. It allows multiple lines separated by 342 CRLF followed by at least one whitespace, to be joined. 344 The formal ABNF for these are (WSP and LWSP are given for information 345 only): 346 WSP = SP / HTAB 347 LWSP = *(WSP / CRLF WSP) 348 FWS = [*WSP CRLF] 1*WSP 350 The definition of FWS is identical to that in [RFC5322] except for 351 the exclusion of obs-FWS. 353 2.9. Imported ABNF Tokens 355 The following tokens are imported from other RFCs as noted. Those 356 RFCs should be considered definitive. 358 The following tokens are imported from [RFC5321]: 360 o "Local-part" (implementation warning: this permits quoted strings) 362 o "sub-domain" 364 The following tokens are imported from [RFC5322]: 366 o "field-name" (name of a header field) 368 o "dot-atom-text" (in the Local-part of an email address) 370 The following tokens are imported from [RFC2045]: 372 o "qp-section" (a single line of quoted-printable-encoded text) 374 o "hex-octet" (a quoted-printable encoded octet) 376 INFORMATIVE NOTE: Be aware that the ABNF in [RFC2045] does not 377 obey the rules of [RFC5234] and must be interpreted accordingly, 378 particularly as regards case folding. 380 Other tokens not defined herein are imported from [RFC5234]. These 381 are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF, 382 etc. 384 2.10. Common ABNF Tokens 385 The following ABNF tokens are used elsewhere in this document: 386 hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] 387 ALPHADIGITPS = (ALPHA / DIGIT / "+" / "/") 388 base64string = ALPHADIGITPS *([FWS] ALPHADIGITPS) 389 [ [FWS] "=" [ [FWS] "=" ] ] 390 hdr-name = field-name 391 qp-hdr-value = dkim-quoted-printable ; with "|" encoded 393 2.11. DKIM-Quoted-Printable 395 The DKIM-Quoted-Printable encoding syntax resembles that described in 396 Quoted-Printable [RFC2045], Section 6.7: any character MAY be encoded 397 as an "=" followed by two hexadecimal digits from the alphabet 398 "0123456789ABCDEF" (no lowercase characters permitted) representing 399 the hexadecimal-encoded integer value of that character. All control 400 characters (those with values < %x20), 8-bit characters (values > 401 %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon 402 (";", %x3B) MUST be encoded. Note that all whitespace, including 403 SPACE, CR, and LF characters, MUST be encoded. After encoding, FWS 404 MAY be added at arbitrary locations in order to avoid excessively 405 long lines; such whitespace is NOT part of the value, and MUST be 406 removed before decoding. Use of characters not listed as "mail-safe" 407 in [RFC2049] is NOT RECOMMENDED. 409 ABNF: 411 dkim-quoted-printable = *(FWS / hex-octet / dkim-safe-char) 412 ; hex-octet is from RFC2045 413 dkim-safe-char = %x21-3A / %x3C / %x3E-7E 414 ; '!' - ':', '<', '>' - '~' 415 ; Characters not listed as "mail-safe" in 416 ; [RFC2049] are also NOT RECOMMENDED. 418 INFORMATIVE NOTE: DKIM-Quoted-Printable differs from Quoted- 419 Printable as defined in [RFC2045] in several important ways: 421 1. Whitespace in the input text, including CR and LF, must be 422 encoded. [RFC2045] does not require such encoding, and does 423 not permit encoding of CR or LF characters that are part of a 424 CRLF line break. 426 2. Whitespace in the encoded text is ignored. This is to allow 427 tags encoded using DKIM-Quoted-Printable to be wrapped as 428 needed. In particular, [RFC2045] requires that line breaks in 429 the input be represented as physical line breaks; that is not 430 the case here. 432 3. The "soft line break" syntax ("=" as the last non-whitespace 433 character on the line) does not apply. 435 4. DKIM-Quoted-Printable does not require that encoded lines be 436 no more than 76 characters long (although there may be other 437 requirements depending on the context in which the encoded 438 text is being used). 440 3. Protocol Elements 442 Protocol Elements are conceptual parts of the protocol that are not 443 specific to either signers or verifiers. The protocol descriptions 444 for signers and verifiers are described in later sections (Signer 445 Actions (Section 5) and Verifier Actions (Section 6)). NOTE: This 446 section must be read in the context of those sections. 448 3.1. Selectors 450 To support multiple concurrent public keys per signing domain, the 451 key namespace is subdivided using "selectors". For example, 452 selectors might indicate the names of office locations (e.g., 453 "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date 454 (e.g., "january2005", "february2005", etc.), or even an individual 455 user. 457 Selectors are needed to support some important use cases. For 458 example: 460 o Domains that want to delegate signing capability for a specific 461 address for a given duration to a partner, such as an advertising 462 provider or other outsourced function. 464 o Domains that want to allow frequent travelers to send messages 465 locally without the need to connect with a particular MSA. 467 o "Affinity" domains (e.g., college alumni associations) that 468 provide forwarding of incoming mail, but that do not operate a 469 mail submission agent for outgoing mail. 471 Periods are allowed in selectors and are component separators. When 472 keys are retrieved from the DNS, periods in selectors define DNS 473 label boundaries in a manner similar to the conventional use in 474 domain names. Selector components might be used to combine dates 475 with locations, for example, "march2005.reykjavik". In a DNS 476 implementation, this can be used to allow delegation of a portion of 477 the selector namespace. 479 ABNF: 481 selector = sub-domain *( "." sub-domain ) 483 The number of public keys and corresponding selectors for each domain 484 is determined by the domain owner. Many domain owners will be 485 satisfied with just one selector, whereas administratively 486 distributed organizations may choose to manage disparate selectors 487 and key pairs in different regions or on different email servers. 489 Beyond administrative convenience, selectors make it possible to 490 seamlessly replace public keys on a routine basis. If a domain 491 wishes to change from using a public key associated with selector 492 "january2005" to a public key associated with selector 493 "february2005", it merely makes sure that both public keys are 494 advertised in the public-key repository concurrently for the 495 transition period during which email may be in transit prior to 496 verification. At the start of the transition period, the outbound 497 email servers are configured to sign with the "february2005" private 498 key. At the end of the transition period, the "january2005" public 499 key is removed from the public-key repository. 501 INFORMATIVE NOTE: A key may also be revoked as described below. 502 The distinction between revoking and removing a key selector 503 record is subtle. When phasing out keys as described above, a 504 signing domain would probably simply remove the key record after 505 the transition period. However, a signing domain could elect to 506 revoke the key (but maintain the key record) for a further period. 507 There is no defined semantic difference between a revoked key and 508 a removed key. 510 While some domains may wish to make selector values well known, 511 others will want to take care not to allocate selector names in a way 512 that allows harvesting of data by outside parties. For example, if 513 per-user keys are issued, the domain owner will need to make the 514 decision as to whether to associate this selector directly with the 515 name of a registered end-user, or make it some unassociated random 516 value, such as a fingerprint of the public key. 518 INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key 519 (for example, changing the key associated with a user's name) 520 makes it impossible to tell the difference between a message that 521 didn't verify because the key is no longer valid versus a message 522 that is actually forged. For this reason, signers are ill-advised 523 to reuse selectors for new keys. A better strategy is to assign 524 new keys to new selectors. 526 3.2. Tag=Value Lists 528 DKIM uses a simple "tag=value" syntax in several contexts, including 529 in messages and domain signature records. 531 Values are a series of strings containing either plain text, "base64" 532 text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid, 533 Section 6.7), or "dkim-quoted-printable" (as defined in 534 Section 2.11). The name of the tag will determine the encoding of 535 each value. Unencoded semicolon (";") characters MUST NOT occur in 536 the tag value, since that separates tag-specs. 538 INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined 539 below (as "tag-value") only includes 7-bit characters, an 540 implementation that wished to anticipate future standards would be 541 advised not to preclude the use of UTF8-encoded text in tag=value 542 lists. 544 Formally, the ABNF syntax rules are as follows: 545 tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] 546 tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] 547 tag-name = ALPHA 0*ALNUMPUNC 548 tag-value = [ tval 0*( 1*(WSP / FWS) tval ) ] 549 ; Prohibits WSP and FWS at beginning and end 550 tval = 1*VALCHAR 551 VALCHAR = %x21-3A / %x3C-7E 552 ; EXCLAMATION to TILDE except SEMICOLON 553 ALNUMPUNC = ALPHA / DIGIT / "_" 555 Note that WSP is allowed anywhere around tags. In particular, any 556 WSP after the "=" and any WSP before the terminating ";" is not part 557 of the value; however, WSP inside the value is significant. 559 Tags MUST be interpreted in a case-sensitive manner. Values MUST be 560 processed as case sensitive unless the specific tag description of 561 semantics specifies case insensitivity. 563 Tags with duplicate names MUST NOT occur within a single tag-list; if 564 a tag name does occur more than once, the entire tag-list is invalid. 566 Whitespace within a value MUST be retained unless explicitly excluded 567 by the specific tag description. 569 Tag=value pairs that represent the default value MAY be included to 570 aid legibility. 572 Unrecognized tags MUST be ignored. 574 Tags that have an empty value are not the same as omitted tags. An 575 omitted tag is treated as having the default value; a tag with an 576 empty value explicitly designates the empty string as the value. 578 3.3. Signing and Verification Algorithms 580 DKIM supports multiple digital signature algorithms. Two algorithms 581 are defined by this specification at this time: rsa-sha1 and rsa- 582 sha256. Signers MUST implement and SHOULD sign using rsa-sha256. 583 Verifiers MUST implement both rsa-sha1 and rsa-sha256. 585 INFORMATIVE NOTE: Although rsa-sha256 is strongly encouraged, some 586 senders might prefer to use rsa-sha1 when balancing security 587 strength against performance, complexity, or other needs. In 588 general, however, rsa-sha256 should always be used whenever 589 possible. 591 3.3.1. The rsa-sha1 Signing Algorithm 593 The rsa-sha1 Signing Algorithm computes a message hash as described 594 in Section 3.7 below using SHA-1 [FIPS-180-3-2008] as the hash-alg. 595 That hash is then signed by the signer using the RSA algorithm 596 (defined in PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the 597 signer's private key. The hash MUST NOT be truncated or converted 598 into any form other than the native binary form before being signed. 599 The signing algorithm SHOULD use a public exponent of 65537. 601 3.3.2. The rsa-sha256 Signing Algorithm 603 The rsa-sha256 Signing Algorithm computes a message hash as described 604 in Section 3.7 below using SHA-256 [FIPS-180-3-2008] as the hash-alg. 605 That hash is then signed by the signer using the RSA algorithm 606 (defined in PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the 607 signer's private key. The hash MUST NOT be truncated or converted 608 into any form other than the native binary form before being signed. 609 The signing algorithm SHOULD use a public exponent of 65537. 611 3.3.3. Key Sizes 613 Selecting appropriate key sizes is a trade-off between cost, 614 performance, and risk. Since short RSA keys more easily succumb to 615 off-line attacks, signers MUST use RSA keys of at least 1024 bits for 616 long-lived keys. Verifiers MUST be able to validate signatures with 617 keys ranging from 512 bits to 2048 bits, and they MAY be able to 618 validate signatures with larger keys. Verifier policies may use the 619 length of the signing key as one metric for determining whether a 620 signature is acceptable. 622 Factors that should influence the key size choice include the 623 following: 625 o The practical constraint that large (e.g., 4096 bit) keys may not 626 fit within a 512-byte DNS UDP response packet 628 o The security constraint that keys smaller than 1024 bits are 629 subject to off-line attacks 631 o Larger keys impose higher CPU costs to verify and sign email 633 o Keys can be replaced on a regular basis, thus their lifetime can 634 be relatively short 636 o The security goals of this specification are modest compared to 637 typical goals of other systems that employ digital signatures 639 See [RFC3766] for further discussion on selecting key sizes. 641 3.3.4. Other Algorithms 643 Other algorithms MAY be defined in the future. Verifiers MUST ignore 644 any signatures using algorithms that they do not implement. 646 3.4. Canonicalization 648 Some mail systems modify email in transit, potentially invalidating a 649 signature. For most signers, mild modification of email is 650 immaterial to validation of the DKIM domain name's use. For such 651 signers, a canonicalization algorithm that survives modest in-transit 652 modification is preferred. 654 Other signers demand that any modification of the email, however 655 minor, result in a signature verification failure. These signers 656 prefer a canonicalization algorithm that does not tolerate in-transit 657 modification of the signed email. 659 Some signers may be willing to accept modifications to header fields 660 that are within the bounds of email standards such as [RFC5322], but 661 are unwilling to accept any modification to the body of messages. 663 To satisfy all requirements, two canonicalization algorithms are 664 defined for each of the header and the body: a "simple" algorithm 665 that tolerates almost no modification and a "relaxed" algorithm that 666 tolerates common modifications such as whitespace replacement and 667 header field line rewrapping. A signer MAY specify either algorithm 668 for header or body when signing an email. If no canonicalization 669 algorithm is specified by the signer, the "simple" algorithm defaults 670 for both header and body. Verifiers MUST implement both 671 canonicalization algorithms. Note that the header and body may use 672 different canonicalization algorithms. Further canonicalization 673 algorithms MAY be defined in the future; verifiers MUST ignore any 674 signatures that use unrecognized canonicalization algorithms. 676 Canonicalization simply prepares the email for presentation to the 677 signing or verification algorithm. It MUST NOT change the 678 transmitted data in any way. Canonicalization of header fields and 679 body are described below. 681 NOTE: This section assumes that the message is already in "network 682 normal" format (text is ASCII encoded, lines are separated with CRLF 683 characters, etc.). See also Section 5.3 for information about 684 normalizing the message. 686 3.4.1. The "simple" Header Canonicalization Algorithm 688 The "simple" header canonicalization algorithm does not change header 689 fields in any way. Header fields MUST be presented to the signing or 690 verification algorithm exactly as they are in the message being 691 signed or verified. In particular, header field names MUST NOT be 692 case folded and whitespace MUST NOT be changed. 694 3.4.2. The "relaxed" Header Canonicalization Algorithm 696 The "relaxed" header canonicalization algorithm MUST apply the 697 following steps in order: 699 o Convert all header field names (not the header field values) to 700 lowercase. For example, convert "SUBJect: AbC" to "subject: AbC". 702 o Unfold all header field continuation lines as described in 703 [RFC5322]; in particular, lines with terminators embedded in 704 continued header field values (that is, CRLF sequences followed by 705 WSP) MUST be interpreted without the CRLF. Implementations MUST 706 NOT remove the CRLF at the end of the header field value. 708 o Convert all sequences of one or more WSP characters to a single SP 709 character. WSP characters here include those before and after a 710 line folding boundary. 712 o Delete all WSP characters at the end of each unfolded header field 713 value. 715 o Delete any WSP characters remaining before and after the colon 716 separating the header field name from the header field value. The 717 colon separator MUST be retained. 719 3.4.3. The "simple" Body Canonicalization Algorithm 721 The "simple" body canonicalization algorithm ignores all empty lines 722 at the end of the message body. An empty line is a line of zero 723 length after removal of the line terminator. If there is no body or 724 no trailing CRLF on the message body, a CRLF is added. It makes no 725 other changes to the message body. In more formal terms, the 726 "simple" body canonicalization algorithm converts "0*CRLF" at the end 727 of the body to a single "CRLF". 729 Note that a completely empty or missing body is canonicalized as a 730 single "CRLF"; that is, the canonicalized length will be 2 octets. 732 The SHA-1 value (in base64) for an empty body (canonicalized to a 733 "CRLF") is: 734 uoq1oCgLlTqpdDX/iUbLy7J1Wic= 735 The SHA-256 value is: 736 frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN/XKdLCPjaYaY= 738 3.4.4. The "relaxed" Body Canonicalization Algorithm 740 The "relaxed" body canonicalization algorithm MUST apply the 741 following steps (a) and (b) in order: 743 a. Reduce whitespace: 745 * Ignore all whitespace at the end of lines. Implementations 746 MUST NOT remove the CRLF at the end of the line. 748 * Reduce all sequences of WSP within a line to a single SP 749 character. 751 b. Ignore all empty lines at the end of the message body. "Empty 752 line" is defined in Section 3.4.3. If the body is non-empty, but 753 does not end with a CRLF, a CRLF is added. (For email, this is 754 only possible when using extensions to SMTP or non-SMTP transport 755 mechanisms.) 757 The SHA-1 value (in base64) for an empty body (canonicalized to a 758 null input) is: 759 2jmj7l5rSw0yVb/vlWAYkK/YBwk= 760 The SHA-256 value is: 761 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 762 INFORMATIVE NOTE: It should be noted that the relaxed body 763 canonicalization algorithm may enable certain types of extremely 764 crude "ASCII Art" attacks where a message may be conveyed by 765 adjusting the spacing between words. If this is a concern, the 766 "simple" body canonicalization algorithm should be used instead. 768 3.4.5. Body Length Limits 770 A body length count MAY be specified to limit the signature 771 calculation to an initial prefix of the body text, measured in 772 octets. If the body length count is not specified, the entire 773 message body is signed. 775 INFORMATIVE RATIONALE: This capability is provided because it is 776 very common for mailing lists to add trailers to messages (e.g., 777 instructions how to get off the list). Until those messages are 778 also signed, the body length count is a useful tool for the 779 verifier since it may as a matter of policy accept messages having 780 valid signatures with extraneous data. 782 INFORMATIVE IMPLEMENTATION NOTE: Using body length limits enables 783 an attack in which an attacker modifies a message to include 784 content that solely benefits the attacker. It is possible for the 785 appended content to completely replace the original content in the 786 end recipient's eyes, such as via alterations to the MIME 787 structure or exploiting lax HTML parsing in the MUA, and to defeat 788 duplicate message detection algorithms. To avoid this attack, 789 signers should be wary of using this tag, and verifiers might wish 790 to ignore the tag, perhaps based on other criteria. 792 The body length count allows the signer of a message to permit data 793 to be appended to the end of the body of a signed message. The body 794 length count MUST be calculated following the canonicalization 795 algorithm; for example, any whitespace ignored by a canonicalization 796 algorithm is not included as part of the body length count. 798 A body length count of zero means that the body is completely 799 unsigned. 801 Signers wishing to ensure that no modification of any sort can occur 802 should specify the "simple" canonicalization algorithm for both 803 header and body and omit the body length count. 805 3.4.6. Canonicalization Examples (INFORMATIVE) 807 In the following examples, actual whitespace is used only for 808 clarity. The actual input and output text is designated using 809 bracketed descriptors: "" for a space character, "" for a 810 tab character, and "" for a carriage-return/line-feed sequence. 811 For example, "X Y" and "XY" represent the same three 812 characters. 814 Example 1: A message reading: 815 A: X 816 B : Y 817 Z 818 819 C 820 D E 821 822 824 when canonicalized using relaxed canonicalization for both header and 825 body results in a header reading: 826 a:X 827 b:Y Z 829 and a body reading: 830 C 831 D E 833 Example 2: The same message canonicalized using simple 834 canonicalization for both header and body results in a header 835 reading: 836 A: X 837 B : Y 838 Z 840 and a body reading: 841 C 842 D E 844 Example 3: When processed using relaxed header canonicalization and 845 simple body canonicalization, the canonicalized version has a header 846 of: 847 a:X 848 b:Y Z 850 and a body reading: 851 C 852 D E 854 3.5. The DKIM-Signature Header Field 856 The signature of the email is stored in the DKIM-Signature header 857 field. This header field contains all of the signature and key- 858 fetching data. The DKIM-Signature value is a tag-list as described 859 in Section 3.2. 861 The DKIM-Signature header field SHOULD be treated as though it were a 862 trace header field as defined in Section 3.6 of [RFC5322], and hence 863 SHOULD NOT be reordered and SHOULD be prepended to the message. 865 The DKIM-Signature header field being created or verified is always 866 included in the signature calculation, after the rest of the header 867 fields being signed; however, when calculating or verifying the 868 signature, the value of the "b=" tag (signature value) of that DKIM- 869 Signature header field MUST be treated as though it were an empty 870 string. Unknown tags in the DKIM-Signature header field MUST be 871 included in the signature calculation but MUST be otherwise ignored 872 by verifiers. Other DKIM-Signature header fields that are included 873 in the signature should be treated as normal header fields; in 874 particular, the "b=" tag is not treated specially. 876 The encodings for each field type are listed below. Tags described 877 as qp-section are encoded as described in Section 6.7 of MIME Part 878 One [RFC2045], with the additional conversion of semicolon characters 879 to "=3B"; intuitively, this is one line of quoted-printable encoded 880 text. The dkim-quoted-printable syntax is defined in Section 2.11. 882 Tags on the DKIM-Signature header field along with their type and 883 requirement status are shown below. Unrecognized tags MUST be 884 ignored. 886 v= Version (MUST be included). This tag defines the version of this 887 specification that applies to the signature record. It MUST have 888 the value "1". Note that verifiers must do a string comparison on 889 this value; for example, "1" is not the same as "1.0". 891 ABNF: 893 sig-v-tag = %x76 [FWS] "=" [FWS] "1" 895 INFORMATIVE NOTE: DKIM-Signature version numbers are expected 896 to increase arithmetically as new versions of this 897 specification are released. 899 a= The algorithm used to generate the signature (plain-text; 900 REQUIRED). Verifiers MUST support "rsa-sha1" and "rsa-sha256"; 901 signers SHOULD sign using "rsa-sha256". See Section 3.3 for a 902 description of the algorithms. 904 ABNF: 906 sig-a-tag = %x61 [FWS] "=" [FWS] sig-a-tag-alg 907 sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h 908 sig-a-tag-k = "rsa" / x-sig-a-tag-k 909 sig-a-tag-h = "sha1" / "sha256" / x-sig-a-tag-h 910 x-sig-a-tag-k = ALPHA *(ALPHA / DIGIT) 911 ; for later extension 912 x-sig-a-tag-h = ALPHA *(ALPHA / DIGIT) 913 ; for later extension 915 b= The signature data (base64; REQUIRED). Whitespace is ignored in 916 this value and MUST be ignored when reassembling the original 917 signature. In particular, the signing process can safely insert 918 FWS in this value in arbitrary places to conform to line-length 919 limits. See Signer Actions (Section 5) for how the signature is 920 computed. 922 ABNF: 924 sig-b-tag = %x62 [FWS] "=" [FWS] sig-b-tag-data 925 sig-b-tag-data = base64string 927 bh= The hash of the canonicalized body part of the message as 928 limited by the "l=" tag (base64; REQUIRED). Whitespace is ignored 929 in this value and MUST be ignored when reassembling the original 930 signature. In particular, the signing process can safely insert 931 FWS in this value in arbitrary places to conform to line-length 932 limits. See Section 3.7 for how the body hash is computed. 934 ABNF: 936 sig-bh-tag = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data 937 sig-bh-tag-data = base64string 939 c= Message canonicalization (plain-text; OPTIONAL, default is 940 "simple/simple"). This tag informs the verifier of the type of 941 canonicalization used to prepare the message for signing. It 942 consists of two names separated by a "slash" (%d47) character, 943 corresponding to the header and body canonicalization algorithms 944 respectively. These algorithms are described in Section 3.4. If 945 only one algorithm is named, that algorithm is used for the header 946 and "simple" is used for the body. For example, "c=relaxed" is 947 treated the same as "c=relaxed/simple". 949 ABNF: 951 sig-c-tag = %x63 [FWS] "=" [FWS] sig-c-tag-alg 952 ["/" sig-c-tag-alg] 953 sig-c-tag-alg = "simple" / "relaxed" / x-sig-c-tag-alg 954 x-sig-c-tag-alg = hyphenated-word ; for later extension 956 d= The SDID claiming responsibility for an introduction of a message 957 into the mail stream (plain-text; REQUIRED). Hence, the SDID 958 value is used to form the query for the public key. The SDID MUST 959 correspond to a valid DNS name under which the DKIM key record is 960 published. The conventions and semantics used by a signer to 961 create and use a specific SDID are outside the scope of the DKIM 962 Signing specification, as is any use of those conventions and 963 semantics. When presented with a signature that does not meet 964 these requirements, verifiers MUST consider the signature invalid. 966 Internationalized domain names MUST be encoded as A-Labels, as 967 described in Section 2.3 of [RFC5890]. 969 ABNF: 971 sig-d-tag = %x64 [FWS] "=" [FWS] domain-name 972 domain-name = sub-domain 1*("." sub-domain) 973 ; from RFC5321 Domain, excluding address-literal 975 h= Signed header fields (plain-text, but see description; REQUIRED). 976 A colon-separated list of header field names that identify the 977 header fields presented to the signing algorithm. The field MUST 978 contain the complete list of header fields in the order presented 979 to the signing algorithm. The field MAY contain names of header 980 fields that do not exist when signed; nonexistent header fields do 981 not contribute to the signature computation (that is, they are 982 treated as the null input, including the header field name, the 983 separating colon, the header field value, and any CRLF 984 terminator). The field MUST NOT include the DKIM-Signature header 985 field that is being created or verified, but may include others. 986 Folding whitespace (FWS) MAY be included on either side of the 987 colon separator. Header field names MUST be compared against 988 actual header field names in a case-insensitive manner. This list 989 MUST NOT be empty. See Section 5.4 for a discussion of choosing 990 header fields to sign. 992 ABNF: 994 sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name 995 0*( [FWS] ":" [FWS] hdr-name ) 997 INFORMATIVE EXPLANATION: By "signing" header fields that do not 998 actually exist, a signer can prevent insertion of those header 999 fields before verification. However, since a signer cannot 1000 possibly know what header fields might be created in the 1001 future, and that some MUAs might present header fields that are 1002 embedded inside a message (e.g., as a message/rfc822 content 1003 type), the security of this solution is not total. 1005 INFORMATIVE EXPLANATION: The exclusion of the header field name 1006 and colon as well as the header field value for non-existent 1007 header fields prevents an attacker from inserting an actual 1008 header field with a null value. 1010 i= The Agent or User Identifier (AUID) on behalf of which the SDID is 1011 taking responsibility (dkim-quoted-printable; OPTIONAL, default is 1012 an empty Local-part followed by an "@" followed by the domain from 1013 the "d=" tag). 1015 The syntax is a standard email address where the Local-part MAY be 1016 omitted. The domain part of the address MUST be the same as, or a 1017 subdomain of, the value of the "d=" tag. 1019 Internationalized domain names MUST be encoded as A-Labels, as 1020 described in Section 2.3 of [RFC5890]. 1022 ABNF: 1024 sig-i-tag = %x69 [FWS] "=" [FWS] [ Local-part ] 1025 "@" domain-name 1027 The AUID is specified as having the same syntax as an email 1028 address, but need not have the same semantics. Notably, the 1029 domain name is need not be registered in the DNS -- so it might 1030 not resolve in a query -- and the Local-part MAY be drawn from a 1031 namespace unrelated to any mailbox. The details of the structure 1032 and semantics for the namespace are determined by the Signer. Any 1033 knowledge or use of those details by verifiers or assessors is 1034 outside the scope of the DKIM Signing specification. The Signer 1035 MAY choose to use the same namespace for its AUIDs as its users' 1036 email addresses or MAY choose other means of representing its 1037 users. However, the signer SHOULD use the same AUID for each 1038 message intended to be evaluated as being within the same sphere 1039 of responsibility, if it wishes to offer receivers the option of 1040 using the AUID as a stable identifier that is finer grained than 1041 the SDID. 1043 INFORMATIVE NOTE: The Local-part of the "i=" tag is optional 1044 because in some cases a signer may not be able to establish a 1045 verified individual identity. In such cases, the signer might 1046 wish to assert that although it is willing to go as far as 1047 signing for the domain, it is unable or unwilling to commit to 1048 an individual user name within their domain. It can do so by 1049 including the domain part but not the Local-part of the 1050 identity. 1052 INFORMATIVE DISCUSSION: This specification does not require the 1053 value of the "i=" tag to match the identity in any message 1054 header fields. This is considered to be a verifier policy 1055 issue. Constraints between the value of the "i=" tag and other 1056 identities in other header fields seek to apply basic 1057 authentication into the semantics of trust associated with a 1058 role such as content author. Trust is a broad and complex 1059 topic and trust mechanisms are subject to highly creative 1060 attacks. The real-world efficacy of any but the most basic 1061 bindings between the "i=" value and other identities is not 1062 well established, nor is its vulnerability to subversion by an 1063 attacker. Hence reliance on the use of these options should be 1064 strictly limited. In particular, it is not at all clear to 1065 what extent a typical end-user recipient can rely on any 1066 assurances that might be made by successful use of the "i=" 1067 options. 1069 l= Body length count (plain-text unsigned decimal integer; OPTIONAL, 1070 default is entire body). This tag informs the verifier of the 1071 number of octets in the body of the email after canonicalization 1072 included in the cryptographic hash, starting from 0 immediately 1073 following the CRLF preceding the body. This value MUST NOT be 1074 larger than the actual number of octets in the canonicalized 1075 message body. 1077 INFORMATIVE IMPLEMENTATION WARNING: Use of the "l=" tag might 1078 allow display of fraudulent content without appropriate warning 1079 to end users. The "l=" tag is intended for increasing 1080 signature robustness when sending to mailing lists that both 1081 modify their content and do not sign their messages. However, 1082 using the "l=" tag enables attacks in which an intermediary 1083 with malicious intent modifies a message to include content 1084 that solely benefits the attacker. It is possible for the 1085 appended content to completely replace the original content in 1086 the end recipient's eyes and to defeat duplicate message 1087 detection algorithms. Examples are described in Security 1088 Considerations (Section 8). To avoid this attack, signers 1089 should be extremely wary of using this tag, and assessors might 1090 wish to ignore signatures that use the tag. 1092 INFORMATIVE NOTE: The value of the "l=" tag is constrained to 1093 76 decimal digits. This constraint is not intended to predict 1094 the size of future messages or to require implementations to 1095 use an integer representation large enough to represent the 1096 maximum possible value, but is intended to remind the 1097 implementer to check the length of this and all other tags 1098 during verification and to test for integer overflow when 1099 decoding the value. Implementers may need to limit the actual 1100 value expressed to a value smaller than 10^76, e.g., to allow a 1101 message to fit within the available storage space. 1103 ABNF: 1105 sig-l-tag = %x6c [FWS] "=" [FWS] 1106 1*76DIGIT 1108 q= A colon-separated list of query methods used to retrieve the 1109 public key (plain-text; OPTIONAL, default is "dns/txt"). Each 1110 query method is of the form "type[/options]", where the syntax and 1111 semantics of the options depend on the type and specified options. 1112 If there are multiple query mechanisms listed, the choice of query 1113 mechanism MUST NOT change the interpretation of the signature. 1114 Implementations MUST use the recognized query mechanisms in the 1115 order presented. Unrecognized query mechanisms MUST be ignored. 1117 Currently, the only valid value is "dns/txt", which defines the 1118 DNS TXT record lookup algorithm described elsewhere in this 1119 document. The only option defined for the "dns" query type is 1120 "txt", which MUST be included. Verifiers and signers MUST support 1121 "dns/txt". 1123 ABNF: 1125 sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 1126 *([FWS] ":" [FWS] sig-q-tag-method) 1127 sig-q-tag-method = "dns/txt" / x-sig-q-tag-type 1128 ["/" x-sig-q-tag-args] 1129 x-sig-q-tag-type = hyphenated-word ; for future extension 1130 x-sig-q-tag-args = qp-hdr-value 1132 s= The selector subdividing the namespace for the "d=" (domain) tag 1133 (plain-text; REQUIRED). 1135 Internationalized selector names MUST be encoded as A-Labels, as 1136 described in Section 2.3 of [RFC5890]. 1138 ABNF: 1140 sig-s-tag = %x73 [FWS] "=" [FWS] selector 1142 t= Signature Timestamp (plain-text unsigned decimal integer; 1143 RECOMMENDED, default is an unknown creation time). The time that 1144 this signature was created. The format is the number of seconds 1145 since 00:00:00 on January 1, 1970 in the UTC time zone. The value 1146 is expressed as an unsigned integer in decimal ASCII. This value 1147 is not constrained to fit into a 31- or 32-bit integer. 1148 Implementations SHOULD be prepared to handle values up to at least 1149 10^12 (until approximately AD 200,000; this fits into 40 bits). 1150 To avoid denial-of-service attacks, implementations MAY consider 1151 any value longer than 12 digits to be infinite. Leap seconds are 1152 not counted. Implementations MAY ignore signatures that have a 1153 timestamp in the future. 1155 ABNF: 1157 sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT 1159 x= Signature Expiration (plain-text unsigned decimal integer; 1160 RECOMMENDED, default is no expiration). The format is the same as 1161 in the "t=" tag, represented as an absolute date, not as a time 1162 delta from the signing timestamp. The value is expressed as an 1163 unsigned integer in decimal ASCII, with the same constraints on 1164 the value in the "t=" tag. Signatures MAY be considered invalid 1165 if the verification time at the verifier is past the expiration 1166 date. The verification time should be the time that the message 1167 was first received at the administrative domain of the verifier if 1168 that time is reliably available; otherwise the current time should 1169 be used. The value of the "x=" tag MUST be greater than the value 1170 of the "t=" tag if both are present. 1172 INFORMATIVE NOTE: The "x=" tag is not intended as an anti- 1173 replay defense. 1175 INFORMATIVE NOTE: Due to clock drift, the receiver's notion of 1176 when to consider the signature expired may not match exactly 1177 when the sender is expecting. Receivers MAY add a 'fudge 1178 factor' to allow for such possible drift. 1180 ABNF: 1182 sig-x-tag = %x78 [FWS] "=" [FWS] 1183 1*12DIGIT 1185 z= Copied header fields (dkim-quoted-printable, but see description; 1186 OPTIONAL, default is null). A vertical-bar-separated list of 1187 selected header fields present when the message was signed, 1188 including both the field name and value. It is not required to 1189 include all header fields present at the time of signing. This 1190 field need not contain the same header fields listed in the "h=" 1191 tag. The header field text itself must encode the vertical bar 1192 ("|", %x7C) character (i.e., vertical bars in the "z=" text are 1193 meta-characters, and any actual vertical bar characters in a 1194 copied header field must be encoded). Note that all whitespace 1195 must be encoded, including whitespace between the colon and the 1196 header field value. After encoding, FWS MAY be added at arbitrary 1197 locations in order to avoid excessively long lines; such 1198 whitespace is NOT part of the value of the header field, and MUST 1199 be removed before decoding. 1201 The header fields referenced by the "h=" tag refer to the fields 1202 in the [RFC5322] header of the message, not to any copied fields 1203 in the "z=" tag. Copied header field values are for diagnostic 1204 use. 1206 ABNF: 1208 sig-z-tag = %x7A [FWS] "=" [FWS] sig-z-tag-copy 1209 *( "|" [FWS] sig-z-tag-copy ) 1210 sig-z-tag-copy = hdr-name [FWS] ":" qp-hdr-value 1211 INFORMATIVE EXAMPLE of a signature header field spread across 1212 multiple continuation lines: 1213 DKIM-Signature: v=1; a=rsa-sha256; d=example.net; s=brisbane; 1214 c=simple; q=dns/txt; i=@eng.example.net; 1215 t=1117574938; x=1118006938; 1216 h=from:to:subject:date; 1217 z=From:foo@eng.example.net|To:joe@example.com| 1218 Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700; 1219 bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=; 1220 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZVoG4ZHRNiYzR 1222 3.6. Key Management and Representation 1224 Signature applications require some level of assurance that the 1225 verification public key is associated with the claimed signer. Many 1226 applications achieve this by using public key certificates issued by 1227 a trusted third party. However, DKIM can achieve a sufficient level 1228 of security, with significantly enhanced scalability, by simply 1229 having the verifier query the purported signer's DNS entry (or some 1230 security-equivalent) in order to retrieve the public key. 1232 DKIM keys can potentially be stored in multiple types of key servers 1233 and in multiple formats. The storage and format of keys are 1234 irrelevant to the remainder of the DKIM algorithm. 1236 Parameters to the key lookup algorithm are the type of the lookup 1237 (the "q=" tag), the domain of the signer (the "d=" tag of the DKIM- 1238 Signature header field), and the selector (the "s=" tag). 1240 public_key = dkim_find_key(q_val, d_val, s_val) 1242 This document defines a single binding, using DNS TXT records to 1243 distribute the keys. Other bindings may be defined in the future. 1245 3.6.1. Textual Representation 1247 It is expected that many key servers will choose to present the keys 1248 in an otherwise unstructured text format (for example, an XML form 1249 would not be considered to be unstructured text for this purpose). 1250 The following definition MUST be used for any DKIM key represented in 1251 an otherwise unstructured textual form. 1253 The overall syntax is a tag-list as described in Section 3.2. The 1254 current valid tags are described below. Other tags MAY be present 1255 and MUST be ignored by any implementation that does not understand 1256 them. 1258 v= Version of the DKIM key record (plain-text; RECOMMENDED, default 1259 is "DKIM1"). If specified, this tag MUST be set to "DKIM1" 1260 (without the quotes). This tag MUST be the first tag in the 1261 record. Records beginning with a "v=" tag with any other value 1262 MUST be discarded. Note that verifiers must do a string 1263 comparison on this value; for example, "DKIM1" is not the same as 1264 "DKIM1.0". 1266 ABNF: 1267 key-v-tag = %x76 [FWS] "=" [FWS] %x44.4B.49.4D.31 1269 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to 1270 allowing all algorithms). A colon-separated list of hash 1271 algorithms that might be used. Unrecognized algorithms MUST be 1272 ignored. Refer to Section 3.3 for a discussion of the hash 1273 algorithms implemented by Signers and Verifiers. The set of 1274 algorithms listed in this tag in each record is an operational 1275 choice made by the Signer. 1277 ABNF: 1279 key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg 1280 0*( [FWS] ":" [FWS] key-h-tag-alg ) 1281 key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg 1282 x-key-h-tag-alg = hyphenated-word ; for future extension 1284 k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and 1285 verifiers MUST support the "rsa" key type. The "rsa" key type 1286 indicates that an ASN.1 DER-encoded [ITU-X660-1997] RSAPublicKey 1287 [RFC3447] (see Sections Section 3.1 and A.1.1) is being used in 1288 the "p=" tag. (Note: the "p=" tag further encodes the value using 1289 the base64 algorithm.) Unrecognized key types MUST be ignored. 1291 ABNF: 1293 key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type 1294 key-k-tag-type = "rsa" / x-key-k-tag-type 1295 x-key-k-tag-type = hyphenated-word ; for future extension 1296 n= Notes that might be of interest to a human (qp-section; OPTIONAL, 1297 default is empty). No interpretation is made by any program. 1298 This tag should be used sparingly in any key server mechanism that 1299 has space limitations (notably DNS). This is intended for use by 1300 administrators, not end users. 1302 ABNF: 1304 key-n-tag = %x6e [FWS] "=" [FWS] qp-section 1306 p= Public-key data (base64; REQUIRED). An empty value means that 1307 this public key has been revoked. The syntax and semantics of 1308 this tag value before being encoded in base64 are defined by the 1309 "k=" tag. 1311 INFORMATIVE RATIONALE: If a private key has been compromised or 1312 otherwise disabled (e.g., an outsourcing contract has been 1313 terminated), a signer might want to explicitly state that it 1314 knows about the selector, but all messages using that selector 1315 should fail verification. Verifiers SHOULD return an error 1316 code for any DKIM-Signature header field with a selector 1317 referencing a revoked key. (See Section 6.1.2 for details.) 1319 ABNF: 1321 key-p-tag = %x70 [FWS] "=" [ [FWS] base64string] 1323 INFORMATIVE NOTE: A base64string is permitted to include white 1324 space (FWS) at arbitrary places; however, any CRLFs must be 1325 followed by at least one WSP character. Implementors and 1326 administrators are cautioned to ensure that selector TXT 1327 records conform to this specification. 1329 s= Service Type (plain-text; OPTIONAL; default is "*"). A colon- 1330 separated list of service types to which this record applies. 1331 Verifiers for a given service type MUST ignore this record if the 1332 appropriate type is not listed. Unrecognized service types MUST 1333 be ignored. Currently defined service types are as follows: 1335 * matches all service types 1337 email electronic mail (not necessarily limited to SMTP) 1339 This tag is intended to constrain the use of keys for other 1340 purposes, should use of DKIM be defined by other services in the 1341 future. 1343 ABNF: 1345 key-s-tag = %x73 [FWS] "=" [FWS] key-s-tag-type 1346 0*( [FWS] ":" [FWS] key-s-tag-type ) 1347 key-s-tag-type = "email" / "*" / x-key-s-tag-type 1348 x-key-s-tag-type = hyphenated-word ; for future extension 1350 t= Flags, represented as a colon-separated list of names (plain- 1351 text; OPTIONAL, default is no flags set). Unrecognized flags MUST 1352 be ignored. The defined flags are as follows: 1354 y This domain is testing DKIM. Verifiers MUST NOT treat messages 1355 from signers in testing mode differently from unsigned email, even 1356 should the signature fail to verify. Verifiers MAY wish to track 1357 testing mode results to assist the signer. 1359 s Any DKIM-Signature header fields using the "i=" tag MUST have the 1360 same domain value on the right-hand side of the "@" in the "i=" 1361 tag and the value of the "d=" tag. That is, the "i=" domain MUST 1362 NOT be a subdomain of "d=". Use of this flag is RECOMMENDED 1363 unless subdomaining is required. 1365 ABNF: 1367 key-t-tag = %x74 [FWS] "=" [FWS] key-t-tag-flag 1368 0*( [FWS] ":" [FWS] key-t-tag-flag ) 1369 key-t-tag-flag = "y" / "s" / x-key-t-tag-flag 1370 x-key-t-tag-flag = hyphenated-word ; for future extension 1372 3.6.2. DNS Binding 1374 A binding using DNS TXT records as a key service is hereby defined. 1375 All implementations MUST support this binding. 1377 3.6.2.1. Namespace 1379 All DKIM keys are stored in a subdomain named "_domainkey". Given a 1380 DKIM-Signature field with a "d=" tag of "example.com" and an "s=" tag 1381 of "foo.bar", the DNS query will be for 1382 "foo.bar._domainkey.example.com". 1384 3.6.2.2. Resource Record Types for Key Storage 1386 The DNS Resource Record type used is specified by an option to the 1387 query-type ("q=") tag. The only option defined in this base 1388 specification is "txt", indicating the use of a TXT Resource Record 1389 (RR). A later extension of this standard may define another RR type. 1391 Strings in a TXT RR MUST be concatenated together before use with no 1392 intervening whitespace. TXT RRs MUST be unique for a particular 1393 selector name; that is, if there are multiple records in an RRset, 1394 the results are undefined. 1396 TXT RRs are encoded as described in Section 3.6.1. 1398 3.7. Computing the Message Hashes 1400 Both signing and verifying message signatures start with a step of 1401 computing two cryptographic hashes over the message. Signers will 1402 choose the parameters of the signature as described in Signer Actions 1403 (Section 5); verifiers will use the parameters specified in the DKIM- 1404 Signature header field being verified. In the following discussion, 1405 the names of the tags in the DKIM-Signature header field that either 1406 exists (when verifying) or will be created (when signing) are used. 1407 Note that canonicalization (Section 3.4) is only used to prepare the 1408 email for signing or verifying; it does not affect the transmitted 1409 email in any way. 1411 The signer/verifier MUST compute two hashes, one over the body of the 1412 message and one over the selected header fields of the message. 1414 Signers MUST compute them in the order shown. Verifiers MAY compute 1415 them in any order convenient to the verifier, provided that the 1416 result is semantically identical to the semantics that would be the 1417 case had they been computed in this order. 1419 In hash step 1, the signer/verifier MUST hash the message body, 1420 canonicalized using the body canonicalization algorithm specified in 1421 the "c=" tag and then truncated to the length specified in the "l=" 1422 tag. That hash value is then converted to base64 form and inserted 1423 into (signers) or compared to (verifiers) the "bh=" tag of the DKIM- 1424 Signature header field. 1426 In hash step 2, the signer/verifier MUST pass the following to the 1427 hash algorithm in the indicated order. 1429 1. The header fields specified by the "h=" tag, in the order 1430 specified in that tag, and canonicalized using the header 1431 canonicalization algorithm specified in the "c=" tag. Each 1432 header field MUST be terminated with a single CRLF. 1434 2. The DKIM-Signature header field that exists (verifying) or will 1435 be inserted (signing) in the message, with the value of the "b=" 1436 tag (including all surrounding whitespace) deleted (i.e., treated 1437 as the empty string), canonicalized using the header 1438 canonicalization algorithm specified in the "c=" tag, and without 1439 a trailing CRLF. 1441 All tags and their values in the DKIM-Signature header field are 1442 included in the cryptographic hash with the sole exception of the 1443 value portion of the "b=" (signature) tag, which MUST be treated as 1444 the null string. All tags MUST be included even if they might not be 1445 understood by the verifier. The header field MUST be presented to 1446 the hash algorithm after the body of the message rather than with the 1447 rest of the header fields and MUST be canonicalized as specified in 1448 the "c=" (canonicalization) tag. The DKIM-Signature header field 1449 MUST NOT be included in its own h= tag, although other DKIM-Signature 1450 header fields MAY be signed (see Section 4). 1452 When calculating the hash on messages that will be transmitted using 1453 base64 or quoted-printable encoding, signers MUST compute the hash 1454 after the encoding. Likewise, the verifier MUST incorporate the 1455 values into the hash before decoding the base64 or quoted-printable 1456 text. However, the hash MUST be computed before transport level 1457 encodings such as SMTP "dot-stuffing" (the modification of lines 1458 beginning with a "." to avoid confusion with the SMTP end-of-message 1459 marker, as specified in [RFC5321]). 1461 With the exception of the canonicalization procedure described in 1462 Section 3.4, the DKIM signing process treats the body of messages as 1463 simply a string of octets. DKIM messages MAY be either in plain-text 1464 or in MIME format; no special treatment is afforded to MIME content. 1465 Message attachments in MIME format MUST be included in the content 1466 that is signed. 1468 More formally, pseudo-code for the signature algorithm is: 1469 body-hash = hash-alg (canon-body, l-param) 1470 data-hash = hash-alg (h-headers, D-SIG, content-hash) 1471 signature = sig-alg (d-domain, selector, data-hash) 1473 where: 1475 body-hash: is the output from hashing the body, using hash-alg. 1477 hash-alg: is the hashing algorithm specified in the "a" 1478 parameter. 1480 canon-body: is a canonicalized representation of the body, 1481 produced by using the body algorithm specified in the "c" 1482 parameter, as defined in Section 3.4 and excluding the 1483 DKIM-Signature field. 1485 l-param: is the length-of-body value of the "l" parameter. 1487 data-hash: is the output from using the hash-alg algorithm, to 1488 hash the header including the DKIM-Signature header, and the 1489 body hash. 1491 h-headers: is the list of headers to be signed, as specified in 1492 the "h" parameter. 1494 D-SIG: is the canonicalized DKIM-Signature field without the 1495 signature value portion of the parameter, itself; that is, an 1496 empty parameter value. 1498 signature: is the signature value produced by the signing 1499 algorithm. 1501 sig-alg: is the signature algorithm specified by the "a" 1502 parameter. 1504 d-domain: is the domain name specified in the "d" parameter. 1506 selector: is the selector value specified in the "s" parameter. 1508 NOTE: Many digital signature APIs provide both hashing and 1509 application of the RSA private key using a single "sign()" 1510 primitive. When using such an API, the last two steps in the 1511 algorithm would probably be combined into a single call that would 1512 perform both the "a-hash-alg" and the "sig-alg". 1514 3.8. Input Requirements 1516 DKIM's design is predicated on valid input. Therefore, signers and 1517 verifiers SHOULD take reasonable steps to ensure that the messages 1518 they are processing are valid according to [RFC5322], [RFC2045], and 1519 any other relevant message format standards. See Section 8.14 and 1520 Section 8.15 for additional discussion and references. 1522 3.9. Output Requirements 1524 For each signature that verifies successfully or produces a TEMPFAIL 1525 result, the output of a DKIM verifier module MUST include the set of: 1527 o The domain name, taken from the "d=" signature tag; and 1529 o The result of the verification attempt for that signature. 1531 The output MAY include other signature properties or result meta- 1532 data, including PERMFAILed or otherwise ignored signatures, for use 1533 by modules that consume those results. 1535 See Section 6.1 for discussion of signature validation result codes. 1537 3.10. Signing by Parent Domains 1539 In some circumstances, it is desirable for a domain to apply a 1540 signature on behalf of any of its subdomains without the need to 1541 maintain separate selectors (key records) in each subdomain. By 1542 default, private keys corresponding to key records can be used to 1543 sign messages for any subdomain of the domain in which they reside; 1544 for example, a key record for the domain example.com can be used to 1545 verify messages where the AUID ("i=" tag of the signature) is 1546 sub.example.com, or even sub1.sub2.example.com. In order to limit 1547 the capability of such keys when this is not intended, the "s" flag 1548 MAY be set in the "t=" tag of the key record, to constrain the 1549 validity of the domain of the AUID. If the referenced key record 1550 contains the "s" flag as part of the "t=" tag, the domain of the AUID 1551 ("i=" flag) MUST be the same as that of the SDID (d=) domain. If 1552 this flag is absent, the domain of the AUID MUST be the same as, or a 1553 subdomain of, the SDID. 1555 3.11. Relationship between SDID and AUID 1557 DKIM's primary task is to communicate from the Signer to a recipient- 1558 side Identity Assessor a single Signing Domain Identifier (SDID) that 1559 refers to a responsible identity. DKIM MAY optionally provide a 1560 single responsible Agent or User Identifier (AUID). 1562 Hence, DKIM's mandatory output to a receive-side Identity Assessor is 1563 a single domain name. Within the scope of its use as DKIM output, 1564 the name has only basic domain name semantics; any possible owner- 1565 specific semantics are outside the scope of DKIM. That is, within 1566 its role as a DKIM identifier, additional semantics cannot be assumed 1567 by an Identity Assessor. 1569 Upon successfully verifying the signature, a receive-side DKIM 1570 verifier MUST communicate the Signing Domain Identifier (d=) to a 1571 consuming Identity Assessor module and MAY communicate the Agent or 1572 User Identifier (i=) if present. 1574 To the extent that a receiver attempts to intuit any structured 1575 semantics for either of the identifiers, this is a heuristic function 1576 that is outside the scope of DKIM's specification and semantics. 1577 Hence, it is relegated to a higher-level service, such as a delivery 1578 handling filter that integrates a variety of inputs and performs 1579 heuristic analysis of them. 1581 INFORMATIVE DISCUSSION: This document does not require the value 1582 of the SDID or AUID to match an identifier in any other message 1583 header field. This requirement is, instead, an assessor policy 1584 issue. The purpose of such a linkage would be to authenticate the 1585 value in that other header field. This, in turn, is the basis for 1586 applying a trust assessment based on the identifier value. Trust 1587 is a broad and complex topic and trust mechanisms are subject to 1588 highly creative attacks. The real-world efficacy of any but the 1589 most basic bindings between the SDID or AUID and other identities 1590 is not well established, nor is its vulnerability to subversion by 1591 an attacker. Hence, reliance on the use of such bindings should 1592 be strictly limited. In particular, it is not at all clear to 1593 what extent a typical end-user recipient can rely on any 1594 assurances that might be made by successful use of the SDID or 1595 AUID. 1597 4. Semantics of Multiple Signatures 1599 4.1. Example Scenarios 1601 There are many reasons why a message might have multiple signatures. 1602 For example, a given signer might sign multiple times, perhaps with 1603 different hashing or signing algorithms during a transition phase. 1605 INFORMATIVE EXAMPLE: Suppose SHA-256 is in the future found to be 1606 insufficiently strong, and DKIM usage transitions to SHA-1024. A 1607 signer might immediately sign using the newer algorithm, but 1608 continue to sign using the older algorithm for interoperability 1609 with verifiers that had not yet upgraded. The signer would do 1610 this by adding two DKIM-Signature header fields, one using each 1611 algorithm. Older verifiers that did not recognize SHA-1024 as an 1612 acceptable algorithm would skip that signature and use the older 1613 algorithm; newer verifiers could use either signature at their 1614 option, and all other things being equal might not even attempt to 1615 verify the other signature. 1617 Similarly, a signer might sign a message including all headers and no 1618 "l=" tag (to satisfy strict verifiers) and a second time with a 1619 limited set of headers and an "l=" tag (in anticipation of possible 1620 message modifications in route to other verifiers). Verifiers could 1621 then choose which signature they preferred. 1623 INFORMATIVE EXAMPLE: A verifier might receive a message with two 1624 signatures, one covering more of the message than the other. If 1625 the signature covering more of the message verified, then the 1626 verifier could make one set of policy decisions; if that signature 1627 failed but the signature covering less of the message verified, 1628 the verifier might make a different set of policy decisions. 1630 Of course, a message might also have multiple signatures because it 1631 passed through multiple signers. A common case is expected to be 1632 that of a signed message that passes through a mailing list that also 1633 signs all messages. Assuming both of those signatures verify, a 1634 recipient might choose to accept the message if either of those 1635 signatures were known to come from trusted sources. 1637 INFORMATIVE EXAMPLE: Recipients might choose to whitelist mailing 1638 lists to which they have subscribed and that have acceptable anti- 1639 abuse policies so as to accept messages sent to that list even 1640 from unknown authors. They might also subscribe to less trusted 1641 mailing lists (e.g., those without anti-abuse protection) and be 1642 willing to accept all messages from specific authors, but insist 1643 on doing additional abuse scanning for other messages. 1645 Another related example of multiple signers might be forwarding 1646 services, such as those commonly associated with academic alumni 1647 sites. 1649 INFORMATIVE EXAMPLE: A recipient might have an address at 1650 members.example.org, a site that has anti-abuse protection that is 1651 somewhat less effective than the recipient would prefer. Such a 1652 recipient might have specific authors whose messages would be 1653 trusted absolutely, but messages from unknown authors that had 1654 passed the forwarder's scrutiny would have only medium trust. 1656 4.2. Interpretation 1658 A signer that is adding a signature to a message merely creates a new 1659 DKIM-Signature header, using the usual semantics of the h= option. A 1660 signer MAY sign previously existing DKIM-Signature header fields 1661 using the method described in Section 5.4 to sign trace header 1662 fields. 1664 INFORMATIVE NOTE: Signers should be cognizant that signing DKIM- 1665 Signature header fields may result in signature failures with 1666 intermediaries that do not recognize that DKIM-Signature header 1667 fields are trace header fields and unwittingly reorder them, thus 1668 breaking such signatures. For this reason, signing existing DKIM- 1669 Signature header fields is unadvised, albeit legal. 1671 INFORMATIVE NOTE: If a header field with multiple instances is 1672 signed, those header fields are always signed from the bottom up. 1673 Thus, it is not possible to sign only specific DKIM-Signature 1674 header fields. For example, if the message being signed already 1675 contains three DKIM-Signature header fields A, B, and C, it is 1676 possible to sign all of them, B and C only, or C only, but not A 1677 only, B only, A and B only, or A and C only. 1679 A signer MAY add more than one DKIM-Signature header field using 1680 different parameters. For example, during a transition period a 1681 signer might want to produce signatures using two different hash 1682 algorithms. 1684 Signers SHOULD NOT remove any DKIM-Signature header fields from 1685 messages they are signing, even if they know that the signatures 1686 cannot be verified. 1688 When evaluating a message with multiple signatures, a verifier SHOULD 1689 evaluate signatures independently and on their own merits. For 1690 example, a verifier that by policy chooses not to accept signatures 1691 with deprecated cryptographic algorithms would consider such 1692 signatures invalid. Verifiers MAY process signatures in any order of 1693 their choice; for example, some verifiers might choose to process 1694 signatures corresponding to the From field in the message header 1695 before other signatures. See Section 6.1 for more information about 1696 signature choices. 1698 INFORMATIVE IMPLEMENTATION NOTE: Verifier attempts to correlate 1699 valid signatures with invalid signatures in an attempt to guess 1700 why a signature failed are ill-advised. In particular, there is 1701 no general way that a verifier can determine that an invalid 1702 signature was ever valid. 1704 Verifiers SHOULD continue to check signatures until a signature 1705 successfully verifies to the satisfaction of the verifier. To limit 1706 potential denial-of-service attacks, verifiers MAY limit the total 1707 number of signatures they will attempt to verify. 1709 If a verifier module reports signatures whose evaluations produced 1710 PERMFAIL results, identity assessors SHOULD ignore those signatures 1711 (see Section 6.1), acting as though they were not present in the 1712 message. 1714 5. Signer Actions 1716 The following steps are performed in order by signers. 1718 5.1. Determine Whether the Email Should Be Signed and by Whom 1720 A signer can obviously only sign email for domains for which it has a 1721 private key and the necessary knowledge of the corresponding public 1722 key and selector information. However, there are a number of other 1723 reasons beyond the lack of a private key why a signer could choose 1724 not to sign an email. 1726 INFORMATIVE NOTE: Signing modules may be incorporated into any 1727 portion of the mail system as deemed appropriate, including an 1728 MUA, a SUBMISSION server, or an MTA. Wherever implemented, 1729 signers should beware of signing (and thereby asserting 1730 responsibility for) messages that may be problematic. In 1731 particular, within a trusted enclave the signing address might be 1732 derived from the header according to local policy; SUBMISSION 1733 servers might only sign messages from users that are properly 1734 authenticated and authorized. 1736 INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not sign 1737 Received header fields if the outgoing gateway MTA obfuscates 1738 Received header fields, for example, to hide the details of 1739 internal topology. 1741 If an email cannot be signed for some reason, it is a local policy 1742 decision as to what to do with that email. 1744 5.2. Select a Private Key and Corresponding Selector Information 1746 This specification does not define the basis by which a signer should 1747 choose which private key and selector information to use. Currently, 1748 all selectors are equal as far as this specification is concerned, so 1749 the decision should largely be a matter of administrative 1750 convenience. Distribution and management of private keys is also 1751 outside the scope of this document. 1753 INFORMATIVE OPERATIONS ADVICE: A signer should not sign with a 1754 private key when the selector containing the corresponding public 1755 key is expected to be revoked or removed before the verifier has 1756 an opportunity to validate the signature. The signer should 1757 anticipate that verifiers may choose to defer validation, perhaps 1758 until the message is actually read by the final recipient. In 1759 particular, when rotating to a new key pair, signing should 1760 immediately commence with the new private key and the old public 1761 key should be retained for a reasonable validation interval before 1762 being removed from the key server. 1764 5.3. Normalize the Message to Prevent Transport Conversions 1766 Some messages, particularly those using 8-bit characters, are subject 1767 to modification during transit, notably conversion to 7-bit form. 1768 Such conversions will break DKIM signatures. In order to minimize 1769 the chances of such breakage, signers SHOULD convert the message to a 1770 suitable MIME content transfer encoding such as quoted-printable or 1771 base64 as described in [RFC2045] before signing. Such conversion is 1772 outside the scope of DKIM; the actual message SHOULD be converted to 1773 7-bit MIME by an MUA or MSA prior to presentation to the DKIM 1774 algorithm. 1776 Similarly, a message that is not compliant with RFC5322, RFC2045 and 1777 RFC2047 can be subject to attempts by intermediaries to correct or 1778 interpret such content. See Section 8 of [RFC4409] for examples of 1779 changes that are commonly made. Such "corrections" may break DKIM 1780 signatures or have other undesirable effects. Therefore, a verifier 1781 SHOULD NOT validate a message that is not compliant with those 1782 specifications. 1784 If the message is submitted to the signer with any local encoding 1785 that will be modified before transmission, that modification to 1786 canonical [RFC5322] form MUST be done before signing. In particular, 1787 bare CR or LF characters (used by some systems as a local line 1788 separator convention) MUST be converted to the SMTP-standard CRLF 1789 sequence before the message is signed. Any conversion of this sort 1790 SHOULD be applied to the message actually sent to the recipient(s), 1791 not just to the version presented to the signing algorithm. 1793 More generally, the signer MUST sign the message as it is expected to 1794 be received by the verifier rather than in some local or internal 1795 form. 1797 5.4. Determine the Header Fields to Sign 1799 The From header field MUST be signed (that is, included in the "h=" 1800 tag of the resulting DKIM-Signature header field). Signers SHOULD 1801 NOT sign an existing header field likely to be legitimately modified 1802 or removed in transit. In particular, [RFC5321] explicitly permits 1803 modification or removal of the Return-Path header field in transit. 1804 Signers MAY include any other header fields present at the time of 1805 signing at the discretion of the signer. 1807 INFORMATIVE OPERATIONS NOTE: The choice of which header fields to 1808 sign is non-obvious. One strategy is to sign all existing, non- 1809 repeatable header fields. An alternative strategy is to sign only 1810 header fields that are likely to be displayed to or otherwise be 1811 likely to affect the processing of the message at the receiver. A 1812 third strategy is to sign only "well known" headers. Note that 1813 verifiers may treat unsigned header fields with extreme 1814 skepticism, including refusing to display them to the end user or 1815 even ignoring the signature if it does not cover certain header 1816 fields. For this reason, signing fields present in the message 1817 such as Date, Subject, Reply-To, Sender, and all MIME header 1818 fields are highly advised. 1820 The DKIM-Signature header field is always implicitly signed and MUST 1821 NOT be included in the "h=" tag except to indicate that other 1822 preexisting signatures are also signed. 1824 Signers MAY claim to have signed header fields that do not exist 1825 (that is, signers MAY include the header field name in the "h=" tag 1826 even if that header field does not exist in the message). When 1827 computing the signature, the non-existing header field MUST be 1828 treated as the null string (including the header field name, header 1829 field value, all punctuation, and the trailing CRLF). 1831 INFORMATIVE RATIONALE: This allows signers to explicitly assert 1832 the absence of a header field; if that header field is added later 1833 the signature will fail. 1835 INFORMATIVE NOTE: A header field name need only be listed once 1836 more than the actual number of that header field in a message at 1837 the time of signing in order to prevent any further additions. 1838 For example, if there is a single Comments header field at the 1839 time of signing, listing Comments twice in the "h=" tag is 1840 sufficient to prevent any number of Comments header fields from 1841 being appended; it is not necessary (but is legal) to list 1842 Comments three or more times in the "h=" tag. 1844 Signers choosing to sign an existing header field that occurs more 1845 than once in the message (such as Received) MUST sign the physically 1846 last instance of that header field in the header block. Signers 1847 wishing to sign multiple instances of such a header field MUST 1848 include the header field name multiple times in the h= tag of the 1849 DKIM-Signature header field, and MUST sign such header fields in 1850 order from the bottom of the header field block to the top. The 1851 signer MAY include more instances of a header field name in h= than 1852 there are actual corresponding header fields to indicate that 1853 additional header fields of that name SHOULD NOT be added. 1855 INFORMATIVE EXAMPLE: 1857 If the signer wishes to sign two existing Received header fields, 1858 and the existing header contains: 1859 Received: 1860 Received: 1861 Received: 1863 then the resulting DKIM-Signature header field should read: 1865 DKIM-Signature: ... h=Received : Received :... 1866 and Received header fields and will be signed in that 1867 order. 1869 Signers should be careful of signing header fields that might have 1870 additional instances added later in the delivery process, since such 1871 header fields might be inserted after the signed instance or 1872 otherwise reordered. Trace header fields (such as Received) and 1873 Resent-* blocks are the only fields prohibited by [RFC5322] from 1874 being reordered. In particular, since DKIM-Signature header fields 1875 may be reordered by some intermediate MTAs, signing existing DKIM- 1876 Signature header fields is error-prone. 1878 INFORMATIVE ADMONITION: Despite the fact that [RFC5322] permits 1879 header fields to be reordered (with the exception of Received 1880 header fields), reordering of signed header fields with multiple 1881 instances by intermediate MTAs will cause DKIM signatures to be 1882 broken; such anti-social behavior should be avoided. 1884 INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this 1885 specification, all end-user visible header fields should be signed 1886 to avoid possible "indirect spamming". For example, if the 1887 Subject header field is not signed, a spammer can resend a 1888 previously signed mail, replacing the legitimate subject with a 1889 one-line spam. 1891 5.5. Recommended Signature Content 1893 The purpose of the DKIM cryptographic algorithm is to affix an 1894 identifier to the message in a way that is both robust against normal 1895 transit-related changes and resistant to kinds of replay attacks. An 1896 essential aspect of satisfying these requirements is choosing what 1897 header fields to include in the hash and what fields to exclude. 1899 The basic rule for choosing fields to include is to select those 1900 fields that constitute the "core" of the message content. Hence, any 1901 replay attack will have to include these in order to have the 1902 signature succeed; but with these included, the core of the message 1903 is valid, even if sent on to new recipients. 1905 Common examples of fields with addresses and fields with textual 1906 content related to the body are: 1908 o From (REQUIRED; see Section 5.4) 1910 o Reply-To 1912 o Subject 1914 o Date 1916 o To, Cc 1918 o Resent-Date, Resent-From, Resent-To, Resent-Cc 1920 o In-Reply-To, References 1922 o List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post, 1923 List-Owner, List-Archive 1925 If the "l=" signature tag is in use (see Section 3.5), the Content- 1926 Type field is also a candidate for being included as it could be 1927 replaced in a way that causes completely different content to be 1928 rendered to the receiving user. 1930 There are tradeoffs in the decision of what constitutes the "core" of 1931 the message, which for some fields is a subjective concept. 1932 Including fields such as "Message-ID" for example is useful if one 1933 considers a mechanism for being able to distinguish separate 1934 instances of the same message to be core content. Similarly, "In- 1935 Reply-To" and "References" might be desirable to include if one 1936 considers message threading to be a core part of the message. 1938 Another class of fields that may be of interest are those that convey 1939 security-related information about the message, such as 1940 Authentication-Results [RFC5451]. 1942 The basic rule for choosing fields to exclude is to select those 1943 fields for which there are multiple fields with the same name, and 1944 fields that are modified in transit. Examples of these are: 1946 o Return-Path 1948 o Received 1950 o Comments, Keywords 1952 Note that the DKIM-Signature field is also excluded from the header 1953 hash, because its handling is specified separately. 1955 Typically, it is better to exclude other, optional fields because of 1956 the potential that additional fields of the same name will be 1957 legitimately added or re-ordered prior to verification. There are 1958 likely to be legitimate exceptions to this rule, because of the wide 1959 variety of application-specific header fields that might be applied 1960 to a message, some of which are unlikely to be duplicated, modified, 1961 or reordered. 1963 Signers SHOULD choose canonicalization algorithms based on the types 1964 of messages they process and their aversion to risk. For example, 1965 e-commerce sites sending primarily purchase receipts, which are not 1966 expected to be processed by mailing lists or other software likely to 1967 modify messages, will generally prefer "simple" canonicalization. 1968 Sites sending primarily person-to-person email will likely prefer to 1969 be more resilient to modification during transport by using "relaxed" 1970 canonicalization. 1972 Signers SHOULD NOT use "l=" unless they intend to accommodate 1973 intermediate mail processors that append text to a message. For 1974 example, many mailing list processors append "unsubscribe" 1975 information to message bodies. If signers use "l=", they SHOULD 1976 include the entire message body existing at the time of signing in 1977 computing the count. In particular, signers SHOULD NOT specify a 1978 body length of 0 since this may be interpreted as a meaningless 1979 signature by some verifiers. 1981 5.6. Compute the Message Hash and Signature 1983 The signer MUST compute the message hash as described in Section 3.7 1984 and then sign it using the selected public-key algorithm. This will 1985 result in a DKIM-Signature header field that will include the body 1986 hash and a signature of the header hash, where that header includes 1987 the DKIM-Signature header field itself. 1989 Entities such as mailing list managers that implement DKIM and that 1990 modify the message or a header field (for example, inserting 1991 unsubscribe information) before retransmitting the message SHOULD 1992 check any existing signature on input and MUST make such 1993 modifications before re-signing the message. 1995 The signer MAY elect to limit the number of bytes of the body that 1996 will be included in the hash and hence signed. The length actually 1997 hashed should be inserted in the "l=" tag of the DKIM-Signature 1998 header field. 2000 5.7. Insert the DKIM-Signature Header Field 2002 Finally, the signer MUST insert the DKIM-Signature header field 2003 created in the previous step prior to transmitting the email. The 2004 DKIM-Signature header field MUST be the same as used to compute the 2005 hash as described above, except that the value of the "b=" tag MUST 2006 be the appropriately signed hash computed in the previous step, 2007 signed using the algorithm specified in the "a=" tag of the DKIM- 2008 Signature header field and using the private key corresponding to the 2009 selector given in the "s=" tag of the DKIM-Signature header field, as 2010 chosen above in Section 5.2 2012 The DKIM-Signature header field MUST be inserted before any other 2013 DKIM-Signature fields in the header block. 2015 INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this 2016 is to insert the DKIM-Signature header field at the beginning of 2017 the header block. In particular, it may be placed before any 2018 existing Received header fields. This is consistent with treating 2019 DKIM-Signature as a trace header field. 2021 6. Verifier Actions 2023 Since a signer MAY remove or revoke a public key at any time, it is 2024 advised that verification occur in a timely manner. In many 2025 configurations, the most timely place is during acceptance by the 2026 border MTA or shortly thereafter. In particular, deferring 2027 verification until the message is accessed by the end user is 2028 discouraged. 2030 A border or intermediate MTA MAY verify the message signature(s). An 2031 MTA who has performed verification MAY communicate the result of that 2032 verification by adding a verification header field to incoming 2033 messages. This considerably simplifies things for the user, who can 2034 now use an existing mail user agent. Most MUAs have the ability to 2035 filter messages based on message header fields or content; these 2036 filters would be used to implement whatever policy the user wishes 2037 with respect to unsigned mail. 2039 A verifying MTA MAY implement a policy with respect to unverifiable 2040 mail, regardless of whether or not it applies the verification header 2041 field to signed messages. 2043 Verifiers MUST produce a result that is semantically equivalent to 2044 applying the following steps in the order listed. In practice, 2045 several of these steps can be performed in parallel in order to 2046 improve performance. 2048 6.1. Extract Signatures from the Message 2050 The order in which verifiers try DKIM-Signature header fields is not 2051 defined; verifiers MAY try signatures in any order they like. For 2052 example, one implementation might try the signatures in textual 2053 order, whereas another might try signatures by identities that match 2054 the contents of the From header field before trying other signatures. 2055 Verifiers MUST NOT attribute ultimate meaning to the order of 2056 multiple DKIM-Signature header fields. In particular, there is 2057 reason to believe that some relays will reorder the header fields in 2058 potentially arbitrary ways. 2060 INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as 2061 a clue to signing order in the absence of any other information. 2062 However, other clues as to the semantics of multiple signatures 2063 (such as correlating the signing host with Received header fields) 2064 might also be considered. 2066 A verifier SHOULD NOT treat a message that has one or more bad 2067 signatures and no good signatures differently from a message with no 2068 signature at all; such treatment is a matter of local policy and is 2069 beyond the scope of this document. 2071 When a signature successfully verifies, a verifier will either stop 2072 processing or attempt to verify any other signatures, at the 2073 discretion of the implementation. A verifier MAY limit the number of 2074 signatures it tries to avoid denial-of-service attacks. 2076 INFORMATIVE NOTE: An attacker could send messages with large 2077 numbers of faulty signatures, each of which would require a DNS 2078 lookup and corresponding CPU time to verify the message. This 2079 could be an attack on the domain that receives the message, by 2080 slowing down the verifier by requiring it to do a large number of 2081 DNS lookups and/or signature verifications. It could also be an 2082 attack against the domains listed in the signatures, essentially 2083 by enlisting innocent verifiers in launching an attack against the 2084 DNS servers of the actual victim. 2086 In the following description, text reading "return status 2087 (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL") 2088 means that the verifier MUST immediately cease processing that 2089 signature. The verifier SHOULD proceed to the next signature, if any 2090 is present, and completely ignore the bad signature. If the status 2091 is "PERMFAIL", the signature failed and should not be reconsidered. 2092 If the status is "TEMPFAIL", the signature could not be verified at 2093 this time but may be tried again later. A verifier MAY either 2094 arrange to defer the message for later processing, or try another 2095 signature; if no good signature is found and any of the signatures 2096 resulted in a TEMPFAIL status, the verifier MAY arrange to defer the 2097 message for later processing. The "(explanation)" is not normative 2098 text; it is provided solely for clarification. 2100 Verifiers that are prepared to validate multiple signature header 2101 fields SHOULD proceed to the next signature header field, if one 2102 exists. However, verifiers MAY make note of the fact that an invalid 2103 signature was present for consideration at a later step. 2105 INFORMATIVE NOTE: The rationale of this requirement is to permit 2106 messages that have invalid signatures but also a valid signature 2107 to work. For example, a mailing list exploder might opt to leave 2108 the original submitter signature in place even though the exploder 2109 knows that it is modifying the message in some way that will break 2110 that signature, and the exploder inserts its own signature. In 2111 this case, the message should succeed even in the presence of the 2112 known-broken signature. 2114 For each signature to be validated, the following steps should be 2115 performed in such a manner as to produce a result that is 2116 semantically equivalent to performing them in the indicated order. 2118 6.1.1. Validate the Signature Header Field 2120 Implementers MUST meticulously validate the format and values in the 2121 DKIM-Signature header field; any inconsistency or unexpected values 2122 MUST cause the header field to be completely ignored and the verifier 2123 to return PERMFAIL (signature syntax error). Being "liberal in what 2124 you accept" is definitely a bad strategy in this security context. 2125 Note however that this does not include the existence of unknown tags 2126 in a DKIM-Signature header field, which are explicitly permitted. 2127 Verifiers MUST return PERMFAIL (incompatible version) when presented 2128 a DKIM-Signature header field with a "v=" tag that is inconsistent 2129 with this specification. 2131 INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of course, 2132 choose to also verify signatures generated by older versions of 2133 this specification. 2135 If any tag listed as "required" in Section 3.5 is omitted from the 2136 DKIM-Signature header field, the verifier MUST ignore the DKIM- 2137 Signature header field and return PERMFAIL (signature missing 2138 required tag). 2140 INFORMATIONAL NOTE: The tags listed as required in Section 3.5 are 2141 "v=", "a=", "b=", "bh=", "d=", "h=", and "s=". Should there be a 2142 conflict between this note and Section 3.5, Section 3.5 is 2143 normative. 2145 If the DKIM-Signature header field does not contain the "i=" tag, the 2146 verifier MUST behave as though the value of that tag were "@d", where 2147 "d" is the value from the "d=" tag. 2149 Verifiers MUST confirm that the domain specified in the "d=" tag is 2150 the same as or a parent domain of the domain part of the "i=" tag. 2151 If not, the DKIM-Signature header field MUST be ignored and the 2152 verifier should return PERMFAIL (domain mismatch). 2154 If the "h=" tag does not include the From header field, the verifier 2155 MUST ignore the DKIM-Signature header field and return PERMFAIL (From 2156 field not signed). 2158 Verifiers MAY ignore the DKIM-Signature header field and return 2159 PERMFAIL (signature expired) if it contains an "x=" tag and the 2160 signature has expired. 2162 Verifiers MAY ignore the DKIM-Signature header field if the domain 2163 used by the signer in the "d=" tag is not associated with a valid 2164 signing entity. For example, signatures with "d=" values such as 2165 "com" and "co.uk" may be ignored. The list of unacceptable domains 2166 SHOULD be configurable. 2168 Verifiers MAY ignore the DKIM-Signature header field and return 2169 PERMFAIL (unacceptable signature header) for any other reason, for 2170 example, if the signature does not sign header fields that the 2171 verifier views to be essential. As a case in point, if MIME header 2172 fields are not signed, certain attacks may be possible that the 2173 verifier would prefer to avoid. 2175 6.1.2. Get the Public Key 2177 The public key for a signature is needed to complete the verification 2178 process. The process of retrieving the public key depends on the 2179 query type as defined by the "q=" tag in the DKIM-Signature header 2180 field. Obviously, a public key need only be retrieved if the process 2181 of extracting the signature information is completely successful. 2182 Details of key management and representation are described in 2183 Section 3.6. The verifier MUST validate the key record and MUST 2184 ignore any public key records that are malformed. 2186 NOTE: The use of a wildcard TXT record that covers a queried DKIM 2187 domain name will produce a response to a DKIM query that is 2188 unlikely to be valid DKIM key record. This problem is not 2189 specific to DKIM and applies to many other types of queries. 2190 Client software that processes DNS responses needs to take this 2191 problem into account. 2193 When validating a message, a verifier MUST perform the following 2194 steps in a manner that is semantically the same as performing them in 2195 the order indicated -- in some cases the implementation may 2196 parallelize or reorder these steps, as long as the semantics remain 2197 unchanged: 2199 1. Retrieve the public key as described in Section 3.6 using the 2200 algorithm in the "q=" tag, the domain from the "d=" tag, and the 2201 selector from the "s=" tag. 2203 2. If the query for the public key fails to respond, the verifier 2204 MAY seek a later verification attempt by returning TEMPFAIL (key 2205 unavailable). 2207 3. If the query for the public key fails because the corresponding 2208 key record does not exist, the verifier MUST immediately return 2209 PERMFAIL (no key for signature). 2211 4. If the query for the public key returns multiple key records, the 2212 verifier may choose one of the key records or may cycle through 2213 the key records performing the remainder of these steps on each 2214 record at the discretion of the implementer. The order of the 2215 key records is unspecified. If the verifier chooses to cycle 2216 through the key records, then the "return ..." wording in the 2217 remainder of this section means "try the next key record, if any; 2218 if none, return to try another signature in the usual way". 2220 5. If the result returned from the query does not adhere to the 2221 format defined in this specification, the verifier MUST ignore 2222 the key record and return PERMFAIL (key syntax error). Verifiers 2223 are urged to validate the syntax of key records carefully to 2224 avoid attempted attacks. In particular, the verifier MUST ignore 2225 keys with a version code ("v=" tag) that they do not implement. 2227 6. If the "h=" tag exists in the public key record and the hash 2228 algorithm implied by the "a=" tag in the DKIM-Signature header 2229 field is not included in the contents of the "h=" tag, the 2230 verifier MUST ignore the key record and return PERMFAIL 2231 (inappropriate hash algorithm). 2233 7. If the public key data (the "p=" tag) is empty, then this key has 2234 been revoked and the verifier MUST treat this as a failed 2235 signature check and return PERMFAIL (key revoked). There is no 2236 defined semantic difference between a key that has been revoked 2237 and a key record that has been removed. 2239 8. If the public key data is not suitable for use with the algorithm 2240 and key types defined by the "a=" and "k=" tags in the DKIM- 2241 Signature header field, the verifier MUST immediately return 2242 PERMFAIL (inappropriate key algorithm). 2244 6.1.3. Compute the Verification 2246 Given a signer and a public key, verifying a signature consists of 2247 actions semantically equivalent to the following steps. 2249 1. Based on the algorithm defined in the "c=" tag, the body length 2250 specified in the "l=" tag, and the header field names in the "h=" 2251 tag, prepare a canonicalized version of the message as is 2252 described in Section 3.7 (note that this version does not 2253 actually need to be instantiated). When matching header field 2254 names in the "h=" tag against the actual message header field, 2255 comparisons MUST be case-insensitive. 2257 2. Based on the algorithm indicated in the "a=" tag, compute the 2258 message hashes from the canonical copy as described in 2259 Section 3.7. 2261 3. Verify that the hash of the canonicalized message body computed 2262 in the previous step matches the hash value conveyed in the "bh=" 2263 tag. If the hash does not match, the verifier SHOULD ignore the 2264 signature and return PERMFAIL (body hash did not verify). 2266 4. Using the signature conveyed in the "b=" tag, verify the 2267 signature against the header hash using the mechanism appropriate 2268 for the public key algorithm described in the "a=" tag. If the 2269 signature does not validate, the verifier SHOULD ignore the 2270 signature and return PERMFAIL (signature did not verify). 2272 5. Otherwise, the signature has correctly verified. 2274 INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to 2275 initiate the public-key query in parallel with calculating the 2276 hash as the public key is not needed until the final decryption is 2277 calculated. Implementations may also verify the signature on the 2278 message header before validating that the message hash listed in 2279 the "bh=" tag in the DKIM-Signature header field matches that of 2280 the actual message body; however, if the body hash does not match, 2281 the entire signature must be considered to have failed. 2283 A body length specified in the "l=" tag of the signature limits the 2284 number of bytes of the body passed to the verification algorithm. 2285 All data beyond that limit is not validated by DKIM. Hence, 2286 verifiers might treat a message that contains bytes beyond the 2287 indicated body length with suspicion, such as by declaring the 2288 signature invalid (e.g., by returning PERMFAIL (unsigned content)), 2289 or conveying the partial verification to the policy module. 2291 6.2. Communicate Verification Results 2293 Verifiers wishing to communicate the results of verification to other 2294 parts of the mail system may do so in whatever manner they see fit. 2295 For example, implementations might choose to add an email header 2296 field to the message before passing it on. Any such header field 2297 SHOULD be inserted before any existing DKIM-Signature or preexisting 2298 authentication status header fields in the header field block. The 2299 Authentication-Results: header field ([RFC5451]) MAY be used for this 2300 purpose. 2302 INFORMATIVE ADVICE to MUA filter writers: Patterns intended to 2303 search for results header fields to visibly mark authenticated 2304 mail for end users should verify that such header field was added 2305 by the appropriate verifying domain and that the verified identity 2306 matches the author identity that will be displayed by the MUA. In 2307 particular, MUA filters should not be influenced by bogus results 2308 header fields added by attackers. To circumvent this attack, 2309 verifiers MAY wish to request deletion of existing results header 2310 fields after verification and before arranging to add a new header 2311 field. 2313 6.3. Interpret Results/Apply Local Policy 2315 It is beyond the scope of this specification to describe what actions 2316 an Identity Assessor can make, but mail carrying a validated SDID 2317 presents an opportunity to an Identity Assessor that unauthenticated 2318 email does not. Specifically, an authenticated email creates a 2319 predictable identifier by which other decisions can reliably be 2320 managed, such as trust and reputation. Conversely, unauthenticated 2321 email lacks a reliable identifier that can be used to assign trust 2322 and reputation. It is reasonable to treat unauthenticated email as 2323 lacking any trust and having no positive reputation. 2325 In general, modules that consume DKIM verification output SHOULD NOT 2326 determine message acceptability based solely on a lack of any 2327 signature or on an unverifiable signature; such rejection would cause 2328 severe interoperability problems. If an MTA does wish to reject such 2329 messages during an SMTP session (for example, when communicating with 2330 a peer who, by prior agreement, agrees to only send signed messages), 2331 and a signature is missing or does not verify, the handling MTA 2332 SHOULD use a 550/5.7.x reply code. 2334 Where the verifier is integrated within the MTA and it is not 2335 possible to fetch the public key, perhaps because the key server is 2336 not available, a temporary failure message MAY be generated using a 2337 451/4.7.5 reply code, such as: 2338 451 4.7.5 Unable to verify signature - key server unavailable 2340 Temporary failures such as inability to access the key server or 2341 other external service are the only conditions that SHOULD use a 4xx 2342 SMTP reply code. In particular, cryptographic signature verification 2343 failures MUST NOT provoke 4xx SMTP replies. 2345 Once the signature has been verified, that information MUST be 2346 conveyed to the Identity Assessor (such as an explicit allow/ 2347 whitelist and reputation system) and/or to the end user. If the SDID 2348 is not the same as the address in the From: header field, the mail 2349 system SHOULD take pains to ensure that the actual SDID is clear to 2350 the reader. 2352 While the symptoms of a failed verification are obvious -- the 2353 signature doesn't verify -- establishing the exact cause can be more 2354 difficult. If a selector cannot be found, is that because the 2355 selector has been removed, or was the value changed somehow in 2356 transit? If the signature line is missing, is that because it was 2357 never there, or was it removed by an overzealous filter? For 2358 diagnostic purposes, the exact reason why the verification fails 2359 SHOULD be made available and possibly recorded in the system logs. 2360 If the email cannot be verified, then it SHOULD be treated the same 2361 as all unverified email regardless of whether or not it looks like it 2362 was signed. 2364 See Section 8.14 and Section 8.15 for additional discussion and 2365 references. 2367 7. IANA Considerations 2369 DKIM has registered namespaces with IANA. In all cases, new values 2370 are assigned only for values that have been documented in a published 2371 RFC that has IETF Consensus [RFC5226]. 2373 This memo updates these registries as described below. Of note is 2374 the addition of a new "status" column. All registrations into these 2375 namespaces MUST include the name being registered, the document in 2376 which it was registered or updated, and an indication of its current 2377 status which MUST be one of "active" (in current use) or "historic" 2378 (no longer in current use). 2380 7.1. DKIM-Signature Tag Specifications 2382 A DKIM-Signature provides for a list of tag specifications. IANA has 2383 established the DKIM-Signature Tag Specification Registry for tag 2384 specifications that can be used in DKIM-Signature fields. 2386 The updated entries in the registry comprise: 2388 +------+-----------------+--------+ 2389 | TYPE | REFERENCE | STATUS | 2390 +------+-----------------+--------+ 2391 | v | (this document) | active | 2392 | a | (this document) | active | 2393 | b | (this document) | active | 2394 | bh | (this document) | active | 2395 | c | (this document) | active | 2396 | d | (this document) | active | 2397 | h | (this document) | active | 2398 | i | (this document) | active | 2399 | l | (this document) | active | 2400 | q | (this document) | active | 2401 | s | (this document) | active | 2402 | t | (this document) | active | 2403 | x | (this document) | active | 2404 | z | (this document) | active | 2405 +------+-----------------+--------+ 2407 Table 1: DKIM-Signature Tag Specification Registry Updated Values 2409 7.2. DKIM-Signature Query Method Registry 2411 The "q=" tag-spec (specified in Section 3.5) provides for a list of 2412 query methods. 2414 IANA has established the DKIM-Signature Query Method Registry for 2415 mechanisms that can be used to retrieve the key that will permit 2416 validation processing of a message signed using DKIM. 2418 The updated entry in the registry comprises: 2420 +------+--------+-----------------+--------+ 2421 | TYPE | OPTION | REFERENCE | STATUS | 2422 +------+--------+-----------------+--------+ 2423 | dns | txt | (this document) | active | 2424 +------+--------+-----------------+--------+ 2426 DKIM-Signature Query Method Registry Updated Values 2428 7.3. DKIM-Signature Canonicalization Registry 2430 The "c=" tag-spec (specified in Section 3.5) provides for a specifier 2431 for canonicalization algorithms for the header and body of the 2432 message. 2434 IANA has established the DKIM-Signature Canonicalization Algorithm 2435 Registry for algorithms for converting a message into a canonical 2436 form before signing or verifying using DKIM. 2438 The updated entries in the header registry comprise: 2440 +---------+-----------------+--------+ 2441 | TYPE | REFERENCE | STATUS | 2442 +---------+-----------------+--------+ 2443 | simple | (this document) | active | 2444 | relaxed | (this document) | active | 2445 +---------+-----------------+--------+ 2447 DKIM-Signature Header Canonicalization Algorithm Registry 2448 Updated Values 2450 The updated entries in the body registry comprise: 2452 +---------+-----------------+--------+ 2453 | TYPE | REFERENCE | STATUS | 2454 +---------+-----------------+--------+ 2455 | simple | (this document) | active | 2456 | relaxed | (this document) | active | 2457 +---------+-----------------+--------+ 2459 DKIM-Signature Body Canonicalization Algorithm Registry 2460 Updated Values 2462 7.4. _domainkey DNS TXT Record Tag Specifications 2464 A _domainkey DNS TXT record provides for a list of tag 2465 specifications. IANA has established the DKIM _domainkey DNS TXT Tag 2466 Specification Registry for tag specifications that can be used in DNS 2467 TXT Records. 2469 The updated entries in the registry comprise: 2471 +------+-----------------+----------+ 2472 | TYPE | REFERENCE | STATUS | 2473 +------+-----------------+----------+ 2474 | v | (this document) | active | 2475 | g | [RFC4871] | historic | 2476 | h | (this document) | active | 2477 | k | (this document) | active | 2478 | n | (this document) | active | 2479 | p | (this document) | active | 2480 | s | (this document) | active | 2481 | t | (this document) | active | 2482 +------+-----------------+----------+ 2484 DKIM _domainkey DNS TXT Record Tag Specification Registry 2485 Updated Values 2487 7.5. DKIM Key Type Registry 2489 The "k=" (specified in Section 3.6.1) and the "a=" (specified in Section 3.5) tags provide for a list of 2491 mechanisms that can be used to decode a DKIM signature. 2493 IANA has established the DKIM Key Type Registry for such mechanisms. 2495 The updated entry in the registry comprises: 2497 +------+-----------+--------+ 2498 | TYPE | REFERENCE | STATUS | 2499 +------+-----------+--------+ 2500 | rsa | [RFC3447] | active | 2501 +------+-----------+--------+ 2503 DKIM Key Type Updated Values 2505 7.6. DKIM Hash Algorithms Registry 2507 The "h=" (specified in Section 3.6.1) and the "a=" (specified in Section 3.5) tags provide for a list of 2509 mechanisms that can be used to produce a digest of message data. 2511 IANA has established the DKIM Hash Algorithms Registry for such 2512 mechanisms. 2514 The updated entries in the registry comprise: 2516 +--------+-------------------+--------+ 2517 | TYPE | REFERENCE | STATUS | 2518 +--------+-------------------+--------+ 2519 | sha1 | [FIPS-180-3-2008] | active | 2520 | sha256 | [FIPS-180-3-2008] | active | 2521 +--------+-------------------+--------+ 2523 DKIM Hash Algorithms Updated Values 2525 7.7. DKIM Service Types Registry 2527 The "s=" tag (specified in Section 3.6.1) provides for a 2528 list of service types to which this selector may apply. 2530 IANA has established the DKIM Service Types Registry for service 2531 types. 2533 The updated entries in the registry comprise: 2535 +-------+-----------------+--------+ 2536 | TYPE | REFERENCE | STATUS | 2537 +-------+-----------------+--------+ 2538 | email | (this document) | active | 2539 | * | (this document) | active | 2540 +-------+-----------------+--------+ 2542 DKIM Service Types Registry Updated Values 2544 7.8. DKIM Selector Flags Registry 2546 The "t=" tag (specified in Section 3.6.1) provides for a 2547 list of flags to modify interpretation of the selector. 2549 IANA has established the DKIM Selector Flags Registry for additional 2550 flags. 2552 The updated entries in the registry comprise: 2554 +------+-----------------+--------+ 2555 | TYPE | REFERENCE | STATUS | 2556 +------+-----------------+--------+ 2557 | y | (this document) | active | 2558 | s | (this document) | active | 2559 +------+-----------------+--------+ 2561 DKIM Selector Flags Registry Updated Values 2563 7.9. DKIM-Signature Header Field 2565 IANA has added DKIM-Signature to the "Permanent Message Header 2566 Fields" registry (see [RFC3864]) for the "mail" protocol, using this 2567 document as the reference. 2569 8. Security Considerations 2571 It has been observed that any mechanism that is introduced that 2572 attempts to stem the flow of spam is subject to intensive attack. 2573 DKIM needs to be carefully scrutinized to identify potential attack 2574 vectors and the vulnerability to each. See also [RFC4686]. 2576 8.1. Misuse of Body Length Limits ("l=" Tag) 2578 As noted in Section 3.4.5, use of the "l=" signature tag enables a 2579 variety of attacks in which added content can partially or completely 2580 change the recipient's view of the message. 2582 8.2. Misappropriated Private Key 2584 If the private key for a user is resident on their computer and is 2585 not protected by an appropriately secure mechanism, it is possible 2586 for malware to send mail as that user and any other user sharing the 2587 same private key. The malware would not, however, be able to 2588 generate signed spoofs of other signers' addresses, which would aid 2589 in identification of the infected user and would limit the 2590 possibilities for certain types of attacks involving socially 2591 engineered messages. This threat applies mainly to MUA-based 2592 implementations; protection of private keys on servers can be easily 2593 achieved through the use of specialized cryptographic hardware. 2595 A larger problem occurs if malware on many users' computers obtains 2596 the private keys for those users and transmits them via a covert 2597 channel to a site where they can be shared. The compromised users 2598 would likely not know of the misappropriation until they receive 2599 "bounce" messages from messages they are purported to have sent. 2600 Many users might not understand the significance of these bounce 2601 messages and would not take action. 2603 One countermeasure is to use a user-entered passphrase to encrypt the 2604 private key, although users tend to choose weak passphrases and often 2605 reuse them for different purposes, possibly allowing an attack 2606 against DKIM to be extended into other domains. Nevertheless, the 2607 decoded private key might be briefly available to compromise by 2608 malware when it is entered, or might be discovered via keystroke 2609 logging. The added complexity of entering a passphrase each time one 2610 sends a message would also tend to discourage the use of a secure 2611 passphrase. 2613 A somewhat more effective countermeasure is to send messages through 2614 an outgoing MTA that can authenticate the submitter using existing 2615 techniques (e.g., SMTP Authentication), possibly validate the message 2616 itself (e.g., verify that the header is legitimate and that the 2617 content passes a spam content check), and sign the message using a 2618 key appropriate for the submitter address. Such an MTA can also 2619 apply controls on the volume of outgoing mail each user is permitted 2620 to originate in order to further limit the ability of malware to 2621 generate bulk email. 2623 8.3. Key Server Denial-of-Service Attacks 2625 Since the key servers are distributed (potentially separate for each 2626 domain), the number of servers that would need to be attacked to 2627 defeat this mechanism on an Internet-wide basis is very large. 2628 Nevertheless, key servers for individual domains could be attacked, 2629 impeding the verification of messages from that domain. This is not 2630 significantly different from the ability of an attacker to deny 2631 service to the mail exchangers for a given domain, although it 2632 affects outgoing, not incoming, mail. 2634 A variation on this attack is that if a very large amount of mail 2635 were to be sent using spoofed addresses from a given domain, the key 2636 servers for that domain could be overwhelmed with requests. However, 2637 given the low overhead of verification compared with handling of the 2638 email message itself, such an attack would be difficult to mount. 2640 8.4. Attacks Against the DNS 2642 Since the DNS is a required binding for key services, specific 2643 attacks against the DNS must be considered. 2645 While the DNS is currently insecure [RFC3833], these security 2646 problems are the motivation behind DNS Security (DNSSEC) [RFC4033], 2647 and all users of the DNS will reap the benefit of that work. 2649 DKIM is only intended as a "sufficient" method of proving 2650 authenticity. It is not intended to provide strong cryptographic 2651 proof about authorship or contents. Other technologies such as 2652 OpenPGP [RFC4880] and S/MIME [RFC5751] address those requirements. 2654 A second security issue related to the DNS revolves around the 2655 increased DNS traffic as a consequence of fetching selector-based 2656 data as well as fetching signing domain policy. Widespread 2657 deployment of DKIM will result in a significant increase in DNS 2658 queries to the claimed signing domain. In the case of forgeries on a 2659 large scale, DNS servers could see a substantial increase in queries. 2661 A specific DNS security issue that should be considered by DKIM 2662 verifiers is the name chaining attack described in Section 2.3 of 2663 [RFC3833]. A DKIM verifier, while verifying a DKIM-Signature header 2664 field, could be prompted to retrieve a key record of an attacker's 2665 choosing. This threat can be minimized by ensuring that name 2666 servers, including recursive name servers, used by the verifier 2667 enforce strict checking of "glue" and other additional information in 2668 DNS responses and are therefore not vulnerable to this attack. 2670 8.5. Replay Attacks 2672 In this attack, a spammer sends a message to be spammed to an 2673 accomplice, which results in the message being signed by the 2674 originating MTA. The accomplice resends the message, including the 2675 original signature, to a large number of recipients, possibly by 2676 sending the message to many compromised machines that act as MTAs. 2677 The messages, not having been modified by the accomplice, have valid 2678 signatures. 2680 Partial solutions to this problem involve the use of reputation 2681 services to convey the fact that the specific email address is being 2682 used for spam and that messages from that signer are likely to be 2683 spam. This requires a real-time detection mechanism in order to 2684 react quickly enough. However, such measures might be prone to 2685 abuse, if for example an attacker resent a large number of messages 2686 received from a victim in order to make them appear to be a spammer. 2688 Large verifiers might be able to detect unusually large volumes of 2689 mails with the same signature in a short time period. Smaller 2690 verifiers can get substantially the same volume of information via 2691 existing collaborative systems. 2693 8.6. Limits on Revoking Keys 2695 When a large domain detects undesirable behavior on the part of one 2696 of its users, it might wish to revoke the key used to sign that 2697 user's messages in order to disavow responsibility for messages that 2698 have not yet been verified or that are the subject of a replay 2699 attack. However, the ability of the domain to do so can be limited 2700 if the same key, for scalability reasons, is used to sign messages 2701 for many other users. Mechanisms for explicitly revoking keys on a 2702 per-address basis have been proposed but require further study as to 2703 their utility and the DNS load they represent. 2705 8.7. Intentionally Malformed Key Records 2707 It is possible for an attacker to publish key records in DNS that are 2708 intentionally malformed, with the intent of causing a denial-of- 2709 service attack on a non-robust verifier implementation. The attacker 2710 could then cause a verifier to read the malformed key record by 2711 sending a message to one of its users referencing the malformed 2712 record in a (not necessarily valid) signature. Verifiers MUST 2713 thoroughly verify all key records retrieved from the DNS and be 2714 robust against intentionally as well as unintentionally malformed key 2715 records. 2717 8.8. Intentionally Malformed DKIM-Signature Header Fields 2719 Verifiers MUST be prepared to receive messages with malformed DKIM- 2720 Signature header fields, and thoroughly verify the header field 2721 before depending on any of its contents. 2723 8.9. Information Leakage 2725 An attacker could determine when a particular signature was verified 2726 by using a per-message selector and then monitoring their DNS traffic 2727 for the key lookup. This would act as the equivalent of a "web bug" 2728 for verification time rather than when the message was read. 2730 8.10. Remote Timing Attacks 2732 In some cases it may be possible to extract private keys using a 2733 remote timing attack [BONEH03]. Implementations should consider 2734 obfuscating the timing to prevent such attacks. 2736 8.11. Reordered Header Fields 2738 Existing standards allow intermediate MTAs to reorder header fields. 2739 If a signer signs two or more header fields of the same name, this 2740 can cause spurious verification errors on otherwise legitimate 2741 messages. In particular, signers that sign any existing DKIM- 2742 Signature fields run the risk of having messages incorrectly fail to 2743 verify. 2745 8.12. RSA Attacks 2747 An attacker could create a large RSA signing key with a small 2748 exponent, thus requiring that the verification key have a large 2749 exponent. This will force verifiers to use considerable computing 2750 resources to verify the signature. Verifiers might avoid this attack 2751 by refusing to verify signatures that reference selectors with public 2752 keys having unreasonable exponents. 2754 In general, an attacker might try to overwhelm a verifier by flooding 2755 it with messages requiring verification. This is similar to other 2756 MTA denial-of-service attacks and should be dealt with in a similar 2757 fashion. 2759 8.13. Inappropriate Signing by Parent Domains 2761 The trust relationship described in Section 3.10 could conceivably be 2762 used by a parent domain to sign messages with identities in a 2763 subdomain not administratively related to the parent. For example, 2764 the ".com" registry could create messages with signatures using an 2765 "i=" value in the example.com domain. There is no general solution 2766 to this problem, since the administrative cut could occur anywhere in 2767 the domain name. For example, in the domain "example.podunk.ca.us" 2768 there are three administrative cuts (podunk.ca.us, ca.us, and us), 2769 any of which could create messages with an identity in the full 2770 domain. 2772 INFORMATIVE NOTE: This is considered an acceptable risk for the 2773 same reason that it is acceptable for domain delegation. For 2774 example, in the example above any of the domains could potentially 2775 simply delegate "example.podunk.ca.us" to a server of their choice 2776 and completely replace all DNS-served information. Note that a 2777 verifier MAY ignore signatures that come from an unlikely domain 2778 such as ".com", as discussed in Section 6.1.1. 2780 8.14. Attacks Involving Addition of Header Fields 2782 Many email implementations do not enforce [RFC5322] with strictness. 2783 As discussed in Section 5.3, DKIM processing is predicated on a valid 2784 mail message as its input. However, DKIM implementers should be 2785 aware of the potential effect of having loose enforcement by email 2786 components interacting with DKIM modules. 2788 For example, a message with multiple From: header fields violates 2789 Section 3.6 of [RFC5322]. With the intent of providing a better user 2790 experience, many agents tolerate these violations and deliver the 2791 message anyway. An MUA then might elect to render to the user the 2792 value of the first, or "top", From: field. This may also be done 2793 simply out of the expectation that there is only one, where a "find 2794 first" algorithm would have the same result. Such code in an MUA can 2795 be exploited to fool the user if it is also known that the other 2796 From: field is the one checked by arriving message filters. Such is 2797 the case with DKIM; although the From: field must be signed, a 2798 malformed message bearing more than one From: field might only have 2799 the first ("bottom") one signed, in an attempt to show the message 2800 with some "DKIM passed" annotation while also rendering the From: 2801 field that was not authenticated. (This can also be taken as a 2802 demonstration that DKIM is not designed to support author 2803 validation.) 2805 Note that the technique for using "h=...:from:from:...", described in 2806 Section 8.15 below, is of no effect in the case of an attacker that 2807 is also the signer. 2809 The From: field is used above to illustrate this issue, but it is 2810 only one of several fields that Section 3.6 of [RFC5322] constrains 2811 in this way. In reality any agent that forgives such malformations, 2812 or is careless about identifying which parts of a message were 2813 authenticated, is open to exploitation. 2815 8.15. Malformed Inputs 2817 DKIM allows additional header fields to be added to a signed message 2818 without breaking the signature. This tolerance can be abused, for 2819 example in a replay attack or a man-in-the-middle attack. The attack 2820 is accomplished by creating additional instances of header fields to 2821 an already signed message, without breaking the signature. These 2822 then might be displayed to the end user or are used as filtering 2823 input. Applicable fields might include From: and Subject:. 2825 The resulting message violates section 3.6 of [RFC5322]. The way 2826 such input will be handled and displayed by an MUA is unpredictable, 2827 but it will commonly display the newly added header fields rather 2828 than those that are part of the originally signed message alongside 2829 some "valid DKIM signature" annotation. This might allow an attacker 2830 to replay a previously sent, signed message with a different 2831 Subject:, From: or To: field. 2833 However, [RFC5322] also tolerates obsolete message syntax, which does 2834 allow things like multiple From: fields on messages. The 2835 implementation of DKIM thus potentially creates a more stringent 2836 layer of expectation regarding the meaning of an identity, while that 2837 additional meaning is either obscured from or incorrectly presented 2838 to an end user in this context. 2840 Implementers need to consider this possibility when designing their 2841 input handling functions. Outright rejection of messages that 2842 violate the relevant standards such as [RFC5322], [RFC2045], etc. 2843 will interfere with delivery of legacy formats. Instead, given such 2844 input, a signing module could return an error rather than generate a 2845 signature; a verifying module might return a syntax error code or 2846 arrange not to return a positive result even if the signature 2847 technically validates. 2849 Senders concerned that their messages might be particularly 2850 vulnerable to this sort of attack and who do not wish to rely on 2851 receiver filtering of invalid messages can ensure that adding 2852 additional header fields will break the DKIM signature by including 2853 two copies of the header fields about which they are concerned in the 2854 signature (e.g. "h= ... from:from:to:to:subject:subject ..."). See 2855 Sections 3.5 and 5.4 for further discussion of this mechanism. 2857 Specific validity rules for all known header fields can be gleaned 2858 from the IANA "Permanent Header Field Registry" and the reference 2859 documents it identifies. 2861 9. References 2863 9.1. Normative References 2865 [FIPS-180-3-2008] 2866 U.S. Department of Commerce, "Secure Hash Standard", FIPS 2867 PUB 180-3, October 2008. 2869 [ITU-X660-1997] 2870 "Information Technology - ASN.1 encoding rules: 2871 Specification of Basic Encoding Rules (BER), Canonical 2872 Encoding Rules (CER) and Distinguished Encoding Rules 2873 (DER)", 1997. 2875 [RFC1034] Mockapetris, P., "DOMAIN NAMES - CONCEPTS AND FACILITIES", 2876 RFC 1034, November 1987. 2878 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2879 Extensions (MIME) Part One: Format of Internet Message 2880 Bodies", RFC 2045, November 1996. 2882 [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2883 Extensions (MIME) Part Five: Conformance Criteria and 2884 Examples", RFC 2049, November 1996. 2886 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2887 Requirement Levels", BCP 14, RFC 2119, March 1997. 2889 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2890 Standards (PKCS) #1: RSA Cryptography Specifications 2891 Version 2.1", RFC 3447, February 2003. 2893 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2894 Specifications: ABNF", RFC 5234, January 2008. 2896 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 2897 October 2008. 2899 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 2900 October 2008. 2902 [RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598, 2903 July 2009. 2905 [RFC5890] Klensin, J., "Internationalizing Domain Names in 2906 Applications (IDNA): Definitions and Document Framework", 2907 RFC 5890, August 2010. 2909 9.2. Informative References 2911 [BONEH03] "Remote Timing Attacks are Practical", Proceedings 12th 2912 USENIX Security Symposium, 2003. 2914 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 2915 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 2916 RFC 3766, April 2004. 2918 [RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain 2919 Name System (DNS)", RFC 3833, August 2004. 2921 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2922 Procedures for Message Header Fields", BCP 90, RFC 3864, 2923 September 2004. 2925 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2926 Rose, "DNS Security Introduction and Requirements", 2927 RFC 4033, March 2005. 2929 [RFC4409] Gellens, R. and J. Klensin, "Message Submission for Mail", 2930 RFC 4409, April 2006. 2932 [RFC4686] Fenton, J., "Analysis of Threats Motivating DomainKeys 2933 Identified Mail (DKIM)", RFC 4686, September 2006. 2935 [RFC4870] Delany, M., "Domain-Based Email Authentication Using 2936 Public Keys Advertised in the DNS (DomainKeys)", RFC 4870, 2937 May 2007. 2939 [RFC4871] Allman, E., Callas, J., Delany, M., Libbey, M., Fenton, 2940 J., and M. Thomas, "DomainKeys Identified Mail (DKIM) 2941 Signatures", RFC 4871, May 2007. 2943 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, 2944 "OpenPGP Message Format", RFC 4880, November 2007. 2946 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2947 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2948 May 2008. 2950 [RFC5451] Kucherawy, M., "Message Header Field for Indicating 2951 Message Authentication Status", RFC 5451, April 2009. 2953 [RFC5585] Hansen, T., Crocker, D., and P. Hallam-Baker, "DomainKeys 2954 Identified Mail (DKIM) Service Overview", RFC 5585, 2955 July 2009. 2957 [RFC5672] Crocker, D., Ed., "RFC 4871 DomainKeys Identified Mail 2958 (DKIM) Signatures -- Update", RFC 5672, August 2009. 2960 [RFC5751] Ramsdell, B., "Secure/Multipurpose Internet Mail 2961 Extensions (S/MIME) Version 3.1 Message Specification", 2962 RFC 5751, January 2010. 2964 [RFC5863] Hansen, T., Siegel, E., Hallam-Baker, P., and D. Crocker, 2965 "DomainKeys Identified Mail (DKIM) Development, 2966 Deployment, and Operations", RFC 5863, May 2010. 2968 Appendix A. Example of Use (INFORMATIVE) 2970 This section shows the complete flow of an email from submission to 2971 final delivery, demonstrating how the various components fit 2972 together. The key used in this example is shown in Appendix C. 2974 A.1. The User Composes an Email 2975 From: Joe SixPack 2976 To: Suzie Q 2977 Subject: Is dinner ready? 2978 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2979 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2981 Hi. 2983 We lost the game. Are you hungry yet? 2985 Joe. 2987 Figure 1: The User Composes an Email 2989 A.2. The Email is Signed 2991 This email is signed by the example.com outbound email server and now 2992 looks like this: 2993 DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com; 2994 c=simple/simple; q=dns/txt; i=joe@football.example.com; 2995 h=Received : From : To : Subject : Date : Message-ID; 2996 bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=; 2997 b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB 2998 4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut 2999 KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV 3000 4bmp/YzhwvcubU4=; 3001 Received: from client1.football.example.com [192.0.2.1] 3002 by submitserver.example.com with SUBMISSION; 3003 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 3004 From: Joe SixPack 3005 To: Suzie Q 3006 Subject: Is dinner ready? 3007 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 3008 Message-ID: <20030712040037.46341.5F8J@football.example.com> 3010 Hi. 3012 We lost the game. Are you hungry yet? 3014 Joe. 3016 The Email is Signed 3018 The signing email server requires access to the private key 3019 associated with the "brisbane" selector to generate this signature. 3021 A.3. The Email Signature is Verified 3023 The signature is normally verified by an inbound SMTP server or 3024 possibly the final delivery agent. However, intervening MTAs can 3025 also perform this verification if they choose to do so. The 3026 verification process uses the domain "example.com" extracted from the 3027 "d=" tag and the selector "brisbane" from the "s=" tag in the DKIM- 3028 Signature header field to form the DNS DKIM query for: 3029 brisbane._domainkey.example.com 3031 Signature verification starts with the physically last Received 3032 header field, the From header field, and so forth, in the order 3033 listed in the "h=" tag. Verification follows with a single CRLF 3034 followed by the body (starting with "Hi."). The email is canonically 3035 prepared for verifying with the "simple" method. The result of the 3036 query and subsequent verification of the signature is stored (in this 3037 example) in the X-Authentication-Results header field line. After 3038 successful verification, the email looks like this: 3039 X-Authentication-Results: shopping.example.net 3040 header.from=joe@football.example.com; dkim=pass 3041 Received: from mout23.football.example.com (192.168.1.1) 3042 by shopping.example.net with SMTP; 3043 Fri, 11 Jul 2003 21:01:59 -0700 (PDT) 3044 DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com; 3045 c=simple/simple; q=dns/txt; i=joe@football.example.com; 3046 h=Received : From : To : Subject : Date : Message-ID; 3047 bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=; 3048 b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB 3049 4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut 3050 KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV 3051 4bmp/YzhwvcubU4=; 3052 Received: from client1.football.example.com [192.0.2.1] 3053 by submitserver.example.com with SUBMISSION; 3054 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 3055 From: Joe SixPack 3056 To: Suzie Q 3057 Subject: Is dinner ready? 3058 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 3059 Message-ID: <20030712040037.46341.5F8J@football.example.com> 3061 Hi. 3063 We lost the game. Are you hungry yet? 3065 Joe. 3067 Successful verification 3069 Appendix B. Usage Examples (INFORMATIVE) 3071 DKIM signing and validating can be used in different ways, for 3072 different operational scenarios. This Appendix discusses some common 3073 examples. 3075 NOTE: Descriptions in this Appendix are for informational purposes 3076 only. They describe various ways that DKIM can be used, given 3077 particular constraints and needs. In no case are these examples 3078 intended to be taken as providing explanation or guidance 3079 concerning DKIM specification details, when creating an 3080 implementation. 3082 B.1. Alternate Submission Scenarios 3084 In the most simple scenario, a user's MUA, MSA, and Internet 3085 (boundary) MTA are all within the same administrative environment, 3086 using the same domain name. Therefore, all of the components 3087 involved in submission and initial transfer are related. However, it 3088 is common for two or more of the components to be under independent 3089 administrative control. This creates challenges for choosing and 3090 administering the domain name to use for signing, and for its 3091 relationship to common email identity header fields. 3093 B.1.1. Delegated Business Functions 3095 Some organizations assign specific business functions to discrete 3096 groups, inside or outside the organization. The goal, then, is to 3097 authorize that group to sign some mail, but to constrain what 3098 signatures they can generate. DKIM selectors (the "s=" signature 3099 tag) facilitate this kind of restricted authorization. Examples of 3100 these outsourced business functions are legitimate email marketing 3101 providers and corporate benefits providers. 3103 Here, the delegated group needs to be able to send messages that are 3104 signed, using the email domain of the client company. At the same 3105 time, the client often is reluctant to register a key for the 3106 provider that grants the ability to send messages for arbitrary 3107 addresses in the domain. 3109 There are multiple ways to administer these usage scenarios. In one 3110 case, the client organization provides all of the public query 3111 service (for example, DNS) administration, and in another it uses DNS 3112 delegation to enable all ongoing administration of the DKIM key 3113 record by the delegated group. 3115 If the client organization retains responsibility for all of the DNS 3116 administration, the outsourcing company can generate a key pair, 3117 supplying the public key to the client company, which then registers 3118 it in the query service, using a unique selector. The client company 3119 retains control over the use of the delegated key because it retains 3120 the ability to revoke the key at any time. 3122 If the client wants the delegated group to do the DNS administration, 3123 it can have the domain name that is specified with the selector point 3124 to the provider's DNS server. The provider then creates and 3125 maintains all of the DKIM signature information for that selector. 3126 Hence, the client cannot provide constraints on the Local-part of 3127 addresses that get signed, but it can revoke the provider's signing 3128 rights by removing the DNS delegation record. 3130 B.1.2. PDAs and Similar Devices 3132 PDAs demonstrate the need for using multiple keys per domain. 3133 Suppose that John Doe wanted to be able to send messages using his 3134 corporate email address, jdoe@example.com, and his email device did 3135 not have the ability to make a Virtual Private Network (VPN) 3136 connection to the corporate network, either because the device is 3137 limited or because there are restrictions enforced by his Internet 3138 access provider. If the device was equipped with a private key 3139 registered for jdoe@example.com by the administrator of the 3140 example.com domain, and appropriate software to sign messages, John 3141 could sign the message on the device itself before transmission 3142 through the outgoing network of the access service provider. 3144 B.1.3. Roaming Users 3146 Roaming users often find themselves in circumstances where it is 3147 convenient or necessary to use an SMTP server other than their home 3148 server; examples are conferences and many hotels. In such 3149 circumstances, a signature that is added by the submission service 3150 will use an identity that is different from the user's home system. 3152 Ideally, roaming users would connect back to their home server using 3153 either a VPN or a SUBMISSION server running with SMTP AUTHentication 3154 on port 587. If the signing can be performed on the roaming user's 3155 laptop, then they can sign before submission, although the risk of 3156 further modification is high. If neither of these are possible, 3157 these roaming users will not be able to send mail signed using their 3158 own domain key. 3160 B.1.4. Independent (Kiosk) Message Submission 3162 Stand-alone services, such as walk-up kiosks and web-based 3163 information services, have no enduring email service relationship 3164 with the user, but users occasionally request that mail be sent on 3165 their behalf. For example, a website providing news often allows the 3166 reader to forward a copy of the article to a friend. This is 3167 typically done using the reader's own email address, to indicate who 3168 the author is. This is sometimes referred to as the "Evite problem", 3169 named after the website of the same name that allows a user to send 3170 invitations to friends. 3172 A common way this is handled is to continue to put the reader's email 3173 address in the From header field of the message, but put an address 3174 owned by the email posting site into the Sender header field. The 3175 posting site can then sign the message, using the domain that is in 3176 the Sender field. This provides useful information to the receiving 3177 email site, which is able to correlate the signing domain with the 3178 initial submission email role. 3180 Receiving sites often wish to provide their end users with 3181 information about mail that is mediated in this fashion. Although 3182 the real efficacy of different approaches is a subject for human 3183 factors usability research, one technique that is used is for the 3184 verifying system to rewrite the From header field, to indicate the 3185 address that was verified. For example: From: John Doe via 3186 news@news-site.com . (Note that such rewriting 3187 will break a signature, unless it is done after the verification pass 3188 is complete.) 3190 B.2. Alternate Delivery Scenarios 3192 Email is often received at a mailbox that has an address different 3193 from the one used during initial submission. In these cases, an 3194 intermediary mechanism operates at the address originally used and it 3195 then passes the message on to the final destination. This mediation 3196 process presents some challenges for DKIM signatures. 3198 B.2.1. Affinity Addresses 3200 "Affinity addresses" allow a user to have an email address that 3201 remains stable, even as the user moves among different email 3202 providers. They are typically associated with college alumni 3203 associations, professional organizations, and recreational 3204 organizations with which they expect to have a long-term 3205 relationship. These domains usually provide forwarding of incoming 3206 email, and they often have an associated Web application that 3207 authenticates the user and allows the forwarding address to be 3208 changed. However, these services usually depend on users sending 3209 outgoing messages through their own service providers' MTAs. Hence, 3210 mail that is signed with the domain of the affinity address is not 3211 signed by an entity that is administered by the organization owning 3212 that domain. 3214 With DKIM, affinity domains could use the Web application to allow 3215 users to register per-user keys to be used to sign messages on behalf 3216 of their affinity address. The user would take away the secret half 3217 of the key pair for signing, and the affinity domain would publish 3218 the public half in DNS for access by verifiers. 3220 This is another application that takes advantage of user-level 3221 keying, and domains used for affinity addresses would typically have 3222 a very large number of user-level keys. Alternatively, the affinity 3223 domain could handle outgoing mail, operating a mail submission agent 3224 that authenticates users before accepting and signing messages for 3225 them. This is of course dependent on the user's service provider not 3226 blocking the relevant TCP ports used for mail submission. 3228 B.2.2. Simple Address Aliasing (.forward) 3230 In some cases a recipient is allowed to configure an email address to 3231 cause automatic redirection of email messages from the original 3232 address to another, such as through the use of a Unix .forward file. 3233 In this case, messages are typically redirected by the mail handling 3234 service of the recipient's domain, without modification, except for 3235 the addition of a Received header field to the message and a change 3236 in the envelope recipient address. In this case, the recipient at 3237 the final address' mailbox is likely to be able to verify the 3238 original signature since the signed content has not changed, and DKIM 3239 is able to validate the message signature. 3241 B.2.3. Mailing Lists and Re-Posters 3243 There is a wide range of behaviors in services that take delivery of 3244 a message and then resubmit it. A primary example is with mailing 3245 lists (collectively called "forwarders" below), ranging from those 3246 that make no modification to the message itself, other than to add a 3247 Received header field and change the envelope information, to those 3248 that add header fields, change the Subject header field, add content 3249 to the body (typically at the end), or reformat the body in some 3250 manner. The simple ones produce messages that are quite similar to 3251 the automated alias services. More elaborate systems essentially 3252 create a new message. 3254 A Forwarder that does not modify the body or signed header fields of 3255 a message is likely to maintain the validity of the existing 3256 signature. It also could choose to add its own signature to the 3257 message. 3259 Forwarders which modify a message in a way that could make an 3260 existing signature invalid are particularly good candidates for 3261 adding their own signatures (e.g., mailing-list-name@example.net). 3263 Since (re-)signing is taking responsibility for the content of the 3264 message, these signing forwarders are likely to be selective, and 3265 forward or re-sign a message only if it is received with a valid 3266 signature or if they have some other basis for knowing that the 3267 message is not spoofed. 3269 A common practice among systems that are primarily redistributors of 3270 mail is to add a Sender header field to the message, to identify the 3271 address being used to sign the message. This practice will remove 3272 any preexisting Sender header field as required by [RFC5322]. The 3273 forwarder applies a new DKIM-Signature header field with the 3274 signature, public key, and related information of the forwarder. 3276 Appendix C. Creating a Public Key (INFORMATIVE) 3278 The default signature is an RSA signed SHA-256 digest of the complete 3279 email. For ease of explanation, the openssl command is used to 3280 describe the mechanism by which keys and signatures are managed. One 3281 way to generate a 1024-bit, unencrypted private key suitable for DKIM 3282 is to use openssl like this: 3283 $ openssl genrsa -out rsa.private 1024 3284 For increased security, the "-passin" parameter can also be added to 3285 encrypt the private key. Use of this parameter will require entering 3286 a password for several of the following steps. Servers may prefer to 3287 use hardware cryptographic support. 3289 The "genrsa" step results in the file rsa.private containing the key 3290 information similar to this: 3291 -----BEGIN RSA PRIVATE KEY----- 3292 MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC 3293 jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb 3294 to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB 3295 AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX 3296 /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ 3297 gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO 3298 n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m 3299 3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/ 3300 eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj 3301 7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA 3302 qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf 3303 eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX 3304 GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc= 3305 -----END RSA PRIVATE KEY----- 3306 To extract the public-key component from the private key, use openssl 3307 like this: 3308 $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM 3310 This results in the file rsa.public containing the key information 3311 similar to this: 3312 -----BEGIN PUBLIC KEY----- 3313 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM 3314 oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R 3315 tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI 3316 MmPSPDdQPNUYckcQ2QIDAQAB 3317 -----END PUBLIC KEY----- 3319 This public-key data (without the BEGIN and END tags) is placed in 3320 the DNS: 3321 $ORIGIN _domainkey.example.org. 3322 brisbane IN TXT ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ" 3323 "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt" 3324 "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v" 3325 "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi" 3326 "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB") 3328 C.1. Compatibility with DomainKeys Key Records 3330 DKIM key records were designed to be backwards-compatible in many 3331 cases with key records used by DomainKeys [RFC4870] (sometimes 3332 referred to as "selector records" in the DomainKeys context). One 3333 area of incompatibility warrants particular attention. The "g=" tag/ 3334 value may be used in DomainKeys and [RFC4871] key records to provide 3335 finer granularity of the validity of the key record to a specific 3336 local-part. A null "g=" value in DomainKeys is valid for all 3337 addresses in the domain. This differs from the usage in the original 3338 DKIM specification, where a null "g=" value is not valid for any 3339 address. In particular, the example public key record in Section 3340 3.2.3 of [RFC4870] with DKIM. 3342 Although the "g=" tag has been deprecated in this version of the DKIM 3343 specification, signers are advised not to include the "g=" tag in key 3344 records because some [RFC4871]-compliant verifiers will be in use for 3345 a considerable period to come. 3347 Appendix D. MUA Considerations (INFORMATIVE) 3349 When a DKIM signature is verified, the processing system sometimes 3350 makes the result available to the recipient user's MUA. How to 3351 present this information to the user in a way that helps them is a 3352 matter of continuing human factors usability research. The tendency 3353 is to have the MUA highlight the SDID, in an attempt to show the user 3354 the identity that is claiming responsibility for the message. An MUA 3355 might do this with visual cues such as graphics, or it might include 3356 the address in an alternate view, or it might even rewrite the 3357 original From address using the verified information. Some MUAs 3358 might indicate which header fields were protected by the validated 3359 DKIM signature. This could be done with a positive indication on the 3360 signed header fields, with a negative indication on the unsigned 3361 header fields, by visually hiding the unsigned header fields, or some 3362 combination of these. If an MUA uses visual indications for signed 3363 header fields, the MUA probably needs to be careful not to display 3364 unsigned header fields in a way that might be construed by the end 3365 user as having been signed. If the message has an l= tag whose value 3366 does not extend to the end of the message, the MUA might also hide or 3367 mark the portion of the message body that was not signed. 3369 The aforementioned information is not intended to be exhaustive. The 3370 MUA may choose to highlight, accentuate, hide, or otherwise display 3371 any other information that may, in the opinion of the MUA author, be 3372 deemed important to the end user. 3374 Appendix E. Changes since RFC4871 3376 o Abstract and introduction refined based on accumulated experience. 3378 o Various references updated. 3380 o Several errata resolved: 3382 * 1376 applied 3384 * 1377 applied 3386 * 1378 applied 3388 * 1379 applied 3390 * 1380 applied 3392 * 1381 applied 3394 * 1382 applied 3396 * 1383 discarded (no longer applies) 3398 * 1384 applied 3399 * 1386 applied 3401 * 1461 applied 3403 * 1487 applied 3405 * 1532 applied 3407 * 1596 applied 3409 o Introductory section enumerating relevent architectural documents 3410 added. 3412 o Introductory section briefly discussing the matter of data 3413 integrity added. 3415 o Allow tolerance of some clock drift. 3417 o Drop "g=" tag from key records. The implementation report 3418 indicates that it is not in use. 3420 o Remove errant note about wildcards in the DNS. 3422 o Remove SMTP-specific advice in most places. 3424 o Reduce (non-normative) recommended signature content list, and 3425 rework the text in that section. 3427 o Clarify signature generation algorithm by rewriting its pseudo- 3428 code. 3430 o Numerous terminology subsections added, imported from [RFC5672]. 3431 Also began using these terms throughout the document (e.g., SDID, 3432 AUID). 3434 o Sections added that specify input and output requirements. Input 3435 requirements address a security concern raised by the working 3436 group (see also new sections in Security Considerations). Output 3437 requirements are imported from [RFC5672]. 3439 o Appendix subsection added discussing compatibility with DomainKeys 3440 ([RFC4870]) records. 3442 o Refer to [RFC5451] as an example method of communicating the 3443 results of DKIM verification. 3445 o Remove advice about possible uses of the "l=" signature tag. 3447 o IANA registry update. 3449 o Add two new Security Considerations sections talking about 3450 malformed message attacks. 3452 o Various copy editing. 3454 Appendix F. Acknowledgements 3456 The previous IETF version of DKIM [RFC4871] was edited by: Eric 3457 Allman, Jon Callas, Mark Delany, Miles Libbey, Jim Fenton and Michael 3458 Thomas. 3460 That specification was the result of an extended, collaborative 3461 effort, including participation by: Russ Allbery, Edwin Aoki, Claus 3462 Assmann, Steve Atkins, Rob Austein, Fred Baker, Mark Baugher, Steve 3463 Bellovin, Nathaniel Borenstein, Dave Crocker, Michael Cudahy, Dennis 3464 Dayman, Jutta Degener, Frank Ellermann, Patrik Faeltstroem, Mark 3465 Fanto, Stephen Farrell, Duncan Findlay, Elliot Gillum, Olafur 3466 Gu[eth]mundsson, Phillip Hallam-Baker, Tony Hansen, Sam Hartman, 3467 Arvel Hathcock, Amir Herzberg, Paul Hoffman, Russ Housley, Craig 3468 Hughes, Cullen Jennings, Don Johnsen, Harry Katz, Murray S. 3469 Kucherawy, Barry Leiba, John Levine, Charles Lindsey, Simon 3470 Longsdale, David Margrave, Justin Mason, David Mayne, Thierry Moreau, 3471 Steve Murphy, Russell Nelson, Dave Oran, Doug Otis, Shamim Pirzada, 3472 Juan Altmayer Pizzorno, Sanjay Pol, Blake Ramsdell, Christian Renaud, 3473 Scott Renfro, Neil Rerup, Eric Rescorla, Dave Rossetti, Hector 3474 Santos, Jim Schaad, the Spamhaus.org team, Malte S. Stretz, Robert 3475 Sanders, Rand Wacker, Sam Weiler, and Dan Wing. 3477 The earlier DomainKeys was a primary source from which DKIM was 3478 derived. Further information about DomainKeys is at [RFC4870]. 3480 This revision received contributions from: Steve Atkins, Mark Delany, 3481 J.D. Falk, Jim Fenton, Michael Hammer, Barry Leiba, John Levine, 3482 Charles Lindsey, Jeff Macdonald, Franck Martin, Brett McDowell, Doug 3483 Otis, Bill Oxley, Hector Santos, Rolf Sonneveld, Michael Thomas, and 3484 Alessandro Vesely. 3486 Authors' Addresses 3488 D. Crocker (editor) 3489 Brandenburg InternetWorking 3490 675 Spruce Dr. 3491 Sunnyvale 3492 USA 3494 Phone: +1.408.246.8253 3495 Email: dcrocker@bbiw.net 3496 URI: http://bbiw.net 3498 Tony Hansen (editor) 3499 AT&T Laboratories 3500 200 Laurel Ave. South 3501 Middletown, NJ 07748 3502 USA 3504 Email: tony+dkimov@maillennium.att.com 3506 M. Kucherawy (editor) 3507 Cloudmark 3508 128 King St., 2nd Floor 3509 San Francisco, CA 94107 3510 USA 3512 Email: msk@cloudmark.com