idnits 2.17.1 draft-ietf-dkim-base-02.txt: -(2494): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 22. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2634. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2606. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2613. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2619. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 60 form feeds but 588 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1135 has weird spacing: '... email elec...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 22, 2006) is 6548 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'MIME' is mentioned on line 2477, but not defined ** Obsolete normative reference: RFC 2821 (Obsoleted by RFC 5321) ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) == Outdated reference: A later version (-20) exists of draft-kucherawy-sender-auth-header-02 -- Obsolete informational reference (is this intentional?): RFC 2440 (Obsoleted by RFC 4880) -- Obsolete informational reference (is this intentional?): RFC 3851 (Obsoleted by RFC 5751) Summary: 8 errors (**), 0 flaws (~~), 7 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DKIM E. Allman 3 Internet-Draft Sendmail, Inc. 4 Expires: November 23, 2006 J. Callas 5 PGP Corporation 6 M. Delany 7 M. Libbey 8 Yahoo! Inc 9 J. Fenton 10 M. Thomas 11 Cisco Systems, Inc. 12 May 22, 2006 14 DomainKeys Identified Mail Signatures (DKIM) 15 draft-ietf-dkim-base-02 17 Status of this Memo 19 By submitting this Internet-Draft, each author represents that any 20 applicable patent or other IPR claims of which he or she is aware 21 have been or will be disclosed, and any of which he or she becomes 22 aware will be disclosed, in accordance with Section 6 of BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on November 23, 2006. 42 Copyright Notice 44 Copyright (C) The Internet Society (2006). 46 Abstract 48 DomainKeys Identified Mail (DKIM) defines a domain-level 49 authentication framework for email using public-key cryptography and 50 key server technology to permit verification of the source and 51 contents of messages by either Mail Transfer Agents (MTAs) or Mail 52 User Agents (MUAs). The ultimate goal of this framework is to permit 53 a signing domain to assert responsibility for a message, thus proving 54 and protecting message sender identity and the integrity of the 55 messages they convey while retaining the functionality of Internet 56 email as it is known today. Proof and protection of email identity, 57 including repudiation and non-repudiation, may assist in the global 58 control of "spam" and "phishing". 60 Requirements Language 62 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 63 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 64 document are to be interpreted as described in [RFC2119]. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 69 1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 1.2 Signing Identity . . . . . . . . . . . . . . . . . . . . . 6 71 1.3 Scalability . . . . . . . . . . . . . . . . . . . . . . . 6 72 1.4 Simple Key Management . . . . . . . . . . . . . . . . . . 6 73 2. Terminology and Definitions . . . . . . . . . . . . . . . . 6 74 2.1 Signers . . . . . . . . . . . . . . . . . . . . . . . . . 7 75 2.2 Verifiers . . . . . . . . . . . . . . . . . . . . . . . . 7 76 2.3 White Space . . . . . . . . . . . . . . . . . . . . . . . 7 77 2.4 Common ABNF Tokens . . . . . . . . . . . . . . . . . . . . 7 78 2.5 Imported ABNF Tokens . . . . . . . . . . . . . . . . . . . 8 79 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . 8 80 3.1 Selectors . . . . . . . . . . . . . . . . . . . . . . . . 8 81 3.2 Tag=Value Lists . . . . . . . . . . . . . . . . . . . . . 10 82 3.3 Signing and Verification Algorithms . . . . . . . . . . . 11 83 3.4 Canonicalization . . . . . . . . . . . . . . . . . . . . . 12 84 3.5 The DKIM-Signature header field . . . . . . . . . . . . . 17 85 3.6 Key Management and Representation . . . . . . . . . . . . 24 86 3.7 Computing the Message Hashes . . . . . . . . . . . . . . . 28 87 4. Semantics of Multiple Signatures . . . . . . . . . . . . . . 29 88 5. Signer Actions . . . . . . . . . . . . . . . . . . . . . . . 30 89 5.1 Determine if the Email Should be Signed and by Whom . . . 30 90 5.2 Select a private-key and corresponding selector 91 information . . . . . . . . . . . . . . . . . . . . . . . 30 92 5.3 Normalize the Message to Prevent Transport Conversions . . 31 93 5.4 Determine the header fields to Sign . . . . . . . . . . . 31 94 5.5 Compute the Message Hash and Signature . . . . . . . . . . 33 95 5.6 Insert the DKIM-Signature header field . . . . . . . . . . 34 96 6. Verifier Actions . . . . . . . . . . . . . . . . . . . . . . 35 97 6.1 Extract the Signature from the Message . . . . . . . . . . 36 98 6.2 Get the Public Key . . . . . . . . . . . . . . . . . . . . 37 99 6.3 Compute the Verification . . . . . . . . . . . . . . . . . 38 100 6.4 Communicate Verification Results . . . . . . . . . . . . . 40 101 6.5 Interpret Results/Apply Local Policy . . . . . . . . . . . 40 102 6.6 MUA Considerations . . . . . . . . . . . . . . . . . . . . 41 103 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 42 104 8. Security Considerations . . . . . . . . . . . . . . . . . . 42 105 8.1 Misuse of Body Length Limits ("l=" Tag) . . . . . . . . . 43 106 8.2 Misappropriated Private Key . . . . . . . . . . . . . . . 43 107 8.3 Key Server Denial-of-Service Attacks . . . . . . . . . . . 44 108 8.4 Attacks Against DNS . . . . . . . . . . . . . . . . . . . 44 109 8.5 Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 45 110 8.6 Limits on Revoking Keys . . . . . . . . . . . . . . . . . 46 111 8.7 Intentionally malformed Key Records . . . . . . . . . . . 46 112 8.8 Intentionally Malformed DKIM-Signature header fields . . . 46 113 8.9 Information Leakage . . . . . . . . . . . . . . . . . . . 46 114 8.10 Remote Timing Attacks . . . . . . . . . . . . . . . . . 46 115 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 116 9.1 Normative References . . . . . . . . . . . . . . . . . . . 47 117 9.2 Informative References . . . . . . . . . . . . . . . . . . 47 118 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 48 119 A. Example of Use (INFORMATIVE) . . . . . . . . . . . . . . . . 49 120 A.1 The user composes an email . . . . . . . . . . . . . . . . 50 121 A.2 The email is signed . . . . . . . . . . . . . . . . . . . 50 122 A.3 The email signature is verified . . . . . . . . . . . . . 51 123 B. Usage Examples (INFORMATIVE) . . . . . . . . . . . . . . . . 52 124 B.1 Simple Message Forwarding . . . . . . . . . . . . . . . . 52 125 B.2 Outsourced Business Functions . . . . . . . . . . . . . . 52 126 B.3 PDAs and Similar Devices . . . . . . . . . . . . . . . . . 52 127 B.4 Mailing Lists . . . . . . . . . . . . . . . . . . . . . . 53 128 B.5 Affinity Addresses . . . . . . . . . . . . . . . . . . . . 53 129 B.6 Third-party Message Transmission . . . . . . . . . . . . . 54 130 C. Creating a public key (INFORMATIVE) . . . . . . . . . . . . 54 131 D. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 56 132 E. Edit History . . . . . . . . . . . . . . . . . . . . . . . . 56 133 E.1 Changes since -ietf-01 version . . . . . . . . . . . . . . 56 134 E.2 Changes since -ietf-00 version . . . . . . . . . . . . . . 57 135 E.3 Changes since -allman-01 version . . . . . . . . . . . . . 57 136 E.4 Changes since -allman-00 version . . . . . . . . . . . . . 58 137 Intellectual Property and Copyright Statements . . . . . . . 59 139 1. Introduction 141 [[Note: text in double square brackets (such as this text) will be 142 deleted before publication.]] 144 1.1 Overview 146 DomainKeys Identified Mail (DKIM) defines a mechanism by which email 147 messages can be cryptographically signed, permitting a signing domain 148 to claim responsibility for the introduction of a message into the 149 mail stream. Message recipients can verify the signature by querying 150 the signer's domain directly to retrieve the appropriate public key, 151 and thereby confirm that the message was attested to by a party in 152 possession of the private key for the signing domain. 154 The approach taken by DKIM differs from previous approaches to 155 message signing (e.g. S/MIME [RFC1847], OpenPGP [RFC2440]) in that: 157 o the message signature is written as a message header field so that 158 neither human recipients nor existing MUA (Mail User Agent) 159 software are confused by signature-related content appearing in 160 the message body, 162 o there is no dependency on public and private key pairs being 163 issued by well-known, trusted certificate authorities, 165 o there is no dependency on the deployment of any new Internet 166 protocols or services for public key distribution or revocation, 168 o it makes no attempt to include encryption as part of the 169 mechanism. 171 DKIM: 173 o is compatible with the existing email infrastructure and 174 transparent to the fullest extent possible 176 o requires minimal new infrastructure 178 o can be implemented independently of clients in order to reduce 179 deployment time 181 o does not require the use of a trusted third party (such as a 182 certificate authority or other entity) which might impose 183 significant costs or introduce delays to deployment 185 o can be deployed incrementally 186 o allows delegation of signing to third parties 188 o is not intended be used for archival purposes 190 A "selector" mechanism allows multiple keys per domain, including 191 delegation of the right to authenticate a portion of the namespace to 192 a trusted third party. 194 1.2 Signing Identity 196 DKIM separates the question of the identity of the signer of the 197 message from the purported author of the message. In particular, a 198 signature includes the identity of the signer. Verifiers can use the 199 signing information to decide how they want to process the message. 201 INFORMATIVE RATIONALE: The signing address associated with a DKIM 202 signature is not required to match a particular header field 203 because of the broad methods of interpretation by recipient mail 204 systems, including MUAs. 206 1.3 Scalability 208 DKIM is designed to support the extreme scalability requirements 209 which characterize the email identification problem. There are 210 currently over 70 million domains and a much larger number of 211 individual addresses. DKIM seeks to preserve the positive aspects of 212 the current email infrastructure, such as the ability for anyone to 213 communicate with anyone else without introduction. 215 1.4 Simple Key Management 217 DKIM differs from traditional hierarchical public-key systems in that 218 no key signing infrastructure is required; the verifier requests the 219 public key from the claimed signer directly. 221 The DNS is proposed as the initial mechanism for publishing public 222 keys. DKIM is designed to be extensible to other key fetching 223 services as they become available. 225 2. Terminology and Definitions 227 This section defines terms used in the rest of the document. Syntax 228 descriptions use the form described in Augmented BNF for Syntax 229 Specifications [RFC4234]. 231 2.1 Signers 233 Elements in the mail system that sign messages are referred to as 234 signers. These may be MUAs (Mail User Agents), MSAs (Mail Submission 235 Agents), MTAs (Mail Transfer Agents), or other agents such as mailing 236 list exploders. In general any signer will be involved in the 237 injection of a message into the message system in some way. The key 238 issue is that a message must be signed before it leaves the 239 administrative domain of the signer. 241 2.2 Verifiers 243 Elements in the mail system that verify signatures are referred to as 244 verifiers. These may be MTAs, Mail Delivery Agents (MDAs), or MUAs. 245 In most cases it is expected that verifiers will be close to an end 246 user (reader) of the message or some consuming agent such as a 247 mailing list exploder. 249 2.3 White Space 251 There are three forms of white space: 253 o WSP represents simple white space, i.e., a space or a tab 254 character, and is inherited from[RFC2822]. 256 o SWSP is streaming white space; it adds the CR and LF characters. 258 o FWS, also from [RFC2822], is folding white space. It allows 259 multiple lines separated by CRLF followed by at least one white 260 space, to be joined. 262 The formal ABNF for SWSP is: 264 SWSP = CR / LF / WSP ; streaming white space 266 2.4 Common ABNF Tokens 268 The following ABNF tokens are used elsewhere in this document. 270 hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] 271 base64string = 1*(ALPHA / DIGIT / "+" / "/" / "=" / SWSP) 273 2.5 Imported ABNF Tokens 275 The following tokens are imported from other RFCs as noted. Those 276 RFCs should be considered definitive. However, all tokens having 277 names beginning with "obs-" should be excluded from this import, as 278 they have been obsoleted and are expected to go away in future 279 editions of those RFCs. 281 The following tokens are imported from [RFC2821]: 283 o Local-part (implementation warning: this permits quoted strings) 285 o Domain (implementation warning: this permits address-literals) 287 o sub-domain 289 The following definitions are imported from [RFC2822]: 291 o WSP (space or tab) 293 o FWS (folding white space) 295 o field-name (name of a header field) 297 o dot-atom (in the local-part of an email address) 299 The following tokens are imported from [RFC2045]: 301 o qp-section (a single line of quoted-printable-encoded text) 303 Other tokens not defined herein are imported from [RFC4234]. These 304 are intuitive primitives such as SP, ALPHA, CRLF, etc. 306 3. Protocol Elements 308 Protocol Elements are conceptual parts of the protocol that are not 309 specific to either signers or verifiers. The protocol descriptions 310 for signers and verifiers are described in later sections (Signer 311 Actions (Section 5) and Verifier Actions (Section 6)). NOTE: This 312 section must be read in the context of those sections. 314 3.1 Selectors 316 To support multiple concurrent public keys per signing domain, the 317 key namespace is subdivided using "selectors". For example, 318 selectors might indicate the names of office locations (e.g., 319 "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date 320 (e.g., "january2005", "february2005", etc.), or even the individual 321 user. 323 Selectors are needed to support some important use cases. For 324 example: 326 o Domains which want to delegate signing capability for a specific 327 address for a given duration to a partner, such as an advertising 328 provider or other outsourced function. 330 o Domains which want to allow frequent travelers to send messages 331 locally without the need to connect with a particular MSA. 333 o "Affinity" domains (e.g., college alumni associations) which 334 provide forwarding of incoming mail but which do not operate a 335 mail submission agent for outgoing mail. 337 Periods are allowed in selectors and are component separators. If 338 keys are stored in DNS, the period defines sub-domain boundaries. 339 Sub-selectors might be used to combine dates with locations; for 340 example, "march2005.reykjavik". This can be used to allow delegation 341 of a portion of the selector name-space. 343 ABNF: 344 selector = sub-domain *( "." sub-domain ) 346 The number of public keys and corresponding selectors for each domain 347 are determined by the domain owner. Many domain owners will be 348 satisfied with just one selector whereas administratively distributed 349 organizations may choose to manage disparate selectors and key pairs 350 in different regions or on different email servers. 352 Beyond administrative convenience, selectors make it possible to 353 seamlessly replace public keys on a routine basis. If a domain 354 wishes to change from using a public key associated with selector 355 "january2005" to a public key associated with selector 356 "february2005", it merely makes sure that both public keys are 357 advertised in the public-key repository concurrently for the 358 transition period during which email may be in transit prior to 359 verification. At the start of the transition period, the outbound 360 email servers are configured to sign with the "february2005" private- 361 key. At the end of the transition period, the "january2005" public 362 key is removed from the public-key repository. 364 While some domains may wish to make selector values well known, 365 others will want to take care not to allocate selector names in a way 366 that allows harvesting of data by outside parties. E.g., if per-user 367 keys are issued, the domain owner will need to make the decision as 368 to whether to make this selector associated directly with the user 369 name, or make it some unassociated random value, such as a 370 fingerprint of the public key. 372 INFORMATIVE IMPLEMENTERS' NOTE: reusing a selector with a new key 373 (for example, changing the key associated with a user's name) 374 makes it impossible to tell the difference between a message that 375 didn't verify because the key is no longer valid versus a message 376 that is actually forged. Signers should not change the key 377 associated with a selector. When creating a new key, signers 378 should associate it with a new selector. 380 3.2 Tag=Value Lists 382 DKIM uses a simple "tag=value" syntax in several contexts, including 383 in messages, domain signature records, and policy records. 385 Values are a series of strings containing either base64 text, plain 386 text, or quoted printable text, as defined in [RFC2045], section 6.7. 387 The name of the tag will determine the encoding of each value; 388 however, no encoding may include the semicolon (";") character, since 389 that separates tag-specs. 391 Formally, the syntax rules are: 392 tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] 393 tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] 394 tag-name = ALPHA 0*ALNUMPUNC 395 tag-value = 0*VALCHAR ; SWSP prohibited at beginning and end 396 VALCHAR = %9 / %d32 - %d58 / %d60 - %d126 397 ; HTAB and SP to TILDE except SEMICOLON 398 ALNUMPUNC = ALPHA / DIGIT / "_" 400 Note that WSP is allowed anywhere around tags; in particular, WSP 401 between the tag-name and the "=", and any WSP before the terminating 402 ";" is not part of the value. 404 Tags MUST be interpreted in a case-sensitive manner. Values MUST be 405 processed as case sensitive unless the specific tag description of 406 semantics specifies case insensitivity. 408 Tags with duplicate names MUST NOT be specified within a single tag- 409 list. 411 Whitespace within a value MUST be retained unless explicitly excluded 412 by the specific tag description. 414 Tag=value pairs that represent the default value MAY be included to 415 aid legibility. 417 Unrecognized tags MUST be ignored. 419 Tags that have an empty value are not the same as omitted tags. An 420 omitted tag is treated as having the default value; a tag with an 421 empty value explicitly designates the empty string as the value. For 422 example, "g=" does not mean "g=*", even though "g=*" is the default 423 for that tag. 425 3.3 Signing and Verification Algorithms 427 DKIM supports multiple key signing/verification algorithms. Two 428 algorithms are defined by this specification at this time: rsa-sha1, 429 and rsa-sha256. The rsa-sha256 algorithm is the default if no 430 algorithm is specified. Verifiers MUST implement both rsa-sha1 and 431 rsa-sha256. Signers MUST implement and SHOULD sign using rsa-sha256. 433 3.3.1 The rsa-sha1 Signing Algorithm 435 The rsa-sha1 Signing Algorithm computes a message hash as described 436 in Section 3.7 below using SHA-1 as the hash-alg. That hash is then 437 signed by the signer using the RSA algorithm (defined in PKCS#1 438 version 1.5 [RFC3447]; in particular see section 5.2) with an 439 exponent of 65537 as the crypt-alg and the signer's private key. The 440 hash MUST NOT be truncated or converted into any form other than the 441 native binary form before being signed. 443 3.3.2 The rsa-sha256 Signing Algorithm 445 The rsa-sha256 Signing Algorithm computes a message hash as described 446 in Section 3.7 below using SHA-256 as the hash-alg. That hash is 447 then signed by the signer using the RSA algorithm (actually PKCS#1 448 version 1.5 [RFC3447]; in particular see section 5.2) with an 449 exponent of 65537 as the crypt-alg and the signer's private key. The 450 hash MUST NOT be truncated or converted into any form other than the 451 native binary form before being signed. 453 3.3.3 Other algorithms 455 Other algorithms MAY be defined in the future. Verifiers MUST ignore 456 any signatures using algorithms that they do not understand. 458 3.3.4 Key sizes 460 Selecting appropriate key sizes is a trade-off between cost, 461 performance and risk. Since short RSA keys more easily succumb to 462 off-line attacks, signers MUST use RSA keys of at least 1024 bits for 463 long-lived keys. Verifiers MUST be able to validate signatures with 464 keys ranging from 512 bits to 2048 bits, and they MAY be able to 465 validate signatures with larger keys. Security policies may use the 466 length of the signing key as one metric for determining whether a 467 signature is acceptable. 469 Factors that should influence the key size choice include: 471 o The practical constraint that large keys may not fit within a 512 472 byte DNS UDP response packet 474 o The security constraint that keys smaller than 1024 bits are 475 subject to off-line attacks 477 o Larger keys impose higher CPU costs to verify and sign email 479 o Keys can be replaced on a regular basis, thus their lifetime can 480 be relatively short 482 o The security goals of this specification are modest compared to 483 typical goals of public-key systems 485 See RFC3766 [RFC3766] for further discussion of selecting key sizes. 487 3.4 Canonicalization 489 Empirical evidence demonstrates that some mail servers and relay 490 systems modify email in transit, potentially invalidating a 491 signature. There are two competing perspectives on such 492 modifications. For most signers, mild modification of email is 493 immaterial to the authentication status of the email. For such 494 signers a canonicalization algorithm that survives modest in-transit 495 modification is preferred. 497 Other signers demand that any modification of the email, however 498 minor, result in an authentication failure. These signers prefer a 499 canonicalization algorithm that does not tolerate in-transit 500 modification of the signed email. 502 Some signers may be willing to accept modifications to header fields 503 that are within the bounds of email standards such as [RFC2822], but 504 are unwilling to accept any modification to the body of messages. 506 To satisfy all requirements, two canonicalization algorithms are 507 defined for each of the header and the body: a "simple" algorithm 508 that tolerates almost no modification and a "relaxed" algorithm that 509 tolerates common modifications such as white-space replacement and 510 header field line re-wrapping. A signer MAY specify either algorithm 511 for header or body when signing an email. If no canonicalization 512 algorithm is specified by the signer, the "simple" algorithm defaults 513 for both header and body. Verifiers MUST implement both 514 canonicalization algorithms. Further canonicalization algorithms MAY 515 be defined in the future; verifiers MUST ignore any signatures that 516 use unrecognized canonicalization algorithms. 518 In all cases, the header fields of the message are presented to the 519 signing algorithm first in the order indicated by the signature 520 header field and canonicalized using the indicated algorithm. Only 521 header fields listed as signed in the signature header field are 522 included. Note: the signature header field itself is presented at 523 the end of the hash, not with the other headers. The CRLF separating 524 the header field from the body is then presented, followed by the 525 canonicalized body. Note that the header and body may use different 526 canonicalization algorithms. 528 Canonicalization simply prepares the email for presentation to the 529 signing or verification algorithm. It MUST NOT change the 530 transmitted data in any way. Canonicalization of header fields and 531 body are described below. 533 NOTE: This section assumes that the message is already in "network 534 normal" format (e.g., text is ASCII encoded, lines are separated with 535 CRLF characters, etc.). See also Section 5.3 for information about 536 normalizing the message. 538 3.4.1 The "simple" Header Field Canonicalization Algorithm 540 The "simple" header canonicalization algorithm does not change header 541 fields in any way. Header fields MUST be presented to the signing or 542 verification algorithm exactly as they are in the message being 543 signed or verified. In particular, header field names MUST NOT be 544 case folded and white space MUST NOT be changed. 546 3.4.2 The "relaxed" Header Field Canonicalization Algorithm 548 The "relaxed" header canonicalization algorithm MUST apply the 549 following steps in order: 551 o Convert all header field names (not the header field values) to 552 lower case. For example, convert "SUBJect: AbC" to "subject: 553 AbC". 555 o Unfold all header field continuation lines as described in 556 [RFC2822]; in particular, lines with terminators embedded in 557 continued header field values (that is, CRLF sequences followed by 558 WSP) MUST be interpreted without the CRLF. Implementations MUST 559 NOT remove the CRLF at the end of the header field value. 561 o Convert all sequences of one or more WSP characters to a single SP 562 character. WSP characters here include those before and after a 563 line folding boundary. 565 o Delete all WSP characters at the end of each unfolded header field 566 value. 568 o Delete any WSP characters remaining before and after the colon 569 separating the header field name from the header field value. The 570 colon separator MUST be retained. 572 3.4.3 The "simple" Body Canonicalization Algorithm 574 The "simple" body canonicalization algorithm ignores all empty lines 575 at the end of the message body. An empty line is a line of zero 576 length after removal of the line terminator. It makes no other 577 changes to the message body. In more formal terms, the "simple" body 578 canonicalization algorithm reduces "CRLF 0*CRLF" at the end of the 579 body to a single "CRLF". 581 3.4.4 The "relaxed" Body Canonicalization Algorithm 583 [[This section may be deleted; see discussion below.]] The "relaxed" 584 body canonicalization algorithm: 586 o Ignores all white space at the end of lines. Implementations MUST 587 NOT remove the CRLF at the end of the line. 589 o Reduces all sequences of WSP within a line to a single SP 590 character. 592 o Ignores all empty lines at the end of the message body. "Empty 593 line" is defined in Section 3.4.3. 595 [[NON-NORMATIVE DISCUSSION: The authors are undecided whether to 596 leave the "relaxed" body canonicalization algorithm in to the 597 specification or delete it entirely. We believe that for the vast 598 majority of cases, the "simple" body canonicalization algorithm 599 should be sufficient. We simply do not have enough data to know 600 whether to retain the "relaxed" body canonicalization algorithm or 601 not.]] 603 3.4.5 Body Length Limits 605 A body length count MAY be specified to limit the signature 606 calculation to an initial prefix of the body text. If the body 607 length count is not specified then the entire message body is signed 608 and verified. 610 INFORMATIVE IMPLEMENTATION NOTE: Body length limits could be 611 useful in increasing signature robustness when sending to a 612 mailing list that both appends to content sent to it and does not 613 sign its messages. However, using such limits enables an attack 614 in which a sender with malicious intent modifies a message to 615 include content that solely benefits the attacker. It is possible 616 for the appended content to completely replace the original 617 content in the end recipient's eyes and to defeat duplicate 618 message detection algorithms. To avoid this attack, signers 619 should be wary of using this tag, and verifiers might wish to 620 ignore the tag or remove text that appears after the specified 621 content length, perhaps based on other criteria. 623 The body length count allows the signer of a message to permit data 624 to be appended to the end of the body of a signed message. The body 625 length count is made following the canonicalization algorithm; for 626 example, any white space ignored by a canonicalization algorithm is 627 not included as part of the body length count. 629 INFORMATIVE RATIONALE: This capability is provided because it is 630 very common for mailing lists to add trailers to messages (e.g., 631 instructions how to get off the list). Until those messages are 632 also signed, the body length count is a useful tool for the 633 verifier since it may as a matter of policy accept messages having 634 valid signatures with extraneous data. 636 Signers of MIME messages that include a body length count SHOULD be 637 sure that the length extends to the closing MIME boundary string. 639 INFORMATIVE IMPLEMENTATION NOTE: A signer wishing to ensure that 640 the only acceptable modifications are to add to the MIME postlude 641 would use a body length count encompassing the entire final MIME 642 boundary string, including the final "--CRLF". A signer wishing 643 to allow additional MIME parts but not modification of existing 644 parts would use a body length count extending through the final 645 MIME boundary string, omitting the final "--CRLF". 647 A body length count of zero means that the body is completely 648 unsigned. 650 Note that verifiers MAY choose to truncate messages that have body 651 content beyond that specified by the body length count. 652 Alternatively, verifiers MAY ignore signatures that do not cover the 653 entire message body. 655 Signers wishing to ensure that no modification of any sort can occur 656 should specify the "simple" algorithm and omit the body length count. 658 3.4.6 Example 660 (In the following examples, actual white space is used only for 661 clarity. The actual input and output text is designated using 662 bracketed descriptors: "" for a space character, "" for a 663 tab character, and "" for a carriage-return/line-feed sequence. 664 For example, "X Y" and "XY" represent the same three 665 characters.) 667 Example 1: A message reading: 668 A: X 669 B : Y 670 Z 671 672 C 673 D E 674 675 677 when canonicalized using relaxed canonicalization for both header and 678 body results in a header reading: 679 a:X 680 b:Y Z 682 and a body reading: 683 C 684 D E 685 (postamble) 687 Example 2: The same message canonicalized using simple 688 canonicalization for both header and body results in a header 689 reading: 690 A: X 691 B : Y 692 Z 694 and a body reading: 695 C 696 D E 697 (postamble) 699 Example 3: When processed using relaxed header canonicalization and 700 simple body canoniccalization, the canonicalized version has a header 701 of: 703 a:X 704 b:Y Z 706 and a body reading: 707 C 708 D E 709 (postamble) 711 3.5 The DKIM-Signature header field 713 The signature of the email is stored in the "DKIM-Signature:" header 714 field. This header field contains all of the signature and key- 715 fetching data. The DKIM-Signature value is a tag-list as described 716 in Section 3.2. 718 The "DKIM-Signature:" header field SHOULD be treated as though it 719 were a trace header field as defined in section 3.6 of [RFC2822], and 720 hence SHOULD NOT be reordered and SHOULD be prepended to the message. 721 In particular, the "DKIM-Signature" header field SHOULD precede the 722 original email header fields presented to the canonicalization and 723 signature algorithms. 725 The "DKIM-Signature:" header field is always included in the 726 signature calculation, after the body of the message; however, when 727 calculating or verifying the signature, the value of the b= tag 728 (signature value) MUST be treated as though it were the null string. 729 Unknown tags MUST be signed and verified but MUST be otherwise 730 ignored by verifiers. 732 The encodings for each field type are listed below. Tags described 733 as quoted-printable are as described in section 6.7 of MIME Part One 734 [RFC2045], with the additional conversion of semicolon characters to 735 "=3B". 737 Tags on the DKIM-Signature header field along with their type and 738 requirement status are shown below. Defined tags are described 739 below. Unrecognized tags MUST be ignored. 741 v= Version (MUST be included). This tag defines the version of 742 this specification that applies to the signature record. It MUST 743 have the value 0.2. 745 ABNF: 747 sig-v-tag = %x76 [FWS] "=" [FWS] "0.2" 748 a= The algorithm used to generate the signature (plain-text; 749 REQUIRED). Verifiers MUST support "rsa-sha1" and "rsa-sha256"; 750 signers SHOULD sign using "rsa-sha256". See Section 3.3 for a 751 description of algorithms. 753 ABNF: 755 sig-a-tag = %x61 [FWS] "=" [FWS] sig-a-tag-alg 756 sig-a-tag-alg = "rsa-sha1" / "rsa-sha256" / x-sig-a-tag-alg 757 x-sig-a-tag-alg = hyphenated-word ; for later extension 759 b= The signature data (base64; REQUIRED). Whitespace is ignored in 760 this value and MUST be ignored when re-assembling tthe original 761 signature. In particular, the signing process can safely insert 762 FWS in this value in arbitrary places to conform to line-length 763 limits. See Signer Actions (Section 5) for how the signature is 764 computed. 766 ABNF: 768 sig-b-tag = %x62 [FWS] "=" [FWS] sig-b-tag-data 769 sig-b-tag-data = base64string 771 bh= The hash of the body part of the message (base64; REQUIRED). 772 Whitespace is ignored in this value and MUST be ignored when re- 773 assembling the original signature. In particular, the signing 774 process can safely insert FWS in this value in arbitrary places 775 to conform to line-length limits. See Section 3.7 for how the 776 body hash is computed. 778 c= Message canonicalization (plain-text; OPTIONAL, default is 779 "simple/simple"). This tag informs the verifier of the type of 780 canonicalization used to prepare the message for signing. It 781 consists of two names separated by a "slash" (%d47) character, 782 corresponding to the header and body canonicalization algorithms 783 respectively. These algorithms are described in Section 3.4. If 784 only one algorithm is named, that algorithm is used for the 785 header and "simple" is used for the body. For example, 786 "c=relaxed" is treated the same as "c=relaxed/simple". 788 ABNF: 790 sig-c-tag = %x63 [FWS] "=" [FWS] sig-c-tag-alg 791 ["/" sig-c-tag-alg] 792 sig-c-tag-alg = "simple" / "relaxed" / x-sig-c-tag-alg 793 x-sig-c-tag-alg = hyphenated-word ; for later extension 795 d= The domain of the signing entity (plain-text; REQUIRED). This 796 is the domain that will be queried for the public key. This 797 domain MUST be the same as or a parent domain of the "i=" tag 798 (the signing identity, as described below). When presented with 799 a signature that does not meet this requirement, verifiers MUST 800 consider the signature invalid. 802 ABNF: 804 sig-d-tag = %x64 [FWS] "=" [FWS] Domain 806 h= Signed header fields (plain-text, but see description; 807 REQUIRED). A colon-separated list of header field names that 808 identify the header fields presented to the signing algorithm. 809 The field MUST contain the complete list of header fields in the 810 order presented to the signing algorithm. The field MAY contain 811 names of header fields that do not exist when signed; nonexistent 812 header fields do not contribute to the signature computation 813 (that is, they are treated as the null input, includiing the 814 header field name, the separating colon, the header field value, 815 and any CRLF terminator). The field MUST NOT include the DKIM- 816 Signature header field that is being created or verified. 817 Folding white space (FWS) MAY be included on either side of the 818 colon separator. Header field names MUST be compared against 819 actual header field names in a case insensitive manner. This 820 list MUST NOT be empty. See Section 5.4 for a discussion of 821 choosing header fields to sign. 823 ABNF: 825 sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name 826 0*( *FWS ":" *FWS hdr-name ) 827 hdr-name = field-name 829 INFORMATIVE EXPLANATION: By "signing" header fields that do 830 not actually exist, a signer can prevent insertion of those 831 header fields before verification. However, since a sender 832 cannot possibly know what header fields might be created in 833 the future, and that some MUAs might present header fields 834 that are embedded inside a message (e.g., as a message/rfc822 835 content type), the security of this solution is not total. 837 INFORMATIVE EXPLANATION: The exclusion of the header field 838 name and colon as well as the header field value for non- 839 existent header fields prevents an attacker from inserting an 840 actual header field with a null value. 842 i= Identity of the user or agent (e.g., a mailing list manager) on 843 behalf of which this message is signed (quoted-printable; 844 OPTIONAL, default is an empty local-part followed by an "@" 845 followed by the domain from the "d=" tag). The syntax is a 846 standard email address where the local-part MAY be omitted. The 847 domain part of the address MUST be the same as or a subdomain of 848 the value of the "d=" tag. 850 ABNF: 852 sig-i-tag = %x69 [FWS] "=" [FWS] [ Local-part ] "@" Domain 854 INFORMATIVE NOTE: The local-part of the "i=" tag is optional 855 because in some cases a signer may not be able to establish a 856 verified individual identity. In such cases, the signer may 857 wish to assert that although it is willing to go as far as 858 signing for the domain, it is unable or unwilling to commit 859 to an individual user name within their domain. It can do so 860 by including the domain part but not the local-part of the 861 identity. 863 INFORMATIVE DISCUSSION: This document does not require the 864 value of the "i=" tag to match the identity in any message 865 header field fields. This is considered to be a verifier 866 policy issue. Constraints between the value of the "i=" tag 867 and other identities in other header fields seek to apply 868 basic authentication into the semantics of trust associated 869 with a role such as content author. Trust is a broad and 870 complex topic and trust mechanisms are subject to highly 871 creative attacks. The real-world efficacy of any but the 872 most basic bindings between the "i=" value and other 873 identities is not well established, nor is its vulnerability 874 to subversion by an attacker. Hence reliance on the use of 875 these options should be strictly limited. In particular it 876 is not at all clear to what extent a typical end-user 877 recipient can rely on any assurances that might be made by 878 successful use of the "i=" options. 880 l= Body count (plain-text decimal integer; OPTIONAL, default is 881 entire body). This tag informs the verifier of the number of 882 bytes in the body of the email after canonicalization included in 883 the cryptographic hash, starting from 0 immediately following the 884 CRLF preceding the body. 886 INFORMATIVE IMPLEMENTATION WARNING: Use of the l= tag might 887 allow display of fraudulent content without appropriate 888 warning to end users. The l= tag is intended for increasing 889 signature robustness when sending to mailing lists that both 890 modify their content and do not sign their messages. 891 However, using the l= tag enables man-in-the-middle attacks 892 in which an intermediary with malicious intent modifies a 893 message to include content that solely benefits the attacker. 894 It is possible for the appended content to completely replace 895 the original content in the end recipient's eyes and to 896 defeat duplicate message detection algorithms. Examples are 897 described in Security Considerations (Section 8). 899 To avoid this attack, signers should be extremely wary of 900 using this tag, and verifiers might wish to ignore the tag or 901 remove text that appears after the specified content length. 903 ABNF: 905 sig-l-tag = %x6c [FWS] "=" [FWS] 1*DIGIT 907 q= A colon-separated list of query methods used to retrieve the 908 public key (plain-text; OPTIONAL, default is "dns/txt"). Each 909 query method is of the form "type[/options]", where the syntax 910 and semantics of the options depends on the type and specified 911 options. If there are multiple query mechanisms listed, the 912 choice of query mechanism MUST NOT change the interpretation of 913 the signature. Implementations MUST use the recognized query 914 mechanisms in the order presented. 916 Currently the only valid value is "dns/txt" which defines the DNS 917 TXT record lookup algorithm described elsewhere in this document. 918 The only option defined for the "dns" query type is "txt", which 919 MUST be included. Verifiers and signers MUST support "dns/txt". 921 ABNF: 923 sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 924 *([FWS] ":" [FWS] sig-q-tag-method) 925 sig-q-tag-method = sig-q-tag-type ["/" sig-q-tag-args] 926 sig-q-tag-type = "dns" / x-sig-q-tag-type 927 x-sig-q-tag-type = hyphenated-word ; for future extension 928 x-sig-q-tag-args = qp-hdr-value 930 s= The selector subdividing the namespace for the "d=" (domain) tag 931 (plain-text; REQUIRED). 933 ABNF: 935 sig-s-tag = %x73 [FWS] "=" [FWS] subdomain *( "." sub-domain ) 937 t= Signature Timestamp (pplain-text; RECOMMENDED, default is an 938 unknown creation time). The time that this signature was 939 created. The format is the number of seconds since 00:00:00 on 940 January 1, 1970 in the UTC time zone. The value is expressed as 941 an unsigned integer in decimal ASCII. This value is not 942 constrained to fit into a 31- or 32-bit integer. Implementations 943 SHOULD be prepared to handle values up to at least 10^12 (until 944 approximately AD 200,000; this fits into 40 bits). To avoid 945 denial of service attacks, implementations MAY consider any value 946 longer than 12 digits to be infinite. 948 ABNF: 950 sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT 952 x= Signature Expiration (plain-text; RECOMMENDED, default is no 953 expiration). The format is the same as in the "t=" tag, 954 represented as an absolute date, not as a time delta from the 955 signing timestamp. The value is expressed as an unsigned integer 956 in decimal ASCII, with the same contraints on the value in the 957 "t=" tag. Signatures MAY be considered invalid if the 958 verification time at the verifier is past the expiration date. 959 The verification time should be the time that the message was 960 first received at the administrative domain of the verifier if 961 that time is reliably available; otherwise the current time 962 should be used. The value of the "x=" tag MUST be greater than 963 the value of the "t=" tag if both are present. 965 INFORMATIVE NOTE: The x= tag is not intended as an anti- 966 replay defense. 968 ABNF: 970 sig-x-tag = %x78 [FWS] "=" [FWS] 1*12DIGIT 972 z= Copied header fields (plain-text, but see description; OPTIONAL, 973 default is null). A vertical-bar-separated list of selected 974 header field names and copies of header field values present when 975 the message was signed. It is not required to include all header 976 fields present at the time of signing. This field need not 977 contain the same header fields listed in the "h=" tag. Copied 978 header field values MUST immediately follow the header field name 979 with a colon separator (no white space permitted). Header field 980 values MUST be represented as Quoted-Printable [RFC2045] with 981 vertical bars, colons, semicolons, and white space encoded in 982 addition to the usual requirements. 984 Verifiers MUST NOT use the header field names or copied values 985 for checking the signature in any way. Copied header field 986 values are for diagnostic use onnly. 988 Header fields with characters requiring conversion (perhaps from 989 legacy MTAs which are not [RFC2822] compliant) SHOULD be 990 converted as described in MIME Part Three [RFC2047]. 992 ABNF: 993 sig-z-tag = %x7A [FWS] "=" [FWS] sig-z-tag-copy 994 *( [FWS] "|" sig-z-tag-copy ) 995 sig-z-tag-copy = hdr-name ":" [FWS] qp-hdr-value 996 qp-hdr-value = 998 ; needs to be updated with real definition 999 ; (could be messy) 1001 INFORMATIVE EXAMPLE of a signature header field spread across 1002 multiple continuation lines: 1004 DKIM-Signature: a=rsa-sha1; d=example.net; s=brisbane 1005 c=simple; q=dns; i=@eng.example.net; t=1117574938; x=1118006938; 1006 h=from:to:subject:date; 1007 z=From:foo@eng.example.net|To:joe@example.com| 1008 Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700 1009 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 1010 VoG4ZHRNiYzR 1012 3.6 Key Management and Representation 1014 Signature applications require some level of assurance that the 1015 verification public key is associated with the claimed signer. Many 1016 applications achieve this by using public key certificates issued by 1017 a trusted third party. However, DKIM can achieve a sufficient level 1018 of security, with significantly enhanced scalability, by simply 1019 having the verifier query the purported signer's DNS entry (or some 1020 security-equivalent) in order to retrieve the public key. 1022 DKIM keys can potentially be stored in multiple types of key servers 1023 and in multiple formats. The storage and format of keys are 1024 irrelevant to the remainder of the DKIM algorithm. 1026 Parameters to the key lookup algorithm are the type of the lookup 1027 (the "q=" tag), the domain of the responsible signer (the "d=" tag of 1028 the DKIM-Signature header field), the signing identity (the "i=" 1029 tag), and the selector (the "s=" tag). The "i=" tag value could be 1030 ignored by some key services. 1032 public_key = dkim_find_key(q_val, d_val, i_val, s_val) 1034 This document defines a single binding, using DNS TXT records to 1035 distribute the keys. Other bindings may be defined in the future. 1037 3.6.1 Textual Representation 1039 It is expected that many key servers will choose to present the keys 1040 in an otherwise unstructured text format (for example, an XML form 1041 would not be considered to be unstructured text for this purpose). 1042 The following definition MMUST be used for any DKIM key represented in 1043 an otherwise unstructured textual form. 1045 The overall syntax is a key-value-list as described in Section 3.2. 1046 The current valid tags are described below. Other tags MAY be 1047 present and MUST be ignored by any implementation that does not 1048 understand them. 1050 v= Version of the DKIM key record (plain-text; RECOMMENDED, default 1051 is "DKIM1"). If specified, this tag MUST be set to "DKIM1" 1052 (without the quotes). This tag MUST be the first tag in the 1053 response. Responses beginning with a "v=" tag with any other 1054 value MUST be discarded. 1056 ABNF: 1058 key-v-tag = %x76 [FWS] "=" [FWS] "DKIM1" 1060 g= granularity of the key (plain-text; OPTIONAL, default is "*"). 1061 This value MUST match the local part of the signing address, with 1062 a "*" character acting as a wildcard. The intent of this tag is 1063 to constrain which signing address can legitimately use this 1064 selector. An email with a signing address that does not match 1065 the value of this tag constitutes a failed verification. 1066 Wildcarding allows matching for addresses such as "user+*". An 1067 empty "g=" value never matches any addresses. 1069 ABNF: 1071 key-g-tag = %x67 [FWS] "=" [FWS] key-g-tag-lpart 1072 key-g-tag-lpart = [dot-atom] ["*"] [dot-atom] 1074 [[NON-NORMATIVE DISCUSSION POINT: "*" is legal in a dot- 1075 atom. This should probably use a different character for 1076 wildcarding. Unfortunately, the options are non-mnemonic 1077 (e.g., "@", "(", ":"). Alternatively we could insist on 1078 escaping a "*" intended as a literal "*" in the address.]] 1080 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to 1081 allowing all algorithms). A colon-separated list of hash 1082 algorithms that might be used. Signers and Verifiers MUST 1083 support the "sha1" hash algorithm. 1085 ABNF: 1087 key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg 1088 0*( [FWS] ":" [FWS] key-h-tag-alg ) 1089 key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg 1090 x-key-h-tag-alg = hyphenated-word ; for future extension 1092 k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and 1093 verifiers MUST support the "rsa" key type. The "rsa" key type 1094 indicates that an RSA public key, as defined in [RFC3447], 1095 sections 3.1 and A.1.1, is being used in the p= tag. (Note: the 1096 p= tag further encodes the value using the base64 algorithm.) 1098 ABNF: 1100 key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type 1101 key-k-tag-type = "rsa" / x-key-k-tag-type 1102 x-key-k-tag-type = hyphenated-word ; for future extension 1104 [[NON-NORMATIVE DISCUSSION NOTE: In some cases it can be 1105 hard to separate h= and k=; for example DSA implies that 1106 SHA-1 will be used. This might be an actual change to the 1107 spec depending on how we decide to fix this.]] 1109 n= Notes that might be of interest to a human (quoted-printable; 1110 OPTIONAL, default is empty). No interpretation is made by any 1111 program. This tag should be used sparingly in any key server 1112 mechanism that has space limitations (notably DNS). 1114 ABNF: 1116 key-n-tag = %x6e [FWS] "=" [FWS] qp-section 1118 p= Public-key data (base64; REQUIRED). An empty value means that 1119 this public key has been revoked. The syntax and semantics of 1120 this tag value before being encoded in base64 is defined by the 1121 k= tag. 1123 ABNF: 1125 key-p-tag = %x70 [FWS] "=" [FWS] base64string 1127 s= Service Type (plain-text; OPTIONAL; default is "*"). A colon- 1128 separated list of service types to which this record applies. 1129 Verifiers for a given service type MUST ignore this record if the 1130 appropriate type is not listed. Currently defined service types 1131 are: 1133 * matches all service types 1135 email electronic mail (not necessarily limited to SMTP) 1137 This tag is intended to permit senders to constrain the use of 1138 delegated keys, e.g., where a company is willing to delegate the 1139 right to send mail in their name to an outsourcer, but not to 1140 send IM or make VoIP calls. (This of course presumes that these 1141 keys are used in other services in the future.) 1142 ABNF: 1144 key-s-tag = %x73 [FWS] "=" [FWS] key-s-tag-type 1145 0*( [FWS] ":" [FWS] key-s-tag-type 1146 key-s-tag-type = "email" / "*" / x-key-s-tag-type 1147 x-key-s-tag-type = hyphenated-word ; for future extension 1149 t= Flags, represented as a colon-separated list of names (plain- 1150 text; OPTIONAL, default is no flags set). The defined flags are: 1152 y This domain is testing DKIM. Verifiers MUST NOT treat 1153 messages from signers in testing mode differently from 1154 unsigned email, even should the signature fail to verify. 1155 Verifiers MAY wish to track testing modee results to assist 1156 the signer. 1158 ABNF: 1160 key-t-tag = %x74 [FWS] "=" [FWS] key-t-tag-flag 1161 0*( [FWS] ":" [FWS] key-t-tag-flag ) 1162 key-t-tag-flag = "y" / x-key-t-tag-flag 1163 x-key-t-tag-flag = hyphenated-word ; for future extension 1165 Unrecognized flags MUST be ignored. 1167 3.6.2 DNS binding 1169 A binding using DNS TXT records as a key service is hereby defined. 1170 All implementations MUST support this binding. 1172 3.6.2.1 Name Space 1174 All DKIM keys are stored in a subdomain named ""_domainkey"". Given 1175 a DKIM-Signature field with a "d=" tag of ""example.com"" and an "s=" 1176 tag of ""sample"", the DNS query will be for 1177 ""sample._domainkey.example.com"". 1179 The value of the "i=" tag is not used by the DNS binding. 1181 3.6.2.2 Resource Record Types for Key Storage 1183 The DNS Resource Record type used is specified by an option to the 1184 query-type ("q=") tag. The only option defined in this base 1185 specification is "/txt", indicating the use of a TXT RR record. A 1186 later extension of this standard may define another Resource Record 1187 type, tentatively dubbed "DKK". 1189 TXT records are encoded as described in Section 3.6.1. 1191 3.7 Computing the Message Hashes 1193 Both signing and verifying message signatures starts with a step of 1194 computing two cryptographic hashes over the message. Signers will 1195 choose the parameters of the signature as described in Signer Actions 1196 (Section 5); verifiers will use the parameters specified in the 1197 "DKIM-Signature" header field being verified. In the following 1198 discussion, the names of the tags in the "DKIM-Signature" header 1199 field which either exists (when verifying) or will be created (when 1200 signing) are used. Note that canonicalization (Section 3.4) is only 1201 used to prepare the email for signing or verifying; it does not 1202 affect the transmitted email in any way. 1204 The signer or verifier must compute two hashes, one over the body of 1205 the message and one over the header of the message. Signers MUST 1206 compute them in the order shown. Verifiers MAY compute them in any 1207 order convenient to the verifier, provided that the result is 1208 semantically identical to the semantics that would be the case had 1209 they been computed in this order. 1211 In hash step 1, the signer or verifier MUST hash the message body, 1212 canonicalized using the body canonicalization algorithm specified in 1213 the "c=" tag and truncated to the length specified in the "l=" tag. 1214 That hash value is then converted to base64 form and inserted into 1215 the "bh=" tag of the DKIMM-Signature: header field. 1217 In hash step 2, the signer or verifier MUST pass the following to the 1218 hash algorithm in the indicated order. 1220 1. The header fields specified by the "h=" tag, in the order 1221 specified in that tag, and canonicalized using the header 1222 canonicalization algorithm specified in the "c=" tag. Each 1223 header field must be terminated with a single CRLF. 1225 2. The "DKIM-Signature" header field that exists (verifying) or will 1226 be inserted (signing) in the message, with the value of the "b=" 1227 tag deleted (i.e., treated as the empty string), canonicalized 1228 using the header canonicalization algorithm specified in the "c=" 1229 tag, and without a trailing CRLF. 1231 All tags and their values in the DKIM-Signature header field are 1232 included in the cryptographic hash with the sole exception of the 1233 value portion of the "b=" (signature) tag, which MUST be treated as 1234 the null string. All tags MUST be included even if they might not be 1235 understood by the verifier. The header field MUST be presented to 1236 the hash algorithm after the body of the message rather than with the 1237 rest of the header fields and MUST be canonicalized as specified in 1238 the� "c=" (canonicalization) tag. The DKIM-Signature header field 1239 MUST NOT be included in its own h= tag. 1241 When calculating the hash on messages that will be transmitted using 1242 base64 or quoted-printable encoding, signers MUST compute the hash 1243 after the encoding. Likewise, the verifier MUST incorporate the 1244 values into the hash before decoding the base64 or quoted-printable 1245 text. However, the hash MUST be computed before transport level 1246 encodings such as SMTP "dot-stuffing." 1248 With the exception of the canonicalization procedure described in 1249 Section 3.4, the DKIM signing process treats the body of messages as 1250 simply a string of characters. DKIM messages MAY be either in plain- 1251 text or in MIME format; no special treatment is afforded to MIME 1252 content. Message attachments in MIME format MUST be included in the 1253 content which is signed. 1255 More formally, the algorithm for the signature is: 1256 body-hash = hash-alg(canon_body) 1257 header-hash = hash-alg(canon_header || DKIM-SIG) 1258 signature = crypt-alg(header-hash, key) 1260 where crypt-alg is the encryption algorithm specified by the "a=" 1261 tag, hash-alg is the hash algorithm specified by the "a=" tag, 1262 canon_header and canon_body are the canonicalized message header and 1263 body (respectively) as defined in Section 3.4 (excluding the DKIM- 1264 Signature header field), and DKIM-SIG is the canonicalized DKIM- 1265 Signature header field sans the signature value itself, but with 1266 body-hash included as the "bh=" tag. 1268 4. Semantics of Multiple Signatures 1270 A signer that is adding a signature to a message merely creates a new 1271 DKIM-Signature header, using the usual semantics of the h= option. A 1272 signer MAY sign previously existing DKIM-Signature headers using the 1273 method described in section Section 5.4 to sign trace headers. 1274 Signers should be cognizant that signing DKIM-Signature headers may 1275 result in signature failures with intermediaries that do not 1276 recognize that DKIM-Signature's are trace headers and unwittingly 1277 reorder them. 1279 When evaluating a message with multiple signatures, a receiver should 1280 evaluate signatures independently and on their own merits. For 1281 example, a receiver that by policy chooses not to accept signatures 1282 with deprecated crypto algorithms should consider such signatures 1283 invalid. As with messages with a single signature, receievers are at 1284 liberty to use the presence of valid signatures as an input to local 1285 policy; likewise, the interpretation of multiple valid signatures in 1286 combination is a local policy decision of the receiver. 1288 Signers SHOULD NOT remove any DKIM-Signature header fields from 1289 messages they are signing, even if they know that the signatures 1290 cannot be verified. 1292 5. Signer Actions 1294 The following steps are performed in order by signers. 1296 5.1 Determine if the Email Should be Signed and by Whom 1298 A signer can obviously only sign email for domains for which it has a 1299 private-key and the necessary knowledge of the corresponding public 1300 key and selector information. However there are a number of other 1301 reasons beyond the lack of a private key why a signer could choose 1302 not to sign an email. 1304 A SUBMISSION server MAY sign if the sender is authenticated by some 1305 secure means, e.g., SMTP AUTH. Within a trusted enclave the signing 1306 address MAY be derived from the header field according to local 1307 signer policy. Within a trusted enclave an MTA MAY do the signing. 1309 INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not 1310 sign Received header fields if the outgoing gateway MTA obfuscates 1311 Received header fields, for example to hide the details of 1312 internal topology. 1314 A signer MUST NOT sign an email if it is unwilling to be held 1315 responsible for the message; in particular, the signer SHOULD ensure 1316 that the submitter has a bona fide relationship with the signer and 1317 that the submitter has tthe right to use the address being claimed. 1319 If an email cannot be signed for some reason, it is a local policy 1320 decision as to what to do with that email. 1322 5.2 Select a private-key and corresponding selector information 1324 This specification does not define the basis by which a signer should 1325 choose which private-key and selector information to use. Currently, 1326 all selectors are equal as far as this specification is concerned, so 1327 the decision should largely be a matter of administrative 1328 convenience. Distribution and management of private-keys is also 1329 outside the scope of this document. 1331 A signer SHOULD NOT sign with a key that is expected to expire within 1332 seven days; that is, when rotating to a new key, signing should 1333 immediately commence with the new key and the old key SHOULD be 1334 retained for at least seven days before being removed from the key 1335 server. 1337 5.3 Normalize the Message to Prevent Transport Conversions 1339 Some messages, particularly those using 8-bit characters, are subject 1340 to modification during transit, notably conversion to 7-bit form. 1341 Such conversions will break DKIM signatures. In order to minimize 1342 the chances of such breakage, signers SHOULD convert the message to a 1343 suitable MIME content transfer encoding such as quoted-printable or 1344 base64 as described in MIME Part One [RFC2045] before signing. Such 1345 conversion is outside the scope of DKIM; the actual message SHOULD be 1346 converted to 7-bit MIME by an MUA or MSA prior to presentation to the 1347 DKIM algorithm. 1349 Should the message be submitted to the signer with any local encoding 1350 that will be modified before transmission, such conversion to 1351 canonical form MUST be done before signing. In particular, some 1352 systems use local line separator conventions (such as the Unix 1353 newline character) internally rather than the SMTP-standard CRLF 1354 sequence. All such local conventions MUST be converted to canonical 1355 format before signing. 1357 More generally, the signer MUST sign the message as it will be 1358 received by the verifier rather than in some local or internal form. 1360 5.4 Determine the header fields to Sign 1362 The From header field MUST be signed (that is, included in the h= tag 1363 of the resulting DKIM-Signature header field); any header field that 1364 describes the role of the signer (for example, the Sender or Resent- 1365 From header field if the signature is on behalf of the corresponding 1366 address and that address is different from the From address) MUST 1367 also be included. The signed header fields SHOULD also include the 1368 Subjectt and Date header fields as well as all MIME header fields. 1369 Signers SHOULD NOT sign an existing header field likely to be 1370 legitimately modified or removed in transit. In particular, 1371 [RFC2821] explicitly permits modification or removal of the "Return- 1372 Path" header field in transit. Signers MAY include any other header 1373 fields present at the time of signing at the discretion of the 1374 signer. It is RECOMMENDED that all other existing, non-repeatable 1375 header fields be signed. 1377 The DKIM-Signature header field is always implicitly signed and MUST 1378 NOT be included in the h= tag except to indicate that other 1379 preexisting signatures are also signed. 1381 Signers MUST sign any header fields that the signers wish to assert 1382 were present at the time of signing. Put another way, verifiers MAY 1383 treat unsigned header fields with extreme skepticism, up to and 1384 including refusing to display them to the end user. 1386 Signers MAY claim to have signed header fields that do not exist 1387 (that is, signers MAY include the header field name in the h= tag 1388 even if that header field does not exist in the message). When 1389 computing the signature, the non-existing header field MUST be 1390 treated as the null string (including the header field name, header 1391 field value, all punctuation, and the trailing CRLF). 1393 INFORMATIVE RATIONALE: This allows signers to explicitly assert 1394 the absence of a header field; if that header field is added later 1395 the signature will fail. 1397 Signers choosing to sign an existing replicated header field (such as 1398 Received) MUST sign the physically last instance of that header field 1399 in the header field block. Signers wishing to sign multiple 1400 instances of an existing replicated header field MUST include the 1401 header field name multiple times in the h= tag of the DKIM-Signature 1402 header field, and MUST sign such header fields in order from the 1403 bottom of the header field block to the top. The signer MAY include 1404 more header field names than there are actual corresponding header 1405 fields to indicate that additional header fields of that name SHOULD 1406 NOT be added. 1408 INFORMATIVE EXAMPLE: 1410 If the signer wishes to sign two existing Received header fields, 1411 and the existing header contains: 1413 Received: 1414 Received: 1415 Received: 1417 then the resulting DKIM-Signature header field should read: 1419 DKIM-Signature: ... h=Received : Received : ... 1421 and Received header fields and will be signed in that 1422 order. 1424 Signers SHOULD NOT sign header fields that might be replicated 1425 (either at the time of signing or potentially in the future), with 1426 the exception of trace header fields such as Received. Comment and 1427 non standard header fields (including X-* header fields) are 1428 permitted by [RFC2822] to be replicated; however, many such header 1429 fields are, by convention, not replicated. Signers need to 1430 understand the implications of signing header fields that might later 1431 be replicated, especially in the face of header field reordering. In 1432 particular, [RFC2822] only requires that trace header fields retain 1433 the original order. 1435 INFORMATIVE RATIONALE: Received: is allowed because these header 1436 fields, as well as Resent-* header fields, are already order- 1437 sensitive. 1439 INFORMATIVE ADMONITION: Despite the fact that [RFC2822] permits 1440 header field blocks to be reordered (with the exception of 1441 Received header fields), reordering of signed replicated header 1442 fields by intermediate MTAs will cause DKIM signatures to be 1443 broken; such anti-social behavior should be avoided. 1445 INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this 1446 specification, all end-user visible header fields should be signed 1447 to avoid possible "indirect spamming." For example, if the 1448 "Subject" header field is not signed, a spammer can resend a 1449 previously signed mail, replacing the legitimate subject with a 1450 one-line spam. 1452 INFORMATIVE NOTE: There has been some discussion that a Sender 1453 Signing Policy include the list of header fields that the signer 1454 always signs. N.B. In theory this is unnecessary, since as long 1455 as the signer really always signs the indicated header fields 1456 there is no possibility of an attacker replaying an existing 1457 message that has such an unsigned header field. 1459 5.5 Compute the Message Hash and Signature 1461 The signer MUST compute the message hash as described in Section 3.7 1462 and then sign it using the selected public-key algorithm. This will 1463 result in a DKIM-Signature header field which will include the body 1464 hash and a signature of the header hash, where that header includes 1465 the DKIM-Signature header field itself. 1467 To avoid possible ambiguity, a signer SHOULD either sign or remove 1468 any preexisting header fields which convey the results of previous 1469 verifications of the message signature prior to preparation for 1470 signing and transmission. Such header fields MUST NOT be signed if 1471 the signer is uncertain of the authenticity of the preexisting header 1472 field, for example, if it is not locally generated or signed by a 1473 previous DKIM-Signature line that the current signer has verified. 1475 Entities such as mailing list managers that implement DKIM and which 1476 modify the message or a header field (for example, inserting 1477 unsubscribe information) before retransmitting the message SHOULD 1478 check any existing signature on input and MUST make such 1479 modifications before re-signing the message; such signing SHOULD 1480 include any prior verification status, if any, that was inserted upon 1481 message receipt. 1483 The signer MAY elect to limit the number of bytes of the body that 1484 will be included in the hash and hence signed. The length actually 1485 hashed should be inserted in the "l=" tag of the "DKIM-Signature" 1486 header field. 1488 INFORMATIVE NOTE: A possible value to include in the "l=" tag 1489 would include the entire length of the message being signed, 1490 thereby allowing intermediate agents to append further information 1491 to the message without breaking the signature (e.g., a mailing 1492 list manager might add unsubscribe information to the body). A 1493 signer wishing to permit such intermediate agents to add another 1494 MIME body part to a "multipart/mixed" message should use a length 1495 that covers the entire presented message except for the trailing 1496 "--CRLF" characters; this is known as the "N-4" approach. Note 1497 that more than four characters may need to be stripped, since 1498 there could be postlude information that needs to be ignored. 1500 5.6 Insert the DKIM-Signature header field 1502 Finally, the signer MUST insert the "DKIM-Signature:" header field 1503 created in the previous step prior to transmitting the email. The 1504 "DKIM-Signature" header field MUST be the same as used to compute the 1505 hash as described above, except that the value of the "b=" tag MUST 1506 be the appropriately signed hash computed in the previous step, 1507 signed using the algorithm specified in the "a=" tag of the "DKIM- 1508 Signature" header field and using the private key corresponding to 1509 the selector given in the "s=" tag of the "DKIM-Signature" header 1510 field, as chosen above in Section 5.2 1512 The "DKIM-Signature" SHOULD be inserted before any header fields that 1513 it signs in the header block. 1515 INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this 1516 is to insert the "DKIM-Signature" header field at the beginning of 1517 the header block. In particular, it may be placed before any 1518 existing Received header fields. This is consistent with treating 1519 "DKIM-Signature" as a trace header. 1521 6. Verifier Actions 1523 Since a signer MAY expire a public key at any time, it is recommended 1524 that verification occur in a timely manner with the most timely place 1525 being during acceptance by the border MTA. 1527 A border or intermediate MTA MAY verify the message signatures and 1528 add a verification header field to incoming messages. This 1529 considerably simplifies things for the user, who can now use an 1530 existing mail user agent. Most MUAs have the ability to filter 1531 messages based on message header fields or content; these filters 1532 would be used to implement whatever policy the user wishes with 1533 respect to unsigned mail. 1535 A verifying MTA MAY implement a policy with respect to unverifiable 1536 mail, regardless of whether or not it applies the verification header 1537 field to signed messages. 1539 In the following description, text reading "return with 1540 DKIM_STAT_something" means that the verifier MUST immediately cease 1541 processing that signature. The verifier SHOULD proceed to the next 1542 signature, if any is present, and completely ignore the bad 1543 signature. There are two special cases: DKIM_STAT_PARTIALSIG 1544 indicates that only a portion of the message was actually signed, and 1545 DKIM_STAT_TEMPFAIL means that the signature could not be verified at 1546 this time but should be tried again later. In the former case, the 1547 action a verifier takes is a matter of local policy. In the latter 1548 case, a verifier MAY either defer the message for later processing, 1549 perhaps by queueing it local or issuing a 451/4.7.5 SMTP reply, or 1550 try another signature; if no good signature is found and any of the 1551 signatures resulted in a DKIM_STAT_TEMPFAIL status, the verifier 1552 SHOULD save the message for later processing. Note that an 1553 implementation is not constrained to use these status codes; these 1554 are for explanatory purposes only, and an implementation may define 1555 fewer or more status codes. 1557 The order in which signatures are tried is a matter of local policy 1558 for the verifier and is not defined here. A verifier SHOULD NOT 1559 treat a message that has one or more bad signatures and no good 1560 signatures differently from a message with no signature at all; 1561 again, this is local policy and is beyond the scope of this document. 1563 When a signature successfully verifies, a verifier will either stop 1564 processing or attempt to verify any other signatures, at the 1565 discretion of the implementation. 1567 Verifiers MUST apply the following steps in the order listed. 1569 6.1 Extract the Signature from the Message 1571 The signature and associated signing identity is included in the 1572 value of the DKIM-Signature header field. The order in which 1573 verifiers try DKIM-Signature header fields is not defined; verifiers 1574 MAY try signatures in any order they would like. For example, one 1575 implementation might prefer to try the signatures in textual order, 1576 whereas another might want to prefer signatures by identities that 1577 match the contents of the "From" header field over other identities. 1579 Implementers MUST meticulously validate the format and values in the 1580 DKIM-Signature header field; any inconsistency or unexpected values 1581 MUST cause the header field to be completely ignored and the verifier 1582 to return with DKIM_STAT_SYNTAX. Being "liberal in what you accept" 1583 is definitely a bad strategy in this security context. Note however 1584 that this does not include the existence of unknown tags in a DKIM- 1585 Signature header field, which are explicitly permitted. 1587 Verifiers MUST ignore DKIM-Signature header fields with a "v=" tag 1588 that is inconsistent with this specification and return with 1589 DKIM_STAT_INCOMPAT. 1591 INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of 1592 course, choose to also verify signatures generated by older 1593 versions of this specification. 1595 If the DKIM-Signature header field does not contain any of the tags 1596 listed as required in Section 3.5 the verifier MUST ignore the DKIM- 1597 Signature header field and return with DKIM_STAT_SYNTAX. 1599 If the "DKIM-Signature" header field does not contain the "i=" tag, 1600 the verifier MUST behave as though the value of that tag were "@d", 1601 where "d" is the value from the "d=" tag. 1603 Verifiers MUST confirm that the domain specified in the "d=" tag is 1604 the same as or a superdomain of the domain part of the "i=" tag. If 1605 not, the DKIM-Signature header field MUST be ignored and the verifier 1606 should return with DKIM_STAT_SYNTAX. 1608 Verifiers MAY ignore the DKIM-Signature header field and return with 1609 DKIM_STAT_EXPIRED if it contains an "x=" tag and the signature has 1610 expired. 1612 Verifiers MUST NOT attribute ultimate meaning to the order of 1613 multiple DKIM-Signature header fields. In particular, there is 1614 reason to believe that some relays will reorder the header fields in 1615 potentially arbitrary ways. 1617 INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as 1618 a clue to signing order in the absence of any other informaation. 1619 However, other clues as to the semantics of multiple signatures 1620 must be considered before using ordering. 1622 If there are no valid signatures remaining after this step, a 1623 verifier MUST NOT proceed to the next step. 1625 6.2 Get the Public Key 1627 The public key is needed to complete the verification process. The 1628 process of retrieving the public key depends on the query type as 1629 defined by the "q=" tag in the "DKIM-Signature:" header field. 1630 Obviously, a public key should only be retrieved if the process of 1631 extracting the signature information is completely successful. 1632 Details of key management and representation are described in 1633 Section 3.6. The verifier MUST validate the key record and MUST 1634 ignore any public key records that are malformed. 1636 When validating a message, a verifier MUST perform the following 1637 steps in a manner that is semantically the same as performing them in 1638 the order indicated (in some cases the implementation may parallelize 1639 or reorder these steps, as long as the semantics remain unchanged): 1641 1. Retrieve the public key as described in (Section 3.6) using the 1642 domain from the "d=" tag and the selector from the "s=" tag. 1644 2. If the query for the public key fails to respond, the verifier 1645 SHOULD defer acceptance of this email and return with 1646 DKIM_STAT_TEMPFAIL. If verification is occuring during the 1647 incoming SMTP session, this MAY be achieved with a 451/4.7.5 SMTP 1648 reply code. Alternatively, the verifier MAY store the message in 1649 the local queue for later trial or ignore the signature. Note 1650 that storing a message in the local queue is subject to denial- 1651 of-service attacks. 1653 3. If the query for the public key fails because the corresponding 1654 key record does not exist, the verifier MUST immediately return 1655 with DKIM_STAT_NOKEY. 1657 4. If the query for the public key returns multiple key records, the 1658 verifier may choose one of the key records or may cycle through 1659 the key records performing the remainder of these steps on each 1660 record at the discretion of the implementer. The order of the 1661 key records is unspecified. If the verifier chooses to cycle 1662 through the key records, then the "return with ..." wording in 1663 the remainder of this section means "try the next key record, if 1664 any; if none, try the next DKIM-Signature header field." 1666 5. If the result returned from the query does not adhere to the 1667 format defined in this specification, the verifier MUST ignore 1668 the key record aand return with DKIM_STAT_NOKEY. Verifiers are 1669 urged to validate the syntax of key records carefully to avoid 1670 attempted attacks. 1672 6. If the "g=" tag in the public key does not match the local part 1673 of the "i=" tag on the message signature, the verifier MUST 1674 ignore the key record and return with DKIM_STAT_INAPPLICABLE. If 1675 the local part of the "i=" tag on the message signature is not 1676 present, the g= tag must be * (valid for all addresses in the 1677 domain) or not present (which defaults to *), otherwise the 1678 verifier MUST ignore the key record and return with 1679 DKIM_STAT_INAPPLICABLE. Other than this test, verifiers SHOULD 1680 NOT treat a message signed with a key record having a g= tag any 1681 differently than one without; in particular, verifiers SHOULD NOT 1682 prefer messages that seem to have an individual signature by 1683 virtue of a g= tag vs. a domain signature. 1685 7. If the "h=" tag exists in the public key record and the hash 1686 algorithm implied by the a= tag in the DKIM-Signature header is 1687 not included in the contents of the "h=" tag, the verifier MUST 1688 ignore the key record and return with DKIM_STAT_INAPPLICABLE. 1690 8. If the public key data (the "p=" tag) is empty then this key has 1691 been revoked and the verifier MUST treat this as a failed 1692 signature check and return with DKIM_STAT_REVOKED. 1694 9. If the public key data is not suitable for use with the algorithm 1695 and key types defined by the "a=" and "k=" tags in the "DKIM- 1696 Signature" header field, the verifier MUST immediately return 1697 with DKIM_STAT_INAPPLICABLE. 1699 6.3 Compute the Verification 1701 Given a signer and a public key, verifying a signature consists of 1702 the following steps. 1704 1. Based on the algorithm defined in the "c=" tag, the body length 1705 specified in the "l=" tag, and the header field names in the "h=" 1706 tag, create a canonicalized copy of the email as is described in 1707 Section 3.7. When matching header field names in the "h=" tag 1708 against the actual message header field, comparisons MUST be 1709 case-insensitive. 1711 2. Based on the algorithm indicated in the "a=" tag, compute the 1712 message hashes from the canonical copy as described in 1713 Section 3.7. 1715 3. Using the signature conveyed in the "b=" tag, verify the 1716 signature against the header hash using the mechanism appropriate 1717 for the public key algorithm described in the "a=" tag. If the 1718 signature does not validatee, the verifier SHOULD ignore the 1719 signature and return with DKIM_STAT_INVALIDSIG. 1721 INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to 1722 initiate the public-key query in parallel with calculating the 1723 hash as the public key is not needed until the final decryption is 1724 calculated. Implementations may also verify the signature on the 1725 message header before validating that the message hash listed in 1726 the "bh=" tag in the DKIM-Signature header field matches that of 1727 the actual message body; however, if the body hash does not match, 1728 the entire signature must be considered to have failed. 1730 Verifiers SHOULD ignore any DKIM-Signature header fields where the 1731 signature does not validate. Verifiers that are prepared to validate 1732 multiple signature header fields SHOULD proceed to the next signature 1733 header field, should it exist. However, verifiers MAY make note of 1734 the fact that an invalid signature was present for consideration at a 1735 later step. 1737 INFORMATIVE NOTE: The rationale of this requirement is to permit 1738 messages that have invalid signatures but also a valid signature 1739 to work. For example, a mailing list exploder might opt to leave 1740 the original submitter signature in place even though the exploder 1741 knows that it is modifying the message in some way that will break 1742 that signature, and the exploder inserts its own signature. In 1743 this case the message should succeed even in the presence of the 1744 known-broken signature. 1746 If a body length is specified in the "l=" tag of the signature, 1747 verifiers MUST only verify the number of bytes indicated in the body 1748 length. Verifiers MAY decide to treat a message containing bytes 1749 beyond the indicated body length with suspicion. Verifiers MAY 1750 truncate the message at the indicated body length, reject the 1751 signature outright, or convey the partial verification to the policy 1752 module using DKIM_STAT_PARTIALSIG. 1754 INFORMATIVE IMPLEMENTATION NOTE: Verifiers that truncate the body 1755 at the indicated body length might pass on a malformed MIME 1756 message if the signer used the "N-4" trick described in the 1757 informative note in Section 5.5. Such verifiers may wish to check 1758 for this case and include a trailing "--CRLF" to avoid breaking 1759 the MIME structure. A simple way to achieve this might be to 1760 append "--CRLF" to any "multipart" message with a body length; if 1761 the MIME structure is already correctly formed, this will appear 1762 in the postlude and will not be displayeed to the end user. 1764 6.4 Communicate Verification Results 1766 Verifiers wishing to communicate the results of verification to other 1767 parts of the mail system may do so in whatever manner they see fit. 1768 For example, implementations might choose to add an email header 1769 field to the message before passing it on. An example proposal for a 1770 header field is the Authentication-Results header field [ID-AUTH- 1771 RES]. Any such header field SHOULD be inserted before any existing 1772 DKIM-Signature or preexisting authentication status header fields in 1773 the header field block. 1775 INFORMATIVE ADVICE to MUA filter writers: Patterns intended to 1776 search for results header fields to visibly mark authenticated 1777 mail for end users should verify that such header field was added 1778 by the appropriate verifying domain and that the verified identity 1779 matches the sender identity that will be displayed by the MUA. In 1780 particular, MUA filters should not be influenced by bogus results 1781 header fields added by attackers. 1783 6.5 Interpret Results/Apply Local Policy 1785 It is beyond the scope of this specification to describe what actions 1786 a verifier system should make, but an authenticated email presents an 1787 opportunity to a receiving system that unauthenticated email cannot. 1788 Specifically, an authenticated email creates a predictable identifier 1789 by which other decisions can reliably be managed, such as trust and 1790 reputation. Conversely, unauthenticated email lacks a reliable 1791 identifier that can be used to assign trust and reputation. It is 1792 reasonable to treat unauthenticated email as lacking any trust and 1793 having no positive reputation. 1795 In general verifiers SHOULD NOT reject messages solely on the basis 1796 of a lack of signature or an unverifiable signature. However, if the 1797 verifier does opt to reject such messages, and the verifier runs 1798 synchronously with the SMTP session and a signature is missing or 1799 does not verify, the MTA SHOULD reject the message with an error such 1800 as: 1802 550 5.7.1 Unsigned messages not accepted 1804 550 5.7.5 Message signature incorrect 1806 If it is not possible to fetch the public key, perhaps because the 1807 key server is not available, a temporary failure message MAY be 1808 generated, such as: 1810 451 4.7.5 Unable to verify signature - key server unavailable 1812 A temporary failure of the key server or other external service is 1813 the only condition that should use a 4xx SMTP reply code. In 1814 particular, signature verification failures MUST NOT return 4xx SMTP 1815 replies. 1817 Oncee the signature has been verified, that information MUST be 1818 conveyed to higher level systems (such as explicit allow/white lists 1819 and reputation systems) and/or to the end user. If the message is 1820 signed on behalf of any address other than that in the From: header 1821 field, the mail system SHOULD take pains to ensure that the actual 1822 signing identity is clear to the reader. 1824 INFORMATIVE NOTE: If the authentication status is to be stored in 1825 the message header field, the Authentication-Results header field 1826 [ID-AUTH-RES] may be used to convey this information. 1828 The verifier MAY treat unsigned header fields with extreme 1829 skepticism, including marking them as untrusted or even deleting them 1830 before display to the end user. 1832 While the symptoms of a failed verification are obvious -- the 1833 signature doesn't verify -- establishing the exact cause can be more 1834 difficult. If a selector cannot be found, is that because the 1835 selector has been removed or was the value changed somehow in 1836 transit? If the signature line is missing is that because it was 1837 never there, or was it removed by an over-zealous filter? For 1838 diagnostic purposes, the exact reason why the verification fails 1839 SHOULD be recorded in the "Authentication-Results" header field and 1840 possibly the system logs. However in terms of presentation to the 1841 end user, the result SHOULD be presented as a simple binary result: 1842 either the email is verified or it is not. If the email cannot be 1843 verified, then it SHOULD be rendered the same as all unverified email 1844 regardless of whether it looks like it was signed or not. 1846 6.6 MUA Considerations 1848 In order to retain the current semantics and visibility of the From 1849 header field, verifying mail agents SHOULD take steps to ensure that 1850 the signing address is prominently visible to the user if it is 1851 different from the From address. MUAs MAY visually mark the 1852 unverified part of the body in a distinctive font or color to the end 1853 user. 1855 If MUA implementations that highlight the signed address are not 1856 available, this MAY be done by the validating MTA or MDA by rewriting 1857 the From address in a manner which remains compliant with [RFC2822]. 1858 Such modifications MUST be performed after the final verification 1859 step since they will break the signature. If performed, the 1860 rewriting SHOULD include the name of the signer in the address. For 1861 example: 1863 From: John Q. User 1865 might be converted to 1867 From: "John Q. User via " 1869 This sort of addrress inconsistency is expected for mailing lists, but 1870 might be otherwise used to mislead the verifier, for example if a 1871 message supposedly from administration@your-bank.com had a Sender 1872 address of fraud@badguy.com. 1874 Under no circumstances should an unsigned header field be displayed 1875 in any context that might be construed by the end user as having been 1876 signed. Notably, unsigned header fields SHOULD be hidden from the 1877 end user to the extent possible. 1879 The MUA MAY hide or mark portions of the message body that are not 1880 signed when using the "l=" tag. 1882 7. IANA Considerations 1884 To avoid conflicts, tag names for the DKIM-Signature header and key 1885 records should be registered with IANA. 1887 Tag values for the "a=", "c=", and "q=" tags in the DKIM-Signature 1888 header field, and the "h=", "k=", "s=", and "t" tags in key records 1889 should be registered with IANA for the same reason. 1891 The DKK RR type must be registered by IANA. 1893 8. Security Considerations 1895 It has been observed that any mechanism that is introduced which 1896 attempts to stem the flow of spam is subject to intensive attack. 1897 DKIM needs to be carefully scrutinized to identify potential attack 1898 vectors and the vulnerability to each. See also [ID-DKIM-THREATS]. 1900 8.1 Misuse of Body Length Limits ("l=" Tag) 1902 Body length limits (in the form of the "l=" tag) are subject to 1903 several potential attacks. 1905 8.1.1 Addition of new MIME parts to multipart/* 1907 If the body length limit does not cover a closing MIME multipart 1908 section (including the trailing ""--CRLF"" portion), then it is 1909 possible for an attacker to intercept a properly signed multipart 1910 message and add a new body part. Depending on the details of the 1911 MIME type and the implementation of the verifying MTA and the 1912 receiving MUA, this could allow an attacker to change the information 1913 displayed to an end user from an apparently trusted source. 1915 *** Example appropriate here *** 1917 8.1.2 Addition of new HTML content to existing content 1919 Several receiving MUA implementations do not cease display after a 1920 """" tag. In particular, this allows attacks involving 1921 overlaying images on top of existing text. 1923 INFORMATIVE EXAMPLE: Appending the following text to an existing, 1924 properly closed message will in many MUAs result in inappropriate 1925 data being rendered on top of existing, correct data: 1926
1927 1929
1931 8.2 Misappropriateed Private Key 1933 If the private key for a user is resident on their computer and is 1934 not protected by an appropriately secure mechanism, it is possible 1935 for malware to send mail as that user and any other user sharing the 1936 same private key. The malware would, however, not be able to 1937 generate signed spoofs of other signers' addresses, which would aid 1938 in identification of the infected user and would limit the 1939 possibilities for certain types of attacks involving socially- 1940 engineered messages. 1942 A larger problem occurs if malware on many users' computers obtains 1943 the private keys for those users and transmits them via a covert 1944 channel to a site where they can be shared. The compromised users 1945 would likely not know of the misappropriation until they receive 1946 "bounce" messages from messages they are purported to have sent. 1947 Many users might not understand the significance of these bounce 1948 messages and would not take action. 1950 One countermeasure is to use a user-entered passphrase to encrypt the 1951 private key, although users tend to choose weak passphrases and often 1952 reuse them for different purposes, possibly allowing an attack 1953 against DKIM to be extended into other domains. Nevertheless, the 1954 decoded private key might be briefly available to compromise by 1955 malware when it is entered, or might be discovered via keystroke 1956 logging. The added complexity of entering a passphrase each time one 1957 sends a message would also tend to discourage the use of a secure 1958 passphrase. 1960 A somewhat more effective countermeasure is to send messages through 1961 an outgoing MTA that can authenticate the submitter using existing 1962 techniques (e.g., SMTP Authentication), possibly validate the message 1963 itself (e.g., verify that the header is legitimate and that the 1964 content passes a spam content check), and sign the message using a 1965 key appropriate for the submitter address. Such an MTA can also 1966 apply controls on the volume of outgoing mail each user is permitted 1967 to originate in order to further limit the ability of malware to 1968 generate bulk email. 1970 8.3 Key Server Denial-of-Service Attacks 1972 Since the key servers are distributed (potentially separate for each 1973 domain), the number of servers that would need to be attacked to 1974 defeat this mechanism on an Internet-wide basis is very large. 1975 Nevertheless, key servers for individual domains could be attacked, 1976 impeding the verification of messages from that domain. This is not 1977 significantly different from the ability of an attacker to deny 1978 service to the mail exchangers for a given domain, aalthough it 1979 affects outgoing, not incoming, mail. 1981 A variation on this attack is that if a very large amount of mail 1982 were to be sent using spoofed addresses from a given domain, the key 1983 servers for that domain could be overwhelmed with requests. However, 1984 given the low overhead of verification compared with handling of the 1985 email message itself, such an attack would be difficult to mount. 1987 8.4 Attacks Against DNS 1989 Since DNS is a required binding for key services, specific attacks 1990 against DNS must be considered. 1992 While the DNS is currently insecure [RFC3833], it is expected that 1993 the security problems should and will be solved by DNSSEC [RFC4033], 1994 and all users of the DNS will reap the benefit of that work. 1996 Secondly, the types of DNS attacks relevant to DKIM are very costly 1997 and are far less rewarding than DNS attacks on other Internet 1998 applications. 2000 To systematically thwart the intent of DKIM, an attacker must conduct 2001 a very costly and very extensive attack on many parts of the DNS over 2002 an extended period. No one knows for sure how attackers will 2003 respond, however the cost/benefit of conducting prolonged DNS attacks 2004 of this nature is expected to be uneconomical. 2006 Finally, DKIM is only intended as a "sufficient" method of proving 2007 authenticity. It is not intended to provide strong cryptographic 2008 proof about authorship or contents. Other technologies such as 2009 OpenPGP [RFC2440] and S/MIME [RFC3851] address those requirements. 2011 A second security issue related to the DNS revolves around the 2012 increased DNS traffic as a consequence of fetching Selector-based 2013 data as well as fetching signing domain policy. Widespread 2014 deployment of DKIM will result in a significant increase in DNS 2015 queries to the claimed signing domain. In the case of forgeries on a 2016 large scale, DNS servers could see a substantial increase in queries. 2018 8.5 Replay Attacks 2020 In this attack, a spammer sends a message to be spammed to an 2021 accomplice, which results in the message being signed by the 2022 originating MTA. The accomplice resends the message, including the 2023 original signature, to a large number of recipients, possibly by 2024 sending the message to many compromised machines that act as MTAs. 2025 The messages, not having been modified by the accomplice, have valid 2026 signatures. 2028 Partial solutions to this problem involve the use of reputation 2029 services to convey the fact that the specific email address is being 2030 used for spam, and that messages from that signer are likely to be 2031 spam. This requires a real-time detection mechanissm in order to 2032 react quickly enough. However, such measures might be prone to 2033 abuse, if for example an attacker resent a large number of messages 2034 received from a victim in order to make them appear to be a spammer. 2036 Large verifiers might be able to detect unusually large volumes of 2037 mails with the same signature in a short time period. Smaller 2038 verifiers can get substantially the same volume information via 2039 existing collaborative systems. 2041 8.6 Limits on Revoking Keys 2043 When a large domain detects undesirable behavior on the part of one 2044 of its users, it might wish to revoke the key used to sign that 2045 user's messages in order to disavow responsibility for messages which 2046 have not yet been verified or which are the subject of a replay 2047 attack. However, the ability of the domain to do so can be limited 2048 if the same key, for scalability reasons, is used to sign messages 2049 for many other users. Mechanisms for explicitly revoking keys on a 2050 per-address basis have been proposed but require further study as to 2051 their utility and the DNS load they represent. 2053 8.7 Intentionally malformed Key Records 2055 It is possible for an attacker to publish key records in DNS which 2056 are intentionally malformed, with the intent of causing a denial-of- 2057 service attack on a non-robust verifier implementation. The attacker 2058 could then cause a verifier to read the malformed key record by 2059 sending a message to one of its users referencing the malformed 2060 record in a (not necessarily valid) signature. Verifiers MUST 2061 thoroughly verify all key records retrieved from DNS and be robust 2062 against intentionally as well as unintentionally malformed key 2063 records. 2065 8.8 Intentionally Malformed DKIM-Signature header fields 2067 Verifiers MUST be prepared to receive messages with malformed DKIM- 2068 Signature header fields, and thoroughly verify the header field 2069 before depending on any of its contents. 2071 8.9 Information Leakage 2073 An attacker could determine when a particular signature was verified 2074 by using a per-message selector and then monitoring their DNS traffic 2075 for the key lookup. This would act as the equivalent of a "web bug" 2076 for verification time rather than when the message was read. 2078 8.10 Remote Timing Attacks 2080 In some cases it may be possible to extract private keys using a 2081 remote timing attack [BONEH03]. Implementations should consider 2082 obfuscating the timing to prevent such attacks. 2084 9. References 2085 9.1 Normative References 2087 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2088 Extensions (MIME) Part One: Format of Internet Message 2089 Bodies", RFC 2045, November 1996. 2091 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 2092 Part Three: Message header field Extensions for Non-ASCII 2093 Text", RFC 2047, November 1996. 2095 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2096 Requirement Levels", BCP 14, RFC 2119, March 1997. 2098 [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, 2099 April 2001. 2101 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 2102 April 2001. 2104 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2105 Standards (PKCS) #1: RSA Cryptography Specifications 2106 Version 2.1", RFC 3447, February 2003. 2108 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2109 Specifications: ABNF", RFC 4234, October 2005. 2111 9.2 Informative References 2113 [BONEH03] Proc. 12th USENIX Security Symposium, "Remote Timing 2114 Attacks are Practical", 2003, . 2117 [ID-AUTH-RES] 2118 Kucherawy, M., "Message header field for Indicating Sender 2119 Authentication Status", 2120 draft-kucherawy-sender-auth-header-02 (work in progress), 2121 February 2006. 2123 [ID-DKIM-THREATS] 2124 Fenton, J., "Analysis of Threats Motivating DomainKeys 2125 Identified Mail (DKIM)", draft-fenton-dkim-threats-02 2126 (work in progress), April 2006. 2128 [RFC1847] Galvin, J., Murphy, S., Crocker, S., and N. Freed, 2129 "Security Multiparts for MIME: Multipart/Signed and 2130 Multipart/Encrypted", RFC 1847, October 1995. 2132 [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, 2133 "OpenPGP Message Format", RFC 2440, November 1998. 2135 [RFC3766] Orman, H. and P. Hoffman, "Determing Strengths for Public 2136 Keys Used For Exchanging Symmetric Keys", RFC 3766, 2137 April 2004. 2139 [RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain 2140 Name System (DNS)", RFC 3833, August 2004. 2142 [RFC3851] Ramsdell, B., "S/MIME Version 3 Message Specification", 2143 RFC 3851, June 1999. 2145 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2146 Rose, "DNS Security Introduction and Requirements", 2147 RFC 4033, March 2005. 2149 Authors' Addresses 2151 Eric Allman 2152 Sendmail, Inc. 2153 6425 Christie Ave, Suite 400 2154 Emeryville, CA 94608 2155 USA 2157 Phone: +1 510 594 5501 2158 Email: eric+dkim@sendmail.org 2159 URI: 2161 Jon Callas 2162 PGP Corporation 2163 3460 West Bayshore 2164 Palo Alto, CA 94303 2165 USA 2167 Phone: +1 650 319 9016 2168 Email: jon@pgp.com 2169 Mark Delany 2170 Yahoo! Inc 2171 701 First Avenue 2172 Sunnyvale, CA 95087 2173 USA 2175 Phone: +1 408 349 6831 2176 Email: markd+dkim@yahoo-inc.com 2177 URI: 2179 Miles Libbey 2180 Yahoo! Inc 2181 701 First Avenue 2182 Sunnyvale, CA 95087 2183 USA 2185 Email: mlibbeymail-mailsig@yahoo.com 2186 URI: 2188 Jim Fenton 2189 Cisco Systems, Inc. 2190 MS SJ-24/2 2191 170 W. Tasman Drive 2192 San Jose, CA 95134-1706 2193 USA 2195 Phone: +1 408 526 5914 2196 Email: fenton@cisco.com 2197 URI: 2199 Michael Thomas 2200 Cisco Systems, Inc. 2201 MS SJ-9/2 2202 170 W. Tasman Drive 2203 San Jose, CA 95134-1706 2205 Phone: +1 408 525 5386 2206 Email: mat@cisco.com 2208 Appendix A. Example of Use (INFORMATIVE) 2210 This section shows the complete flow of an email from submission to 2211 final delivery, demonstrating how the various components fit 2212 together. 2214 A.1 The user composes an email 2216 From: Joe SixPack 2217 To: Suzie Q 2218 Subject: Is dinner ready? 2219 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2220 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2222 Hi. 2224 We lost the game. Are you hungry yet? 2226 Joe. 2228 A.2 The email is signed 2230 This email is signed by the example.com outbound email server and now 2231 looks like this: 2233 DKIM-Signature: a=rsa-sha1; s=brisbane; d=example.com; 2234 c=simple; q=dns; i=joe@football.example.com; 2235 h=Received : From : To : Subject : Date : Message-ID; 2236 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 2237 VoG4ZHRNiYzR; 2238 Received: from dsl-10.2.3.4.football.example.com [10.2.3.4] 2239 by submitserver.example.com with SUBMISSION; 2240 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2241 From: Joe SixPack 2242 To: Suzie Q 2243 Subject: Is dinner ready? 2244 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2245 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2247 Hi. 2249 We lost the game. Are you hungry yet? 2251 Joe. 2253 The signing email server requires access to thhe private-key 2254 associated with the "brisbane" selector to generate this signature. 2256 A.3 The email signature is verified 2258 The signature is normally verified by an inbound SMTP server or 2259 possibly the final delivery agent. However, intervening MTAs can 2260 also perform this verification if they choose to do so. The 2261 verification process uses the domain "example.com" extracted from the 2262 "d=" tag and the selector "brisbane" from the "s=" tag in the "DKIM- 2263 Signature" header field to form the DNS DKIM query for: 2265 brisbane._domainkey.example.com 2267 Signature verification starts with the physically last "Received" 2268 header field, the "From" header field, and so forth, in the order 2269 listed in the "h=" tag. Verification follows with a single CRLF 2270 followed by the body (starting with "Hi."). The email is canonically 2271 prepared for verifying with the "simple" method. The result of the 2272 query and subsequent verification of the signature is stored in the 2273 "Authentication-Results" header field line. After successful 2274 verification, the email looks like this: 2276 Authentication-Results: shopping.example.net 2277 header.from=joe@football.example.com; dkim=pass 2278 Received: from mout23.football.example.com (192.168.1.1) 2279 by shopping.example.net with SMTP; 2280 Fri, 11 Jul 2003 21:01:59 -0700 (PDT) 2281 DKIM-Signature: a=rsa-sha1; s=brisbane; d=example.com; 2282 c=simple; q=dns; i=joe@football.example.com; 2283 h=Received : From : To : Subject : Date : Message-ID; 2284 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 2285 VoG4ZHRNiYzR 2286 Received: from dsl-10.2.3.4.network.example.com [10.2.3.4] 2287 by submitserver.example.com with SUBMISSION; 2288 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2289 From: Joe SixPack 2290 To: Suzie Q 2291 Subject: Is dinner ready? 2292 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2293 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2295 Hi. 2297 We lost the game. Are you hungry yet? 2299 Joe. 2301 Appendix B. Usage Examples (INFORMATIVE) 2303 Studies in this appendix are for informational purposes only. In no 2304 case should these examples be used as guidance when creating an 2305 implementation. 2307 B.1 Simple Message Forwarding 2309 In some cases the recipient may request forwarding of email messages 2310 from the original address tto another, through the use of a Unix 2311 .forward file or equivalent. In this case messages are typically 2312 forwarded without modification, except for the addition of a Received 2313 header field to the message and a change in the Envelope-to address. 2314 In this case, the eventual recipient should be able to verify the 2315 original signature since the signed content has not changed, and 2316 attribute the message correctly. 2318 B.2 Outsourced Business Functions 2320 Outsourced business functions represent a use case that motivates the 2321 need for selectors (the "s=" signature tag) and granularity (the "g=" 2322 key tag). Examples of outsourced business functions are legitimate 2323 email marketing providers and corporate benefits providers. In 2324 either case, the outsourced function would like to be able to send 2325 messages using the email domain of the client company. At the same 2326 time, the client may be reluctant to register a key for the provider 2327 that grants the ability to send messages for any address in the 2328 domain. 2330 The outsourcing company can generate a keypair and the client company 2331 can register the public key using a unique selector for a specific 2332 address such as winter-promotions@example.com by specifying a 2333 granularity of "g=winter-promotions" or "g=*-promotions" (to allow a 2334 range of addresses). This would enable the provider to send messages 2335 using that specific address and have them verify properly. The 2336 client company retains control over the email address because it 2337 retains the ability to revoke the key at any time. 2339 B.3 PDAs and Similar Devices 2341 PDAs are one example of the use of multiple keys per user. Suppose 2342 that John Doe wanted to be able to send messages using his corporate 2343 email address, jdoe@example.com, and the device did not have the 2344 ability to make a VPN connection to the corporate network. If the 2345 device was equipped with a private key registered for 2346 jdoe@example.com by the administrator of that domain, and appropriate 2347 software to sign messages, John could send signed messages through 2348 the outgoing network of the PDA service provider. 2350 B.4 Mailing Lists 2352 There is a wide range of behavior in forwarders and mailing lists 2353 (collectively called "forwarders" below), ranging from those which 2354 make no modification to the message itself (other than to add a 2355 Received header field and change the envelope information) to those 2356 which may add header fields, change the Subject header field, add 2357 content to the body (typically at the end), or reformat the body in 2358 some manner. 2360 Forwarders which do noot modify the body or signed header fields of a 2361 message with a valid signature may re-sign the message as described 2362 below. 2364 Forwarders which make any modification to a message that could result 2365 in its signature becoming invalid should sign or re-sign using an 2366 appropriate identification (e.g., mailing-list-name@example.net). 2367 Since in so doing the (re-)signer is taking responsibility for the 2368 content of the message, modifying forwarders may elect to forward or 2369 re-sign only for messages which were received with valid signatures 2370 or other indications that the messages being signed are not spoofed. 2372 Forwarders which wish to re-sign a message must apply a Sender header 2373 field to the message to identify the address being used to sign the 2374 message and must remove any preexisting Sender header field as 2375 required by [RFC2822]. The forwarder applies a new DKIM-Signature 2376 header field with the signature, public key, and related information 2377 of the forwarder. 2379 B.5 Affinity Addresses 2381 "Affinity addresses" are email addresses that users employ to have an 2382 email address that is independent of any changes in email service 2383 provider they may choose to make. They are typically associated with 2384 college alumni associations, professional organizations, and 2385 recreational organizations with which they expect to have a long-term 2386 relationship. These domains usually provide forwarding of incoming 2387 email, but (currently) usually depend on the user to send outgoing 2388 messages through their own service provider's MTA. They usually have 2389 an associated Web application which authenticates the user and allows 2390 the forwarding address to be changed. 2392 With DKIM, affinity domains could use the Web application to allow 2393 users to register their own public keys to be used to sign messages 2394 on behalf of their affinity address. This is another application 2395 that takes advantage of user-level keying, and domains used for 2396 affinity addresses would typically have a very large number of user- 2397 level keys. Alternatively, the affinity domain could handle outgoing 2398 mail, operating a mail submission agent that authenticates users 2399 before accepting and signing messages for them. This is of course 2400 dependent on the user's service provider not blocking the relevant 2401 TCP ports used for mail submission. 2403 B.6 Third-party Message Transmission 2405 Third-party message transmission refers to the authorized sending of 2406 mail by an Internet application on behalf of a user. For example, a 2407 website providing news may allow the reader to forward a copy of the 2408 message to a friend; this is typically done using the reader's email 2409 address. This is sometimes referred to as the "Evite problem", named 2410 after the website of the same name that allows a user to send 2411 invitations to friends. 2413 One way this can be handled is to continue to put the reader's email 2414 address in the From field of the message, but put an address owned by 2415 the site into the Sender field, and sign the message on behalf of the 2416 Sender. A verifying MTA should accept this and rewrite the From 2417 field to indicate the address that was verified, i.e., From: John 2418 Doe via news@news-site.com . 2420 Appendix C. Creating a public key (INFORMATIVE) 2422 XXX Update to 1024 bit key and SHA-256 and adjust examples 2423 accordingly. XXX 2425 The default signature is an RSA signed SHA1 digest of the complete 2426 email. For ease of explanation, the openssl command is used to 2427 describe the mechanism by which keys and signatures are managed. One 2428 way to generate a 768 bit private-key suitable for DKIM, is to use 2429 openssl like this: 2431 $ openssl genrsa -out rsa.private 768 2433 This results in the file rsa.private containing the key information 2434 similar to this: 2436 -----BEGIN RSA PRIVATE KEY----- 2437 MIIByQIBAAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6lMIgulclWjZwP56LRqdg5 2438 ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7EXzVc+nRLWT1kwTvFNGIo 2439 AUsFUq+J6+OprwIDAQABAmBOX0UaLdWWusYzNol++nNZ0RLAtr1/LKMX3tk1MkLH 2440 +Ug13EzB2RZjjDOWlUOY98yxW9/hX05Uc9V5MPo+q2Lzg8wBtyRLqlORd7pfxYCn 2441 Kapi2RPMcR1CxEJdXOkLCFECMQDTO0fzuShRvL8q0m5sitIHlLA/L+0+r9KaSRM/ 2442 3WQrmUpV+fAC3C31XGjhHv2EuAkCMQDE5U2nP2ZWVlSbxOKBqX724amoL7rrkUew 2443 ti9TEjfaBndGKF2yYF7/+g53ZowRkfcCME/xOJr58VN17pejSl1T8Icj88wGNHCs 2444 FDWGAH4EKNwDSMnfLMG4WMBqd9rzYpkvGQIwLhAHDq2CX4hq2tZAt1zT2yYH7tTb 2445 weiHAQxeHe0RK+x/UuZ2pRhuoSv63mwbMLEZAjAP2vy6Yn+f9SKw2mKuj1zLjEhG 2446 6ppw+nKD50ncnPoP322UMxVNG4Eah0GYJ4DLP0U= 2447 -----END RSA PRIVATE KEY----- 2449 To extract the public-key component from the private-key, use openssl 2450 like this: 2452 $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM 2454 This results in the file rsa.public containing the key information 2455 similar to this: 2457 -----BEGIN PUBLIC KEY----- 2458 MHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6l 2459 MIgulclWjZwP56LRqdg5ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7E 2460 XzVc+nRLWT1kwTvFNGIoAUsFUq+J6+OprwIDAQAB 2461 -----END PUBLIC KEY----- 2463 This public-key data (without the BEGIN and END tags) is placed in 2464 the DNS. With the signature, canonical email contents and puublic 2465 key, a verifying system can test the validity of the signature. The 2466 openssl invocation to verify a signature looks like this: 2468 openssl dgst -verify rsa.public -sha1 -signature signature.file \ 2469 . 2505 Appendix E. Edit History 2507 [[This section to be removed before publication.]] 2509 E.1 Changes since -ietf-01 version 2511 The following changes were made between draft-ietf-dkim-base-01 and 2512 draft-ietf-dkim-base-02: 2514 o Change wording on "x=" tag in DKIM-Signature header field 2515 regarding verifier handling of expired signatures from MUST to MAY 2516 (per 20 April Jabber session). Also, make it clear that received 2517 time is to be preferred over current time if reliably available. 2519 o Several changes to limit wording that would intrude into verifier 2520 policy. This is largely changing statements such as "... MUST 2521 reject the message" to "... MUST consider the signature invalid." 2523 o Drop normative references to ID-DKIM-RR, OpenSSL, PEM, and 2524 Stringprep. 2526 o Change "v=" tag in DKIM-Signature from "MUST NOT" to "MUST"; the 2527 version number is 0.2 for this draft, with the expectation that 2528 the first official version will be "v=1". (Per 18 May Jabber 2529 session.) 2531 o Change "q=dns" query access method to "q=dnstxt" to emphasize the 2532 use of the TXT record. The expectation is that a later extension 2533 will define "q=dnsdkk" to indicate use of a DKK record. (Per 18 2534 May Jabber session.) 2536 o Several typos fixed, including removing a paragraph that implied 2537 that the DKIM-Signature header field should be hashed with the 2538 body (it should not). 2540 E.2 Changes since -ietf-00 version 2542 The following changes were made between draft-ietf-dkim-base-00 and 2543 draft-ietf-dkim-base-01: 2545 o Added section 8.9 (Information Leakage). 2547 o Replace section 4 (Multiple Signatures) with much less vague text. 2549 o Fixed ABNF for base64string. 2551 o Added rsa-sha256 signing algorithm. 2553 o Expanded several examples. 2555 o Changed signing algorithm to use separate hash of the body of the 2556 message; this is represented as the "bh=" tag in the DKIM- 2557 Signature header field. 2559 o Changed "z=" tag so that it need not have the same header field 2560 names as the "h=" tag. 2562 o Significant wordsmithing. 2564 E.3 Changes since -allman-01 version 2566 The following changes were made between draft-allman-dkim-base-01 and 2567 draft-ietf-dkim-base-00: 2569 o Remove references to Sender Signing Policy document. Such 2570 consideration is implicitly included in Section 6.5. 2572 o Added ABNF for all tags. 2574 o Updated references (still includes some references to expired 2575 drafts, notably [ID-AUTH-RES]. 2577 o Significant wordsmithing. 2579 E.4 Changes since -allman-00 version 2581 The following changes were made between draft-allman-dkim-base-00 and 2582 draft-allman-dkim-base-01: 2584 o Changed "c=" tag to separate out header from body 2585 canonicalization. 2587 o Eliminated "nowsp" canonicalization in favor of "relaxed", which 2588 is somewhat less relaxed (but more secure) than "nowsp". 2590 o Moved the (empty) Compliance section to the Sender Signing Policy 2591 document. 2593 o Added several IANA Considerations. 2595 o Fixed a number of grammar and formatting errors. 2597 Intellectual Property Statement 2599 The IETF takes no position regarding the validity or scope of any 2600 Intellectual Property Rights or other rights that might be claimed to 2601 pertain to the implementation or use of the technology described in 2602 this document or the extent to which any license under such rights 2603 might or might not be available; nor does it represent that it has 2604 made any independent effort to identify any such rights. Information 2605 on the procedures with respect to rights in RFC documents can be 2606 found in BCP 78 and BCP 79. 2608 Copies of IPR disclosures made to the IETF Secretariat and any 2609 assurances of licenses to be made available, or the result of an 2610 attempt made to obtain a general license or permission for the use of 2611 such proprietary rights by implementers or users of this 2612 specification can be obtained from the IETF on-line IPR repository at 2613 http://www.ietf.org/ipr. 2615 The IETF invites any interested party to bring to its attention any 2616 copyrights, patents or patent applications, or other proprietary 2617 rights that may cover technology that may be required to implement 2618 this standard. Please address the information to the IETF at 2619 ietf-ipr@ietf.org. 2621 The IETF has been notified of intellectual property rights claimed in 2622 regard to some or all of the specification contained in this 2623 document. For more information consult the online list of claimed 2624 rights. 2626 Disclaimer of Validity 2628 This document and the information contained herein are provided on an 2629 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2630 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2631 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2632 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2633 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2634 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2636 Copyright Statement 2638 Copyright (C) The Internet Society (2006). This document is subject 2639 to the rights, licenses and restrictions contained in BCP 78, and 2640 except as set forth therein, the authors retain all their rights. 2642 Acknowledgment 2644 Funding for the RFC Editor function is currently provided by the 2645 Internet Society.