idnits 2.17.1 draft-ietf-dkim-base-03.txt: 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 2788. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2760. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2767. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2773. ** 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: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 2 characters 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 1227 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 (June 25, 2006) is 6512 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 2559, 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 (~~), 5 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: December 27, 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 June 25, 2006 14 DomainKeys Identified Mail (DKIM) Signatures 15 draft-ietf-dkim-base-03 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 December 27, 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 signer 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 2.6 DKIM-Quoted-Printable . . . . . . . . . . . . . . . . . . 8 80 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . 9 81 3.1 Selectors . . . . . . . . . . . . . . . . . . . . . . . . 9 82 3.2 Tag=Value Lists . . . . . . . . . . . . . . . . . . . . . 11 83 3.3 Signing and Verification Algorithms . . . . . . . . . . . 12 84 3.4 Canonicalization . . . . . . . . . . . . . . . . . . . . . 13 85 3.5 The DKIM-Signature header field . . . . . . . . . . . . . 18 86 3.6 Key Management and Representation . . . . . . . . . . . . 25 87 3.7 Computing the Message Hashes . . . . . . . . . . . . . . . 30 88 4. Semantics of Multiple Signatures . . . . . . . . . . . . . . 31 89 5. Signer Actions . . . . . . . . . . . . . . . . . . . . . . . 32 90 5.1 Determine if the Email Should be Signed and by Whom . . . 32 91 5.2 Select a private-key and corresponding selector 92 information . . . . . . . . . . . . . . . . . . . . . . . 32 93 5.3 Normalize the Message to Prevent Transport Conversions . . 33 94 5.4 Determine the header fields to Sign . . . . . . . . . . . 33 95 5.5 Compute the Message Hash and Signature . . . . . . . . . . 35 96 5.6 Insert the DKIM-Signature header field . . . . . . . . . . 36 97 6. Verifier Actions . . . . . . . . . . . . . . . . . . . . . . 37 98 6.1 Extract Signatures from the Message . . . . . . . . . . . 37 99 6.2 Communicate Verification Results . . . . . . . . . . . . . 42 100 6.3 Interpret Results/Apply Local Policy . . . . . . . . . . . 42 101 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 44 102 8. Security Considerations . . . . . . . . . . . . . . . . . . 44 103 8.1 Misuse of Body Length Limits ("l=" Tag) . . . . . . . . . 44 104 8.2 Misappropriated Private Key . . . . . . . . . . . . . . . 45 105 8.3 Key Server Denial-of-Service Attacks . . . . . . . . . . . 45 106 8.4 Attacks Against DNS . . . . . . . . . . . . . . . . . . . 46 107 8.5 Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 46 108 8.6 Limits on Revoking Keys . . . . . . . . . . . . . . . . . 47 109 8.7 Intentionally malformed Key Records . . . . . . . . . . . 47 110 8.8 Intentionally Malformed DKIM-Signature header fields . . . 47 111 8.9 Information Leakage . . . . . . . . . . . . . . . . . . . 48 112 8.10 Remote Timing Attacks . . . . . . . . . . . . . . . . . 48 113 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 114 9.1 Normative References . . . . . . . . . . . . . . . . . . . 48 115 9.2 Informative References . . . . . . . . . . . . . . . . . . 49 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 50 117 A. Example of Use (INFORMATIVE) . . . . . . . . . . . . . . . . 51 118 A.1 The user composes an email . . . . . . . . . . . . . . . . 51 119 A.2 The email is signed . . . . . . . . . . . . . . . . . . . 51 120 A.3 The email signature is verified . . . . . . . . . . . . . 52 121 B. Usage Examples (INFORMATIVE) . . . . . . . . . . . . . . . . 53 122 B.1 Simple Message Forwarding . . . . . . . . . . . . . . . . 53 123 B.2 Outsourced Business Functions . . . . . . . . . . . . . . 53 124 B.3 PDAs and Similar Devices . . . . . . . . . . . . . . . . . 54 125 B.4 Mailing Lists . . . . . . . . . . . . . . . . . . . . . . 54 126 B.5 Affinity Addresses . . . . . . . . . . . . . . . . . . . . 55 127 B.6 Third-party Message Transmission . . . . . . . . . . . . . 55 128 C. Creating a public key (INFORMATIVE) . . . . . . . . . . . . 56 129 D. MUA Considerations . . . . . . . . . . . . . . . . . . . . . 57 130 E. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 58 131 F. Edit History . . . . . . . . . . . . . . . . . . . . . . . . 58 132 F.1 Changes since -ietf-02 version . . . . . . . . . . . . . . 58 133 F.2 Changes since -ietf-01 version . . . . . . . . . . . . . . 59 134 F.3 Changes since -ietf-00 version . . . . . . . . . . . . . . 60 135 F.4 Changes since -allman-01 version . . . . . . . . . . . . . 60 136 F.5 Changes since -allman-00 version . . . . . . . . . . . . . 61 137 Intellectual Property and Copyright Statements . . . . . . . 62 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. 200 The signing identity is included as part of the signature header 201 field. 203 INFORMATIVE RATIONALE: The signing identity associated with a 204 DKIM signature is not required to match an address in any 205 particular header field because of the broad methods of 206 interpretation by recipient mail systems, including MUAs. 208 1.3 Scalability 210 DKIM is designed to support the extreme scalability requirements 211 which characterize the email identification problem. There are 212 currently over 70 million domains and a much larger number of 213 individual addresses. DKIM seeks to preserve the positive aspects of 214 the current email infrastructure, such as the ability for anyone to 215 communicate with anyone else without introduction. 217 1.4 Simple Key Management 219 DKIM differs from traditional hierarchical public-key systems in that 220 no key signing infrastructure is required; the verifier requests the 221 public key from the claimed signer directly. 223 The DNS is proposed as the initial mechanism for publishing public 224 keys. DKIM is designed to be extensible to other key fetching 225 services as they become available. 227 2. Terminology and Definitions 229 This section defines terms used in the rest of the document. Syntax 230 descriptions use the form described in Augmented BNF for Syntax 231 Specifications [RFC4234]. 233 2.1 Signers 235 Elements in the mail system that sign messages are referred to as 236 signers. These may be MUAs (Mail User Agents), MSAs (Mail Submission 237 Agents), MTAs (Mail Transfer Agents), or other agents such as mailing 238 list exploders. In general any signer will be involved in the 239 injection of a message into the message system in some way. The key 240 issue is that a message must be signed before it leaves the 241 administrative domain of the signer. 243 2.2 Verifiers 245 Elements in the mail system that verify signatures are referred to as 246 verifiers. These may be MTAs, Mail Delivery Agents (MDAs), or MUAs. 247 In most cases it is expected that verifiers will be close to an end 248 user (reader) of the message or some consuming agent such as a 249 mailing list exploder. 251 2.3 White Space 253 There are three forms of white space: 255 o WSP represents simple white space, i.e., a space or a tab 256 character, and is inherited from[RFC2822]. 258 o SWSP is streaming white space, defined as WSP plus the CR and LF 259 characters. 261 o FWS, also from [RFC2822], is folding white space. It allows 262 multiple lines separated by CRLF followed by at least one white 263 space, to be joined. 265 The formal ABNF for SWSP is: 267 SWSP = CR / LF / WSP ; streaming white space 269 2.4 Common ABNF Tokens 271 The following ABNF tokens are used elsewhere in this document. 273 hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] 274 base64string = 1*(ALPHA / DIGIT / "+" / "/" / "=" / SWSP) 276 2.5 Imported ABNF Tokens 278 The following tokens are imported from other RFCs as noted. Those 279 RFCs should be considered definitive. However, all tokens having 280 names beginning with "obs-" should be excluded from this import, as 281 they have been obsoleted and are expected to go away in future 282 editions of those RFCs. 284 The following tokens are imported from [RFC2821]: 286 o "Local-part" (implementation warning: this permits quoted 287 strings) 289 o "sub-domain" 291 The following definitions are imported from [RFC2822]: 293 o "WSP" (space or tab) 295 o "FWS" (folding white space) 297 o "field-name" (name of a header field) 299 o "dot-atom" (in the local-part of an email address) 301 The following tokens are imported from [RFC2045]: 303 o "qp-section" (a single line of quoted-printable-encoded text) 305 o "hex-octet" (a quoted-printable encoded octet) 307 INFORMATIVE NOTE: Be aware that the ABNF in RFC 2045 does not 308 obey the rules of RFC 4234 and must be interpreted accordingly, 309 particularly as regards case folding. 311 Other tokens not defined herein are imported from [RFC4234]. These 312 are intuitive primitives such as SP, ALPHA, CRLF, etc. 314 2.6 DKIM-Quoted-Printable 316 The DKIM-Quoted-Printable encoding syntax resembles that described in 317 Quoted-Printable [RFC2045] section 6.7: any character MAY be encoded 318 as an "=" followed by two hexadecimal digits from the alphabet 319 "0123456789ABCDEF" (no lower case characters permitted) representing 320 the hexadecimal-encoded integer value of that character. All control 321 characters (those with values < %x20), eight-bit characters (values > 322 %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon 323 (";", %x3B) MUST be encoded. Note that all white space, including 324 SPACE, CR and LF characters, MUST be encoded. After encoding, FWS 325 MAY be added at arbitrary locations in order to avoid excessively 326 long lines; such white space is NOT part of the value, and MUST be 327 removed before decoding. 329 ABNF: 330 dkim-quoted-printable = 331 *(FWS / hex-octet / dkim-safe-char) 332 ; hex-octet is from RFC 2045 333 dkim-safe-char = %x21-3A / %x3C / %x3E-7E 334 ; '!' - ':', '<', '>' - '~' 335 ; Characters not listed as "mail-safe" in 336 ; RFC 2049 are also not recommended. 338 INFORMATIVE NOTE: DKIM-Quoted-Printable differs from Quoted- 339 Printable as defined in RFC 2045 in several important ways: 341 1. White space in the input text, including CR and LF, must be 342 encoded. RFC 2045 does not require such encoding, and does 343 not permit encoded of CR or LF characters that are part of a 344 CRLF line break. 346 2. White space in the encoded text is ignored. This is to allow 347 DKIM-Quoted-Printable to be wrapped as needed in headers. In 348 particular, RFC 2045 requires that line breaks in the input be 349 represented as physical line breaks; that is not the case 350 here. 352 3. The "soft line break" syntax ("=" as the last non-white-space 353 character on the line) does not apply. 355 4. DKIM-Quoted-Printable does not require that encoded lines be 356 no more than 76 characters long (although there may be other 357 requirements depending on the context in which the encoded 358 text is being used). 360 3. Protocol Elements 362 Protocol Elements are conceptual parts of the protocol that are not 363 specific to either signers or verifiers. The protocol descriptions 364 for signers and verifiers are described in later sections (Signer 365 Actions (Section 5) and Verifier Actions (Section 6)). NOTE: This 366 section must be read in the context of those sections. 368 3.1 Selectors 370 To support multiple concurrent public keys per signing domain, the 371 key namespace is subdivided using "selectors". For example, 372 selectors might indicate the names of office locations (e.g., 373 "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date 374 (e.g., "january2005", "february2005", etc.), or even the individual 375 user. 377 Selectors are needed to support some important use cases. For 378 example: 380 o Domains which want to delegate signing capability for a specific 381 address for a given duration to a partner, such as an advertising 382 provider or other outsourced function. 384 o Domains which want to allow frequent travelers to send messages 385 locally without the need to connect with a particular MSA. 387 o "Affinity" domains (e.g., college alumni associations) which 388 provide forwarding of incoming mail but which do not operate a 389 mail submission agent for outgoing mail. 391 Periods are allowed in selectors and are component separators. If 392 keys are stored in DNS, the period defines sub-domain boundaries. 393 Sub-selectors might be used to combine dates with locations; for 394 example, "march2005.reykjavik". This can be used to allow delegation 395 of a portion of the selector name-space. 397 ABNF: 398 selector = sub-domain *( "." sub-domain ) 400 The number of public keys and corresponding selectors for each domain 401 are determined by the domain owner. Many domain owners will be 402 satisfied with just one selector whereas administratively distributed 403 organizations may choose to manage disparate selectors and key pairs 404 in different regions or on different email servers. 406 Beyond administrative convenience, selectors make it possible to 407 seamlessly replace public keys on a routine basis. If a domain 408 wishes to change from using a public key associated with selector 409 "january2005" to a public key associated with selector 410 "february2005", it merely makes sure that both public keys are 411 advertised in the public-key repository concurrently for the 412 transition period during which email may be in transit prior to 413 verification. At the start of the transition period, the outbound 414 email servers are configured to sign with the "february2005" private- 415 key. At the end of the transition period, the "january2005" public 416 key is removed from the public-key repository. 418 While some domains may wish to make selector values well known, 419 others will want to take care not to allocate selector names in a way 420 that allows harvesting of data by outside parties. E.g., if per-user 421 keys are issued, the domain owner will need to make the decision as 422 to whether to associate this selector directly with the user name, or 423 make it some unassociated random value, such as a fingerprint of the 424 public key. 426 INFORMATIVE IMPLEMENTERS' NOTE: reusing a selector with a new key 427 (for example, changing the key associated with a user's name) 428 makes it impossible to tell the difference between a message that 429 didn't verify because the key is no longer valid versus a message 430 that is actually forged. Signers should not change the key 431 associated with a selector. When creating a new key, signers 432 should associate it with a new selector. 434 3.2 Tag=Value Lists 436 DKIM uses a simple "tag=value" syntax in several contexts, including 437 in messages and domain signature records. 439 Values are a series of strings containing either plain text, base64 440 text (as defined in [RFC2045], section 6.8), qp-section (ibid, 441 section 6.7), or dkim-quoted-printable (as defined above). The name 442 of the tag will determine the encoding of each value; however, no 443 encoding may include the semicolon (";") character, since that 444 separates tag-specs. 446 Formally, the syntax rules are: 447 tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] 448 tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] 449 tag-name = ALPHA 0*ALNUMPUNC 450 tag-value = [ 1*VALCHAR 0*( 1*(WSP / FWS) 1*VALCHAR ) ] 451 ; WSP and FWS prohibited at beginning and end 452 VALCHAR = %x21-3A / %x3C-7E 453 ; EXCLAMATION to TILDE except SEMICOLON 454 ALNUMPUNC = ALPHA / DIGIT / "_" 456 Note that WSP is allowed anywhere around tags; in particular, any WSP 457 after the "=" and any WSP before the terminating ";" is not part of 458 the value; however, WSP inside the value is significant. 460 Tags MUST be interpreted in a case-sensitive manner. Values MUST be 461 processed as case sensitive unless the specific tag description of 462 semantics specifies case insensitivity. 464 Tags with duplicate names MUST NOT be specified within a single tag- 465 list. 467 Whitespace within a value MUST be retained unless explicitly excluded 468 by the specific tag description. 470 Tag=value pairs that represent the default value MAY be included to 471 aid legibility. 473 Unrecognized tags MUST be ignored. 475 Tags that have an empty value are not the same as omitted tags. An 476 omitted tag is treated as having the default value; a tag with an 477 empty value explicitly designates the empty string as the value. For 478 example, "g=" does not mean "g=*", even though "g=*" is the default 479 for that tag. 481 3.3 Signing and Verification Algorithms 483 DKIM supports multiple key signing/verification algorithms. Two 484 algorithms are defined by this specification at this time: rsa-sha1, 485 and rsa-sha256. The rsa-sha256 algorithm is the default if no 486 algorithm is specified. Verifiers MUST implement both rsa-sha1 and 487 rsa-sha256. Signers MUST implement and SHOULD sign using rsa-sha256. 489 3.3.1 The rsa-sha1 Signing Algorithm 491 The rsa-sha1 Signing Algorithm computes a message hash as described 492 in Section 3.7 below using SHA-1 as the hash-alg. That hash is then 493 signed by the signer using the RSA algorithm (defined in PKCS#1 494 version 1.5 [RFC3447]; in particular see section 5.2) with an 495 exponent of 65537 as the crypt-alg and the signer's private key. The 496 hash MUST NOT be truncated or converted into any form other than the 497 native binary form before being signed. 499 3.3.2 The rsa-sha256 Signing Algorithm 501 The rsa-sha256 Signing Algorithm computes a message hash as described 502 in Section 3.7 below using SHA-256 as the hash-alg. That hash is 503 then signed by the signer using the RSA algorithm (actually PKCS#1 504 version 1.5 [RFC3447]; in particular see section 5.2) with an 505 exponent of 65537 as the crypt-alg and the signer's private key. The 506 hash MUST NOT be truncated or converted into any form other than the 507 native binary form before being signed. 509 3.3.3 Other algorithms 511 Other algorithms MAY be defined in the future. Verifiers MUST ignore 512 any signatures using algorithms that they do not understand. 514 3.3.4 Key sizes 516 Selecting appropriate key sizes is a trade-off between cost, 517 performance and risk. Since short RSA keys more easily succumb to 518 off-line attacks, signers MUST use RSA keys of at least 1024 bits for 519 long-lived keys. Verifiers MUST be able to validate signatures with 520 keys ranging from 512 bits to 2048 bits, and they MAY be able to 521 validate signatures with larger keys. Security policies may use the 522 length of the signing key as one metric for determining whether a 523 signature is acceptable. 525 Factors that should influence the key size choice include: 527 o The practical constraint that large keys may not fit within a 512 528 byte DNS UDP response packet 530 o The security constraint that keys smaller than 1024 bits are 531 subject to off-line attacks 533 o Larger keys impose higher CPU costs to verify and sign email 535 o Keys can be replaced on a regular basis, thus their lifetime can 536 be relatively short 538 o The security goals of this specification are modest compared to 539 typical goals of public-key systems 541 See RFC3766 [RFC3766] for further discussion of selecting key sizes. 543 3.4 Canonicalization 545 Empirical evidence demonstrates that some mail servers and relay 546 systems modify email in transit, potentially invalidating a 547 signature. There are two competing perspectives on such 548 modifications. For most signers, mild modification of email is 549 immaterial to the authentication status of the email. For such 550 signers a canonicalization algorithm that survives modest in-transit 551 modification is preferred. 553 Other signers demand that any modification of the email, however 554 minor, result in an authentication failure. These signers prefer a 555 canonicalization algorithm that does not tolerate in-transit 556 modification of the signed email. 558 Some signers may be willing to accept modifications to header fields 559 that are within the bounds of email standards such as [RFC2822], but 560 are unwilling to accept any modification to the body of messages. 562 To satisfy all requirements, two canonicalization algorithms are 563 defined for each of the header and the body: a "simple" algorithm 564 that tolerates almost no modification and a "relaxed" algorithm that 565 tolerates common modifications such as white-space replacement and 566 header field line re-wrapping. A signer MAY specify either algorithm 567 for header or body when signing an email. If no canonicalization 568 algorithm is specified by the signer, the "simple" algorithm defaults 569 for both header and body. Verifiers MUST implement both 570 canonicalization algorithms. Further canonicalization algorithms MAY 571 be defined in the future; verifiers MUST ignore any signatures that 572 use unrecognized canonicalization algorithms. 574 In all cases, the header fields of the message are presented to the 575 signing algorithm first in the order indicated by the signature 576 header field and canonicalized using the indicated algorithm. Only 577 header fields listed as signed in the signature header field are 578 included. Note: the signature header field itself is presented at 579 the end of the hash, not with the other headers. The CRLF separating 580 the header field from the body is then presented, followed by the 581 canonicalized body. Note that the header and body may use different 582 canonicalization algorithms. 584 Canonicalization simply prepares the email for presentation to the 585 signing or verification algorithm. It MUST NOT change the 586 transmitted data in any way. Canonicalization of header fields and 587 body are described below. 589 NOTE: This section assumes that the message is already in "network 590 normal" format (e.g., text is ASCII encoded, lines are separated with 591 CRLF characters, etc.). See also Section 5.3 for information about 592 normalizing the message. 594 3.4.1 The "simple" Header Field Canonicalization Algorithm 596 The "simple" header canonicalization algorithm does not change header 597 fields in any way. Header fields MUST be presented to the signing or 598 verification algorithm exactly as they are in the message being 599 signed or verified. In particular, header field names MUST NOT be 600 case folded and white space MUST NOT be changed. 602 3.4.2 The "relaxed" Header Field Canonicalization Algorithm 604 The "relaxed" header canonicalization algorithm MUST apply the 605 following steps in order: 607 o Convert all header field names (not the header field values) to 608 lower case. For example, convert "SUBJect: AbC" to "subject: 609 AbC". 611 o Unfold all header field continuation lines as described in 612 [RFC2822]; in particular, lines with terminators embedded in 613 continued header field values (that is, CRLF sequences followed by 614 WSP) MUST be interpreted without the CRLF. Implementations MUST 615 NOT remove the CRLF at the end of the header field value. 617 o Convert all sequences of one or more WSP characters to a single SP 618 character. WSP characters here include those before and after a 619 line folding boundary. 621 o Delete all WSP characters at the end of each unfolded header field 622 value. 624 o Delete any WSP characters remaining before and after the colon 625 separating the header field name from the header field value. The 626 colon separator MUST be retained. 628 3.4.3 The "simple" Body Canonicalization Algorithm 630 The "simple" body canonicalization algorithm ignores all empty lines 631 at the end of the message body. An empty line is a line of zero 632 length after removal of the line terminator. It makes no other 633 changes to the message body. In more formal terms, the "simple" body 634 canonicalization algorithm reduces "CRLF 0*CRLF" at the end of the 635 body to a single "CRLF". 637 3.4.4 The "relaxed" Body Canonicalization Algorithm 639 [[This section may be deleted; see discussion below.]] The "relaxed" 640 body canonicalization algorithm: 642 o Ignores all white space at the end of lines. Implementations MUST 643 NOT remove the CRLF at the end of the line. 645 o Reduces all sequences of WSP within a line to a single SP 646 character. 648 o Ignores all empty lines at the end of the message body. "Empty 649 line" is defined in Section 3.4.3. 651 [[NON-NORMATIVE DISCUSSION: The authors are undecided whether to 652 leave the "relaxed" body canonicalization algorithm in to the 653 specification or delete it entirely. We believe that for the vast 654 majority of cases, the "simple" body canonicalization algorithm 655 should be sufficient. We simply do not have enough data to know 656 whether to retain the "relaxed" body canonicalization algorithm or 657 not.]] 659 3.4.5 Body Length Limits 661 A body length count MAY be specified to limit the signature 662 calculation to an initial prefix of the body text, measured in 663 octets. If the body length count is not specified then the entire 664 message body is signed and verified. 666 INFORMATIVE IMPLEMENTATION NOTE: Body length limits could be 667 useful in increasing signature robustness when sending to a 668 mailing list that both appends to content sent to it and does not 669 sign its messages. However, using such limits enables an attack 670 in which an attacker modifies a message to include content that 671 solely benefits the attacker. It is possible for the appended 672 content to completely replace the original content in the end 673 recipient's eyes and to defeat duplicate message detection 674 algorithms. To avoid this attack, signers should be wary of using 675 this tag, and verifiers might wish to ignore the tag or remove 676 text that appears after the specified content length, perhaps 677 based on other criteria. 679 The body length count allows the signer of a message to permit data 680 to be appended to the end of the body of a signed message. The body 681 length count is made following the canonicalization algorithm; for 682 example, any white space ignored by a canonicalization algorithm is 683 not included as part of the body length count. 685 INFORMATIVE RATIONALE: This capability is provided because it is 686 very common for mailing lists to add trailers to messages (e.g., 687 instructions how to get off the list). Until those messages are 688 also signed, the body length count is a useful tool for the 689 verifier since it may as a matter of policy accept messages having 690 valid signatures with extraneous data. 692 Signers of MIME messages that include a body length count SHOULD be 693 sure that the length extends to the closing MIME boundary string. 695 INFORMATIVE IMPLEMENTATION NOTE: A signer wishing to ensure that 696 the only acceptable modifications are to add to the MIME postlude 697 would use a body length count encompassing the entire final MIME 698 boundary string, including the final "--CRLF". A signer wishing 699 to allow additional MIME parts but not modification of existing 700 parts would use a body length count extending through the final 701 MIME boundary string, omitting the final "--CRLF". 703 A body length count of zero means that the body is completely 704 unsigned. 706 INFORMATIVE IMPLEMENTATION NOTE: Note that verifiers may choose 707 to modify their interpretation of messages with unsigned content, 708 including truncating the unsigned part, refusing to display the 709 unsigned part to the user, or simply treating the signature as 710 invalid. 712 Signers wishing to ensure that no modification of any sort can occur 713 should specify the "simple" algorithm and omit the body length count. 715 3.4.6 Canonicalization Examples (INFORMATIVE) 717 (In the following examples, actual white space is used only for 718 clarity. The actual input and output text is designated using 719 bracketed descriptors: "" for a space character, "" for a 720 tab character, and "" for a carriage-return/line-feed sequence. 721 For example, "X Y" and "XY" represent the same three 722 characters.) 724 Example 1: A message reading: 725 A: X 726 B : Y 727 Z 728 729 C 730 D E 731 732 734 when canonicalized using relaxed canonicalization for both header and 735 body results in a header reading: 736 a:X 737 b:Y Z 739 and a body reading: 740 C 741 D E 742 (postamble) 744 Example 2: The same message canonicalized using simple 745 canonicalization for both header and body results in a header 746 reading: 747 A: X 748 B : Y 749 Z 751 and a body reading: 752 C 753 D E 754 (postamble) 756 Example 3: When processed using relaxed header canonicalization and 757 simple body canonicalization, the canonicalized version has a header 758 of: 759 a:X 760 b:Y Z 762 and a body reading: 763 C 764 D E 765 (postamble) 767 3.5 The DKIM-Signature header field 769 The signature of the email is stored in the "DKIM-Signature:" header 770 field. This header field contains all of the signature and key- 771 fetching data. The DKIM-Signature value is a tag-list as described 772 in Section 3.2. 774 The "DKIM-Signature:" header field SHOULD be treated as though it 775 were a trace header field as defined in section 3.6 of [RFC2822], and 776 hence SHOULD NOT be reordered and SHOULD be prepended to the message. 777 In particular, the "DKIM-Signature" header field SHOULD precede the 778 original email header fields presented to the canonicalization and 779 signature algorithms. 781 The "DKIM-Signature:" header field being created or verified is 782 always included in the signature calculation, after the body of the 783 message; however, when calculating or verifying the signature, the 784 value of the b= tag (signature value) of that DKIM-Signature header 785 field MUST be treated as though it were the null string. Unknown 786 tags in the "DKIM-Signature:" header field MUST be included in the 787 signature calculation but MUST be otherwise ignored by verifiers. 788 Other "DKIM-Signature:" header fields that are included in the 789 signature should be treated as normal header fields; in particular, 790 the b= tag is not treated specially. 792 The encodings for each field type are listed below. Tags described 793 as qp-section are as described in section 6.7 of MIME Part One 794 [RFC2045], with the additional conversion of semicolon characters to 795 "=3B"; intuitively, this is one line of quoted-printable encoded 796 text. Tags described as dkim-quoted-printable are as defined above. 798 Tags on the DKIM-Signature header field along with their type and 799 requirement status are shown below. Defined tags are described 800 below. Unrecognized tags MUST be ignored. 802 v= Version (MUST be included). This tag defines the version of 803 this specification that applies to the signature record. It MUST 804 have the value 0.3. 806 ABNF: 808 sig-v-tag = %x76 [FWS] "=" [FWS] "0.3" 810 INFORMATIVE NOTE: DKIM-Signature version numbers are 811 expected to increase arithmetically as new versions of this 812 specification are released. 814 [[INFORMATIVE NOTE: Upon publication, this version number 815 should be changed to "1", and this note should be deleted.]] 817 a= The algorithm used to generate the signature (plain-text; 818 REQUIRED). Verifiers MUST support "rsa-sha1" and "rsa-sha256"; 819 signers SHOULD sign using "rsa-sha256". See Section 3.3 for a 820 description of algorithms. 822 ABNF: 824 sig-a-tag = %x61 [FWS] "=" [FWS] sig-a-tag-alg 825 sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h 826 sig-a-tag-k = "rsa" / x-sig-a-tag-k 827 sig-a-tag-h = "sha1" / "sha256" / x-sig-a-tag-h 828 x-sig-a-tag-k = ALPHA *(ALPHA / DIGIT) ; for later extension 829 x-sig-a-tag-h = ALPHA *(ALPHA / DIGIT) ; for later extension 831 b= The signature data (base64; REQUIRED). Whitespace is ignored in 832 this value and MUST be ignored when re-assembling the original 833 signature. In particular, the signing process can safely insert 834 FWS in this value in arbitrary places to conform to line-length 835 limits. See Signer Actions (Section 5) for how the signature is 836 computed. 838 ABNF: 840 sig-b-tag = %x62 [FWS] "=" [FWS] sig-b-tag-data 841 sig-b-tag-data = base64string 842 bh= The hash of the body part of the message (base64; REQUIRED). 843 Whitespace is ignored in this value and MUST be ignored when re- 844 assembling the original signature. In particular, the signing 845 process can safely insert FWS in this value in arbitrary places 846 to conform to line-length limits. See Section 3.7 for how the 847 body hash is computed. 849 ABNF: 851 sig-bh-tag = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data 852 sig-bh-tag-data = base64string 854 c= Message canonicalization (plain-text; OPTIONAL, default is 855 "simple/simple"). This tag informs the verifier of the type of 856 canonicalization used to prepare the message for signing. It 857 consists of two names separated by a "slash" (%d47) character, 858 corresponding to the header and body canonicalization algorithms 859 respectively. These algorithms are described in Section 3.4. If 860 only one algorithm is named, that algorithm is used for the 861 header and "simple" is used for the body. For example, 862 "c=relaxed" is treated the same as "c=relaxed/simple". 864 ABNF: 866 sig-c-tag = %x63 [FWS] "=" [FWS] sig-c-tag-alg 867 ["/" sig-c-tag-alg] 868 sig-c-tag-alg = "simple" / "relaxed" / x-sig-c-tag-alg 869 x-sig-c-tag-alg = hyphenated-word ; for later extension 871 d= The domain of the signing entity (plain-text; REQUIRED). This 872 is the domain that will be queried for the public key. This 873 domain MUST be the same as or a parent domain of the "i=" tag 874 (the signing identity, as described below). If the "t=s" tag is 875 specified in the key record referenced by the selector in the 876 "s=" tag, then the domain in the "d=" tag must be identical to 877 the domain specified in the "i=" tag. When presented with a 878 signature that does not meet these requirement, verifiers MUST 879 consider the signature invalid. 881 Internationalized domain names MUST be punycode-encoded 882 [RFC3492]. 884 ABNF: 886 sig-d-tag = %x64 [FWS] "=" [FWS] domain-name 887 domain-name = sub-domain 1*("." sub-domain) 888 ; from RFC 2821 Domain, but excluding address-literal 890 h= Signed header fields (plain-text, but see description; 891 REQUIRED). A colon-separated list of header field names that 892 identify the header fields presented to the signing algorithm. 893 The field MUST contain the complete list of header fields in the 894 order presented to the signing algorithm. The field MAY contain 895 names of header fields that do not exist when signed; nonexistent 896 header fields do not contribute to the signature computation 897 (that is, they are treated as the null input, including the 898 header field name, the separating colon, the header field value, 899 and any CRLF terminator). The field MUST NOT include the DKIM- 900 Signature header field that is being created or verified, but may 901 include others. Folding white space (FWS) MAY be included on 902 either side of the colon separator. Header field names MUST be 903 compared against actual header field names in a case insensitive 904 manner. This list MUST NOT be empty. See Section 5.4 for a 905 discussion of choosing header fields to sign. 907 ABNF: 909 sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name 910 0*( *FWS ":" *FWS hdr-name ) 911 hdr-name = field-name 913 INFORMATIVE EXPLANATION: By "signing" header fields that do 914 not actually exist, a signer can prevent insertion of those 915 header fields before verification. However, since a signer 916 cannot possibly know what header fields might be created in 917 the future, and that some MUAs might present header fields 918 that are embedded inside a message (e.g., as a message/rfc822 919 content type), the security of this solution is not total. 921 INFORMATIVE EXPLANATION: The exclusion of the header field 922 name and colon as well as the header field value for non- 923 existent header fields prevents an attacker from inserting an 924 actual header field with a null value. 926 i= Identity of the user or agent (e.g., a mailing list manager) on 927 behalf of which this message is signed (dkim-quoted-printable; 928 OPTIONAL, default is an empty local-part followed by an "@" 929 followed by the domain from the "d=" tag). The syntax is a 930 standard email address where the local-part MAY be omitted. The 931 domain part of the address MUST be the same as or a subdomain of 932 the value of the "d=" tag. 934 ABNF: 936 sig-i-tag = %x69 [FWS] "=" [FWS] [ Local-part ] "@" domain-name 938 INFORMATIVE NOTE: The local-part of the "i=" tag is optional 939 because in some cases a signer may not be able to establish a 940 verified individual identity. In such cases, the signer may 941 wish to assert that although it is willing to go as far as 942 signing for the domain, it is unable or unwilling to commit 943 to an individual user name within their domain. It can do so 944 by including the domain part but not the local-part of the 945 identity. 947 INFORMATIVE DISCUSSION: This document does not require the 948 value of the "i=" tag to match the identity in any message 949 header field fields. This is considered to be a verifier 950 policy issue. Constraints between the value of the "i=" tag 951 and other identities in other header fields seek to apply 952 basic authentication into the semantics of trust associated 953 with a role such as content author. Trust is a broad and 954 complex topic and trust mechanisms are subject to highly 955 creative attacks. The real-world efficacy of any but the 956 most basic bindings between the "i=" value and other 957 identities is not well established, nor is its vulnerability 958 to subversion by an attacker. Hence reliance on the use of 959 these options should be strictly limited. In particular it 960 is not at all clear to what extent a typical end-user 961 recipient can rely on any assurances that might be made by 962 successful use of the "i=" options. 964 l= Body length count (plain-text unsigned decimal integer; 965 OPTIONAL, default is entire body). This tag informs the verifier 966 of the number of octets in the body of the email after 967 canonicalization included in the cryptographic hash, starting 968 from 0 immediately following the CRLF preceding the body. This 969 value MUST NOT be larger than the actual number of octets in the 970 canonicalized message body. 972 INFORMATIVE IMPLEMENTATION WARNING: Use of the l= tag might 973 allow display of fraudulent content without appropriate 974 warning to end users. The l= tag is intended for increasing 975 signature robustness when sending to mailing lists that both 976 modify their content and do not sign their messages. 977 However, using the l= tag enables attacks in which an 978 intermediary with malicious intent modifies a message to 979 include content that solely benefits the attacker. It is 980 possible for the appended content to completely replace the 981 original content in the end recipient's eyes and to defeat 982 duplicate message detection algorithms. Examples are 983 described in Security Considerations (Section 8). To avoid 984 this attack, signers should be extremely wary of using this 985 tag, and verifiers might wish to ignore the tag or remove 986 text that appears after the specified content length. 988 INFORMATIVE NOTE: The value of the l= tag is constrained to 989 76 decimal digits, which will fit in a 256-bit binary integer 990 field. This constraint is not intended to predict the size 991 of future messages, but is intended to remind the implementer 992 to check the length of this and all other tags during 993 verification. Implementers may need to limit the actual 994 value expressed to a value smaller than 10^76, e.g., to allow 995 a message to fit within the available storage space. 997 ABNF: 999 sig-l-tag = %x6c [FWS] "=" [FWS] 1*76DIGIT 1001 q= A colon-separated list of query methods used to retrieve the 1002 public key (plain-text; OPTIONAL, default is "dns/txt"). Each 1003 query method is of the form "type[/options]", where the syntax 1004 and semantics of the options depends on the type and specified 1005 options. If there are multiple query mechanisms listed, the 1006 choice of query mechanism MUST NOT change the interpretation of 1007 the signature. Implementations MUST use the recognized query 1008 mechanisms in the order presented. 1010 Currently the only valid value is "dns/txt" which defines the DNS 1011 TXT record lookup algorithm described elsewhere in this document. 1012 The only option defined for the "dns" query type is "txt", which 1013 MUST be included. Verifiers and signers MUST support "dns/txt". 1015 ABNF: 1017 sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 1018 *([FWS] ":" [FWS] sig-q-tag-method) 1019 sig-q-tag-method = "txt/dns" / x-sig-q-tag-type ["/" x-sig-q-tag-args] 1020 x-sig-q-tag-type = hyphenated-word ; for future extension 1021 x-sig-q-tag-args = qp-hdr-value 1022 s= The selector subdividing the namespace for the "d=" (domain) tag 1023 (plain-text; REQUIRED). 1025 ABNF: 1027 sig-s-tag = %x73 [FWS] "=" [FWS] subdomain *( "." sub-domain ) 1029 t= Signature Timestamp (plain-text unsigned decimal integer; 1030 RECOMMENDED, default is an unknown creation time). The time that 1031 this signature was created. The format is the number of seconds 1032 since 00:00:00 on January 1, 1970 in the UTC time zone. The 1033 value is expressed as an unsigned integer in decimal ASCII. This 1034 value is not constrained to fit into a 31- or 32-bit integer. 1035 Implementations SHOULD be prepared to handle values up to at 1036 least 10^12 (until approximately AD 200,000; this fits into 40 1037 bits). To avoid denial of service attacks, implementations MAY 1038 consider any value longer than 12 digits to be infinite. 1040 ABNF: 1042 sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT 1044 x= Signature Expiration (plain-text unsigned decimal integer; 1045 RECOMMENDED, default is no expiration). The format is the same 1046 as in the "t=" tag, represented as an absolute date, not as a 1047 time delta from the signing timestamp. The value is expressed as 1048 an unsigned integer in decimal ASCII, with the same contraints on 1049 the value in the "t=" tag. Signatures MAY be considered invalid 1050 if the verification time at the verifier is past the expiration 1051 date. The verification time should be the time that the message 1052 was first received at the administrative domain of the verifier 1053 if that time is reliably available; otherwise the current time 1054 should be used. The value of the "x=" tag MUST be greater than 1055 the value of the "t=" tag if both are present. 1057 INFORMATIVE NOTE: The x= tag is not intended as an anti- 1058 replay defense. 1060 ABNF: 1062 sig-x-tag = %x78 [FWS] "=" [FWS] 1*12DIGIT 1063 z= Copied header fields (dkim-quoted-printable, but see 1064 description; OPTIONAL, default is null). A vertical-bar- 1065 separated list of selected header fields present when the message 1066 was signed, including both the field name and value. It is not 1067 required to include all header fields present at the time of 1068 signing. This field need not contain the same header fields 1069 listed in the "h=" tag. The header field text itself must encode 1070 the vertical bar ("|", %x7C) character (i.e., vertical bars in 1071 the z= text are metacharacters, and any actual vertical bar 1072 characters in a copied header field must be encoded). Note that 1073 all white space must be encoded, including white space between 1074 the colon and the header field value. After encoding, SWSP MAY 1075 be added at arbitrary locations in order to avoid excessively 1076 long lines; such white space is NOT part of the value of the 1077 header field, and MUST be removed before decoding. 1079 Verifiers MUST NOT use the header field names or copied values 1080 for checking the signature in any way. Copied header field 1081 values are for diagnostic use only. 1083 Header fields with characters requiring conversion (perhaps from 1084 legacy MTAs which are not [RFC2822] compliant) SHOULD be 1085 converted as described in MIME Part Three [RFC2047]. 1087 ABNF: 1088 sig-z-tag = %x7A [FWS] "=" [FWS] sig-z-tag-copy 1089 *( [FWS] "|" sig-z-tag-copy ) 1090 sig-z-tag-copy = hdr-name ":" qp-hdr-value 1091 qp-hdr-value = dkim-quoted-printable ; with "|" encoded 1093 INFORMATIVE EXAMPLE of a signature header field spread across 1094 multiple continuation lines: 1096 DKIM-Signature: a=rsa-sha256; d=example.net; s=brisbane; 1097 c=simple; q=dns/txt; i=@eng.example.net; t=1117574938; x=1118006938; 1098 h=from:to:subject:date; 1099 z=From:foo@eng.example.net|To:joe@example.com| 1100 Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700 1101 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 1102 VoG4ZHRNiYzR 1104 3.6 Key Management and Representation 1106 Signature applications require some level of assurance that the 1107 verification public key is associated with the claimed signer. Many 1108 applications achieve this by using public key certificates issued by 1109 a trusted third party. However, DKIM can achieve a sufficient level 1110 of security, with significantly enhanced scalability, by simply 1111 having the verifier query the purported signer's DNS entry (or some 1112 security-equivalent) in order to retrieve the public key. 1114 DKIM keys can potentially be stored in multiple types of key servers 1115 and in multiple formats. The storage and format of keys are 1116 irrelevant to the remainder of the DKIM algorithm. 1118 Parameters to the key lookup algorithm are the type of the lookup 1119 (the "q=" tag), the domain of the responsible signer (the "d=" tag of 1120 the DKIM-Signature header field), and the selector (the "s=" tag). 1122 public_key = dkim_find_key(q_val, d_val, s_val) 1124 This document defines a single binding, using DNS TXT records to 1125 distribute the keys. Other bindings may be defined in the future. 1127 3.6.1 Textual Representation 1129 It is expected that many key servers will choose to present the keys 1130 in an otherwise unstructured text format (for example, an XML form 1131 would not be considered to be unstructured text for this purpose). 1132 The following definition MUST be used for any DKIM key represented in 1133 an otherwise unstructured textual form. 1135 The overall syntax is a key-value-list as described in Section 3.2. 1136 The current valid tags are described below. Other tags MAY be 1137 present and MUST be ignored by any implementation that does not 1138 understand them. 1140 v= Version of the DKIM key record (plain-text; RECOMMENDED, default 1141 is "DKIM1"). If specified, this tag MUST be set to "DKIM1" 1142 (without the quotes). This tag MUST be the first tag in the 1143 response. Responses beginning with a "v=" tag with any other 1144 value MUST be discarded. 1146 ABNF: 1148 key-v-tag = %x76 [FWS] "=" [FWS] "DKIM1" 1150 g= granularity of the key (plain-text; OPTIONAL, default is "*"). 1151 This value MUST match the Local-part of the "i=" tag of the DKIM- 1152 Signature header field (or its default value of the empty string 1153 if "i=" is not specified), with a "*" character matching a 1154 sequence of zero or more arbitrary characters ("wildcarding"). 1155 The intent of this tag is to constrain which signing address can 1156 legitimately use this selector. An email with a signing address 1157 that does not match the value of this tag constitutes a failed 1158 verification. Wildcarding allows matching for addresses such as 1159 "user+*". An empty "g=" value never matches any addresses. 1161 ABNF: 1163 key-g-tag = %x67 [FWS] "=" [FWS] key-g-tag-lpart 1164 key-g-tag-lpart = [dot-atom] ["*"] [dot-atom] 1166 [[NON-NORMATIVE DISCUSSION POINT: "*" is legal in a dot- 1167 atom. This should probably use a different character for 1168 wildcarding. Unfortunately, the options are non-mnemonic 1169 (e.g., "@", "(", ":"). Alternatively we could insist on 1170 escaping a "*" intended as a literal "*" in the address.]] 1172 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to 1173 allowing all algorithms). A colon-separated list of hash 1174 algorithms that might be used. Signers and Verifiers MUST 1175 support the "sha1" hash algorithm. 1177 ABNF: 1179 key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg 1180 0*( [FWS] ":" [FWS] key-h-tag-alg ) 1181 key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg 1182 x-key-h-tag-alg = hyphenated-word ; for future extension 1184 k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and 1185 verifiers MUST support the "rsa" key type. The "rsa" key type 1186 indicates that an RSA public key, as defined in [RFC3447], 1187 sections 3.1 and A.1.1, is being used in the p= tag. (Note: the 1188 p= tag further encodes the value using the base64 algorithm.) 1190 ABNF: 1192 key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type 1193 key-k-tag-type = "rsa" / x-key-k-tag-type 1194 x-key-k-tag-type = hyphenated-word ; for future extension 1196 [[NON-NORMATIVE DISCUSSION NOTE: In some cases it can be 1197 hard to separate h= and k=; for example DSA implies that 1198 SHA-1 will be used. This might be an actual change to the 1199 spec depending on how we decide to fix this.]] 1201 n= Notes that might be of interest to a human (qp-section; 1202 OPTIONAL, default is empty). No interpretation is made by any 1203 program. This tag should be used sparingly in any key server 1204 mechanism that has space limitations (notably DNS). 1206 ABNF: 1208 key-n-tag = %x6e [FWS] "=" [FWS] qp-section 1210 p= Public-key data (base64; REQUIRED). An empty value means that 1211 this public key has been revoked. The syntax and semantics of 1212 this tag value before being encoded in base64 is defined by the 1213 k= tag. 1215 ABNF: 1217 key-p-tag = %x70 [FWS] "=" [FWS] base64string 1219 s= Service Type (plain-text; OPTIONAL; default is "*"). A colon- 1220 separated list of service types to which this record applies. 1221 Verifiers for a given service type MUST ignore this record if the 1222 appropriate type is not listed. Currently defined service types 1223 are: 1225 * matches all service types 1227 email electronic mail (not necessarily limited to SMTP) 1229 This tag is intended to permit signers to constrain the use of 1230 delegated keys, e.g., where a company is willing to delegate the 1231 right to send mail in their name to an outsourcer, but not to 1232 send IM or make VoIP calls. (This of course presumes that these 1233 keys are used in other services in the future.) 1235 ABNF: 1237 key-s-tag = %x73 [FWS] "=" [FWS] key-s-tag-type 1238 0*( [FWS] ":" [FWS] key-s-tag-type 1239 key-s-tag-type = "email" / "*" / x-key-s-tag-type 1240 x-key-s-tag-type = hyphenated-word ; for future extension 1241 t= Flags, represented as a colon-separated list of names (plain- 1242 text; OPTIONAL, default is no flags set). The defined flags are: 1244 y This domain is testing DKIM. Verifiers MUST NOT treat 1245 messages from signers in testing mode differently from 1246 unsigned email, even should the signature fail to verify. 1247 Verifiers MAY wish to track testing mode results to assist 1248 the signer. 1250 s Any DKIM-Signature header fields using the "i=" tag MUST have 1251 the same domain value on the right hand side of the "@" in 1252 the "i=" tag and the value of the "d=" tag. That is, the 1253 "i=" domain MUST NOT be a subdomain of "d=". 1255 ABNF: 1257 key-t-tag = %x74 [FWS] "=" [FWS] key-t-tag-flag 1258 0*( [FWS] ":" [FWS] key-t-tag-flag ) 1259 key-t-tag-flag = "y" / "s" / x-key-t-tag-flag 1260 x-key-t-tag-flag = hyphenated-word ; for future extension 1262 Unrecognized flags MUST be ignored. 1264 3.6.2 DNS binding 1266 A binding using DNS TXT records as a key service is hereby defined. 1267 All implementations MUST support this binding. 1269 3.6.2.1 Name Space 1271 All DKIM keys are stored in a subdomain named ""_domainkey"". Given 1272 a DKIM-Signature field with a "d=" tag of ""example.com"" and an "s=" 1273 tag of ""sample"", the DNS query will be for 1274 ""sample._domainkey.example.com"". 1276 The value of the "i=" tag is not used by the DNS binding. 1278 3.6.2.2 Resource Record Types for Key Storage 1280 The DNS Resource Record type used is specified by an option to the 1281 query-type ("q=") tag. The only option defined in this base 1282 specification is "txt", indicating the use of a TXT RR record. A 1283 later extension of this standard may define another Resource Record 1284 type, tentatively dubbed "DKK". 1286 TXT records are encoded as described in Section 3.6.1. 1288 3.7 Computing the Message Hashes 1290 Both signing and verifying message signatures starts with a step of 1291 computing two cryptographic hashes over the message. Signers will 1292 choose the parameters of the signature as described in Signer Actions 1293 (Section 5); verifiers will use the parameters specified in the 1294 "DKIM-Signature" header field being verified. In the following 1295 discussion, the names of the tags in the "DKIM-Signature" header 1296 field which either exists (when verifying) or will be created (when 1297 signing) are used. Note that canonicalization (Section 3.4) is only 1298 used to prepare the email for signing or verifying; it does not 1299 affect the transmitted email in any way. 1301 The signer or verifier must compute two hashes, one over the body of 1302 the message and one over the selected header fields of the message. 1303 Signers MUST compute them in the order shown. Verifiers MAY compute 1304 them in any order convenient to the verifier, provided that the 1305 result is semantically identical to the semantics that would be the 1306 case had they been computed in this order. 1308 In hash step 1, the signer or verifier MUST hash the message body, 1309 canonicalized using the body canonicalization algorithm specified in 1310 the "c=" tag and truncated to the length specified in the "l=" tag. 1311 That hash value is then converted to base64 form and inserted into 1312 the "bh=" tag of the DKIM-Signature: header field. 1314 In hash step 2, the signer or verifier MUST pass the following to the 1315 hash algorithm in the indicated order. 1317 1. The header fields specified by the "h=" tag, in the order 1318 specified in that tag, and canonicalized using the header 1319 canonicalization algorithm specified in the "c=" tag. Each 1320 header field must be terminated with a single CRLF. 1322 2. The "DKIM-Signature" header field that exists (verifying) or will 1323 be inserted (signing) in the message, with the value of the "b=" 1324 tag deleted (i.e., treated as the empty string), canonicalized 1325 using the header canonicalization algorithm specified in the "c=" 1326 tag, and without a trailing CRLF. 1328 All tags and their values in the DKIM-Signature header field are 1329 included in the cryptographic hash with the sole exception of the 1330 value portion of the "b=" (signature) tag, which MUST be treated as 1331 the null string. All tags MUST be included even if they might not be 1332 understood by the verifier. The header field MUST be presented to 1333 the hash algorithm after the body of the message rather than with the 1334 rest of the header fields and MUST be canonicalized as specified in 1335 the "c=" (canonicalization) tag. The DKIM-Signature header field 1336 MUST NOT be included in its own h= tag. 1338 When calculating the hash on messages that will be transmitted using 1339 base64 or quoted-printable encoding, signers MUST compute the hash 1340 after the encoding. Likewise, the verifier MUST incorporate the 1341 values into the hash before decoding the base64 or quoted-printable 1342 text. However, the hash MUST be computed before transport level 1343 encodings such as SMTP "dot-stuffing." 1345 With the exception of the canonicalization procedure described in 1346 Section 3.4, the DKIM signing process treats the body of messages as 1347 simply a string of characters. DKIM messages MAY be either in plain- 1348 text or in MIME format; no special treatment is afforded to MIME 1349 content. Message attachments in MIME format MUST be included in the 1350 content which is signed. 1352 More formally, the algorithm for the signature is: 1353 body-hash = hash-alg(canon_body) 1354 header-hash = hash-alg(canon_header || DKIM-SIG) 1355 signature = sig-alg(header-hash, key) 1357 where sig-alg is the signature algorithm specified by the "a=" tag, 1358 hash-alg is the hash algorithm specified by the "a=" tag, 1359 canon_header and canon_body are the canonicalized message header and 1360 body (respectively) as defined in Section 3.4 (excluding the DKIM- 1361 Signature header field), and DKIM-SIG is the canonicalized DKIM- 1362 Signature header field sans the signature value itself, but with 1363 body-hash included as the "bh=" tag. 1365 4. Semantics of Multiple Signatures 1367 A signer that is adding a signature to a message merely creates a new 1368 DKIM-Signature header, using the usual semantics of the h= option. A 1369 signer MAY sign previously existing DKIM-Signature headers using the 1370 method described in section Section 5.4 to sign trace headers. 1371 Signers should be cognizant that signing DKIM-Signature headers may 1372 result in signature failures with intermediaries that do not 1373 recognize that DKIM-Signature's are trace headers and unwittingly 1374 reorder them. 1376 When evaluating a message with multiple signatures, a verifier should 1377 evaluate signatures independently and on their own merits. For 1378 example, a verifier that by policy chooses not to accept signatures 1379 with deprecated cryptographic algorithms should consider such 1380 signatures invalid. As with messages with a single signature, 1381 verifiers are at liberty to use the presence of valid signatures as 1382 an input to local policy; likewise, the interpretation of multiple 1383 valid signatures in combination is a local policy decision of the 1384 verifier. 1386 Signers SHOULD NOT remove any DKIM-Signature header fields from 1387 messages they are signing, even if they know that the signatures 1388 cannot be verified. 1390 5. Signer Actions 1392 The following steps are performed in order by signers. 1394 5.1 Determine if the Email Should be Signed and by Whom 1396 A signer can obviously only sign email for domains for which it has a 1397 private-key and the necessary knowledge of the corresponding public 1398 key and selector information. However there are a number of other 1399 reasons beyond the lack of a private key why a signer could choose 1400 not to sign an email. 1402 A SUBMISSION server MAY sign if the submitter is authenticated by 1403 some secure means, e.g., SMTP AUTH. Within a trusted enclave the 1404 signing address MAY be derived from the header field according to 1405 local signer policy. Within a trusted enclave an MTA MAY do the 1406 signing. 1408 INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not 1409 sign Received header fields if the outgoing gateway MTA obfuscates 1410 Received header fields, for example to hide the details of 1411 internal topology. 1413 A signer MUST NOT sign an email if it is unwilling to be held 1414 responsible for the message; in particular, the signer SHOULD ensure 1415 that the submitter has a bona fide relationship with the signer and 1416 that the submitter has the right to use the address being claimed. 1418 If an email cannot be signed for some reason, it is a local policy 1419 decision as to what to do with that email. 1421 5.2 Select a private-key and corresponding selector information 1423 This specification does not define the basis by which a signer should 1424 choose which private-key and selector information to use. Currently, 1425 all selectors are equal as far as this specification is concerned, so 1426 the decision should largely be a matter of administrative 1427 convenience. Distribution and management of private-keys is also 1428 outside the scope of this document. 1430 INFORMATIVE OPERATIONS ADVICE: A signer should not sign with a 1431 private key when the selector containing the corresponding public 1432 key is expected to be removed before the verifier has an 1433 opportunity to validate the signature. The signer should 1434 anticipate that verifiers may choose to defer validation, perhaps 1435 until the message is actually read by the final recipient. In 1436 particular, when rotating to a new key-pair, signing should 1437 immediately commence with the new private key and the old public 1438 key should be retained for a reasonable validation interval before 1439 being removed from the key server. 1441 5.3 Normalize the Message to Prevent Transport Conversions 1443 Some messages, particularly those using 8-bit characters, are subject 1444 to modification during transit, notably conversion to 7-bit form. 1445 Such conversions will break DKIM signatures. In order to minimize 1446 the chances of such breakage, signers SHOULD convert the message to a 1447 suitable MIME content transfer encoding such as quoted-printable or 1448 base64 as described in MIME Part One [RFC2045] before signing. Such 1449 conversion is outside the scope of DKIM; the actual message SHOULD be 1450 converted to 7-bit MIME by an MUA or MSA prior to presentation to the 1451 DKIM algorithm. 1453 Should the message be submitted to the signer with any local encoding 1454 that will be modified before transmission, such conversion to 1455 canonical form MUST be done before signing. In particular, some 1456 systems use local line separator conventions (such as the Unix 1457 newline character) internally rather than the SMTP-standard CRLF 1458 sequence. All such local conventions MUST be converted to canonical 1459 format before signing. 1461 More generally, the signer MUST sign the message as it will be 1462 received by the verifier rather than in some local or internal form. 1464 5.4 Determine the header fields to Sign 1466 The From header field MUST be signed (that is, included in the h= tag 1467 of the resulting DKIM-Signature header field); any header field that 1468 describes the role of the signer (for example, the Sender or Resent- 1469 From header field if the signature is on behalf of the corresponding 1470 address and that address is different from the From address) MUST 1471 also be included. The signed header fields SHOULD also include the 1472 Subject and Date header fields as well as all MIME header fields. 1473 Signers SHOULD NOT sign an existing header field likely to be 1474 legitimately modified or removed in transit. In particular, 1475 [RFC2821] explicitly permits modification or removal of the "Return- 1476 Path" header field in transit. Signers MAY include any other header 1477 fields present at the time of signing at the discretion of the 1478 signer. It is RECOMMENDED that all other existing, non-repeatable 1479 header fields be signed. 1481 The DKIM-Signature header field is always implicitly signed and MUST 1482 NOT be included in the h= tag except to indicate that other 1483 preexisting signatures are also signed. 1485 Signers MUST sign any header fields that the signers wish to assert 1486 were present at the time of signing. Put another way, verifiers MAY 1487 treat unsigned header fields with extreme skepticism, up to and 1488 including refusing to display them to the end user. 1490 Signers MAY claim to have signed header fields that do not exist 1491 (that is, signers MAY include the header field name in the h= tag 1492 even if that header field does not exist in the message). When 1493 computing the signature, the non-existing header field MUST be 1494 treated as the null string (including the header field name, header 1495 field value, all punctuation, and the trailing CRLF). 1497 INFORMATIVE RATIONALE: This allows signers to explicitly assert 1498 the absence of a header field; if that header field is added later 1499 the signature will fail. 1501 Signers choosing to sign an existing replicated header field (such as 1502 Received) MUST sign the physically last instance of that header field 1503 in the header field block. Signers wishing to sign multiple 1504 instances of an existing replicated header field MUST include the 1505 header field name multiple times in the h= tag of the DKIM-Signature 1506 header field, and MUST sign such header fields in order from the 1507 bottom of the header field block to the top. The signer MAY include 1508 more header field names than there are actual corresponding header 1509 fields to indicate that additional header fields of that name SHOULD 1510 NOT be added. 1512 INFORMATIVE EXAMPLE: 1514 If the signer wishes to sign two existing Received header fields, 1515 and the existing header contains: 1517 Received: 1518 Received: 1519 Received: 1521 then the resulting DKIM-Signature header field should read: 1523 DKIM-Signature: ... h=Received : Received : ... 1525 and Received header fields and will be signed in that 1526 order. 1528 Signers SHOULD NOT sign header fields that might be replicated 1529 (either at the time of signing or potentially in the future), with 1530 the exception of trace header fields such as Received. Comment and 1531 non standard header fields (including X-* header fields) are 1532 permitted by [RFC2822] to be replicated; however, many such header 1533 fields are, by convention, not replicated. Signers need to 1534 understand the implications of signing header fields that might later 1535 be replicated, especially in the face of header field reordering. In 1536 particular, [RFC2822] only requires that trace header fields retain 1537 the original order. 1539 INFORMATIVE RATIONALE: Received: is allowed because these header 1540 fields, as well as Resent-* header fields, are already order- 1541 sensitive. 1543 INFORMATIVE ADMONITION: Despite the fact that [RFC2822] permits 1544 header field blocks to be reordered (with the exception of 1545 Received header fields), reordering of signed replicated header 1546 fields by intermediate MTAs will cause DKIM signatures to be 1547 broken; such anti-social behavior should be avoided. 1549 INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this 1550 specification, all end-user visible header fields should be signed 1551 to avoid possible "indirect spamming." For example, if the 1552 "Subject" header field is not signed, a spammer can resend a 1553 previously signed mail, replacing the legitimate subject with a 1554 one-line spam. 1556 INFORMATIVE NOTE: There has been some discussion that a Sender 1557 Signing Policy include the list of header fields that the signer 1558 always signs. N.B. In theory this is unnecessary, since as long 1559 as the signer really always signs the indicated header fields 1560 there is no possibility of an attacker replaying an existing 1561 message that has such an unsigned header field. 1563 5.5 Compute the Message Hash and Signature 1565 The signer MUST compute the message hash as described in Section 3.7 1566 and then sign it using the selected public-key algorithm. This will 1567 result in a DKIM-Signature header field which will include the body 1568 hash and a signature of the header hash, where that header includes 1569 the DKIM-Signature header field itself. 1571 To avoid possible ambiguity, a signer SHOULD either sign or remove 1572 any preexisting header fields which convey the results of previous 1573 verifications of the message signature prior to preparation for 1574 signing and transmission. Such header fields MUST NOT be signed if 1575 the signer is uncertain of the authenticity of the preexisting header 1576 field, for example, if it is not locally generated or signed by a 1577 previous DKIM-Signature line that the current signer has verified. 1579 Entities such as mailing list managers that implement DKIM and which 1580 modify the message or a header field (for example, inserting 1581 unsubscribe information) before retransmitting the message SHOULD 1582 check any existing signature on input and MUST make such 1583 modifications before re-signing the message; such signing SHOULD 1584 include any prior verification status, if any, that was inserted upon 1585 message receipt. 1587 The signer MAY elect to limit the number of bytes of the body that 1588 will be included in the hash and hence signed. The length actually 1589 hashed should be inserted in the "l=" tag of the "DKIM-Signature" 1590 header field. 1592 INFORMATIVE NOTE: A possible value to include in the "l=" tag 1593 would include the entire length of the message being signed, 1594 thereby allowing intermediate agents to append further information 1595 to the message without breaking the signature (e.g., a mailing 1596 list manager might add unsubscribe information to the body). A 1597 signer wishing to permit such intermediate agents to add another 1598 MIME body part to a "multipart/mixed" message should use a length 1599 that covers the entire presented message except for the trailing 1600 "--CRLF" characters; this is known as the "N-4" approach. Note 1601 that more than four characters may need to be stripped, since 1602 there could be postlude information that needs to be ignored. 1604 5.6 Insert the DKIM-Signature header field 1606 Finally, the signer MUST insert the "DKIM-Signature:" header field 1607 created in the previous step prior to transmitting the email. The 1608 "DKIM-Signature" header field MUST be the same as used to compute the 1609 hash as described above, except that the value of the "b=" tag MUST 1610 be the appropriately signed hash computed in the previous step, 1611 signed using the algorithm specified in the "a=" tag of the "DKIM- 1612 Signature" header field and using the private key corresponding to 1613 the selector given in the "s=" tag of the "DKIM-Signature" header 1614 field, as chosen above in Section 5.2 1616 The "DKIM-Signature" SHOULD be inserted before any header fields that 1617 it signs in the header block. 1619 INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this 1620 is to insert the "DKIM-Signature" header field at the beginning of 1621 the header block. In particular, it may be placed before any 1622 existing Received header fields. This is consistent with treating 1623 "DKIM-Signature" as a trace header. 1625 6. Verifier Actions 1627 Since a signer MAY expire a public key at any time, it is recommended 1628 that verification occur in a timely manner with the most timely place 1629 being during acceptance by the border MTA. 1631 A border or intermediate MTA MAY verify the message signatures and 1632 add a verification header field to incoming messages. This 1633 considerably simplifies things for the user, who can now use an 1634 existing mail user agent. Most MUAs have the ability to filter 1635 messages based on message header fields or content; these filters 1636 would be used to implement whatever policy the user wishes with 1637 respect to unsigned mail. 1639 A verifying MTA MAY implement a policy with respect to unverifiable 1640 mail, regardless of whether or not it applies the verification header 1641 field to signed messages. 1643 Verifiers MUST produce a result that is semantically equivalent to 1644 applying the following steps in the order listed. In practice, 1645 several of these steps can be performed in parallel in order to 1646 improve performance. 1648 6.1 Extract Signatures from the Message 1650 The order in which verifiers try DKIM-Signature header fields is not 1651 defined; verifiers MAY try signatures in any order they would like. 1652 For example, one implementation might prefer to try the signatures in 1653 textual order, whereas another might want to prefer signatures by 1654 identities that match the contents of the "From" header field over 1655 other identities. Verifiers MUST NOT attribute ultimate meaning to 1656 the order of multiple DKIM-Signature header fields. In particular, 1657 there is reason to believe that some relays will reorder the header 1658 fields in potentially arbitrary ways. 1660 INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as 1661 a clue to signing order in the absence of any other information. 1662 However, other clues as to the semantics of multiple signatures 1663 must be considered before using ordering. 1665 A verifier SHOULD NOT treat a message that has one or more bad 1666 signatures and no good signatures differently from a message with no 1667 signature at all; this is local policy and is beyond the scope of 1668 this document. 1670 When a signature successfully verifies, a verifier will either stop 1671 processing or attempt to verify any other signatures, at the 1672 discretion of the implementation. 1674 In the following description, text reading "return status 1675 (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL") 1676 means that the verifier MUST immediately cease processing that 1677 signature. The verifier SHOULD proceed to the next signature, if any 1678 is present, and completely ignore the bad signature. If the status 1679 is "PERMFAIL", the signature failed and should not be reconsidered. 1680 If the status is "TEMPFAIL", the signature could not be verified at 1681 this time but may be tried again later. A verifier MAY either defer 1682 the message for later processing, perhaps by queueing it locally or 1683 issuing a 451/4.7.5 SMTP reply, or try another signature; if no good 1684 signature is found and any of the signatures resulted in a TEMPFAIL 1685 status, the verifier MAY save the message for later processing. The 1686 "(explanation)" is not normative text; it is provided solely for 1687 clarification. 1689 Verifiers SHOULD ignore any DKIM-Signature header fields where the 1690 signature does not validate. Verifiers that are prepared to validate 1691 multiple signature header fields SHOULD proceed to the next signature 1692 header field, should it exist. However, verifiers MAY make note of 1693 the fact that an invalid signature was present for consideration at a 1694 later step. 1696 INFORMATIVE NOTE: The rationale of this requirement is to permit 1697 messages that have invalid signatures but also a valid signature 1698 to work. For example, a mailing list exploder might opt to leave 1699 the original submitter signature in place even though the exploder 1700 knows that it is modifying the message in some way that will break 1701 that signature, and the exploder inserts its own signature. In 1702 this case the message should succeed even in the presence of the 1703 known-broken signature. 1705 For each signature to be validated, the following steps should be 1706 performed in such a manner as to produce a result that is 1707 semantically equivalent to performing them in the indicated order. 1709 6.1.1 Validate the Signature Header Field 1711 Implementers MUST meticulously validate the format and values in the 1712 DKIM-Signature header field; any inconsistency or unexpected values 1713 MUST cause the header field to be completely ignored and the verifier 1714 to return PERMFAIL (signature syntax error). Being "liberal in what 1715 you accept" is definitely a bad strategy in this security context. 1716 Note however that this does not include the existence of unknown tags 1717 in a DKIM-Signature header field, which are explicitly permitted. 1719 Verifiers MUST ignore DKIM-Signature header fields with a "v=" tag 1720 that is inconsistent with this specification and return PERMFAIL 1721 (incompatible version). 1723 INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of 1724 course, choose to also verify signatures generated by older 1725 versions of this specification. 1727 If the DKIM-Signature header field does not contain any of the tags 1728 listed as required in Section 3.5 the verifier MUST ignore the DKIM- 1729 Signature header field and return PERMFAIL (signature missing 1730 required tag). 1732 If the "DKIM-Signature" header field does not contain the "i=" tag, 1733 the verifier MUST behave as though the value of that tag were "@d", 1734 where "d" is the value from the "d=" tag. 1736 Verifiers MUST confirm that the domain specified in the "d=" tag is 1737 the same as or a superdomain of the domain part of the "i=" tag. If 1738 not, the DKIM-Signature header field MUST be ignored and the verifier 1739 should return PERMFAIL (domain mismatch). 1741 Verifiers MAY ignore the DKIM-Signature header field and return 1742 PERMFAIL (signature expired) if it contains an "x=" tag and the 1743 signature has expired. 1745 6.1.2 Get the Public Key 1747 The public key for a signature is needed to complete the verification 1748 process. The process of retrieving the public key depends on the 1749 query type as defined by the "q=" tag in the "DKIM-Signature:" header 1750 field. Obviously, a public key need only be retrieved if the process 1751 of extracting the signature information is completely successful. 1752 Details of key management and representation are described in 1753 Section 3.6. The verifier MUST validate the key record and MUST 1754 ignore any public key records that are malformed. 1756 When validating a message, a verifier MUST perform the following 1757 steps in a manner that is semantically the same as performing them in 1758 the order indicated (in some cases the implementation may parallelize 1759 or reorder these steps, as long as the semantics remain unchanged): 1761 1. Retrieve the public key as described in (Section 3.6) using the 1762 domain from the "d=" tag and the selector from the "s=" tag. 1764 2. If the query for the public key fails to respond, the verifier 1765 MAY defer acceptance of this email and return TEMPFAIL (key 1766 unavailable). If verification is occuring during the incoming 1767 SMTP session, this MAY be achieved with a 451/4.7.5 SMTP reply 1768 code. Alternatively, the verifier MAY store the message in the 1769 local queue for later trial or ignore the signature. Note that 1770 storing a message in the local queue is subject to denial-of- 1771 service attacks. 1773 3. If the query for the public key fails because the corresponding 1774 key record does not exist, the verifier MUST immediately return 1775 PERMFAIL (no key for signature). 1777 4. If the query for the public key returns multiple key records, the 1778 verifier may choose one of the key records or may cycle through 1779 the key records performing the remainder of these steps on each 1780 record at the discretion of the implementer. The order of the 1781 key records is unspecified. If the verifier chooses to cycle 1782 through the key records, then the "return with ..." wording in 1783 the remainder of this section means "try the next key record, if 1784 any; if none, return to try another signature in the usual way." 1786 5. If the result returned from the query does not adhere to the 1787 format defined in this specification, the verifier MUST ignore 1788 the key record and return PERMFAIL (key syntax error). Verifiers 1789 are urged to validate the syntax of key records carefully to 1790 avoid attempted attacks. 1792 6. If the "g=" tag in the public key does not match the Local-part 1793 of the "i=" tag in the message signature header field, the 1794 verifier MUST ignore the key record and return PERMFAIL 1795 (inapplicable key). If the Local-part of the "i=" tag on the 1796 message signature is not present, the g= tag must be * (valid for 1797 all addresses in the domain) or the entire g= tag must be omitted 1798 (which defaults to "g=*"), otherwise the verifier MUST ignore the 1799 key record and return PERMFAIL (inapplicable key). Other than 1800 this test, verifiers SHOULD NOT treat a message signed with a key 1801 record having a g= tag any differently than one without; in 1802 particular, verifiers SHOULD NOT prefer messages that seem to 1803 have an individual signature by virtue of a g= tag versus a 1804 domain signature. 1806 7. If the "h=" tag exists in the public key record and the hash 1807 algorithm implied by the a= tag in the DKIM-Signature header is 1808 not included in the contents of the "h=" tag, the verifier MUST 1809 ignore the key record and return PERMFAIL (inappropriate hash 1810 algorithm). 1812 8. If the public key data (the "p=" tag) is empty then this key has 1813 been revoked and the verifier MUST treat this as a failed 1814 signature check and return PERMFAIL (key revoked). 1816 9. If the public key data is not suitable for use with the algorithm 1817 and key types defined by the "a=" and "k=" tags in the "DKIM- 1818 Signature" header field, the verifier MUST immediately return 1819 PERMFAIL (inappropriate key algorithm). 1821 6.1.3 Compute the Verification 1823 Given a signer and a public key, verifying a signature consists of 1824 the following steps. 1826 1. Based on the algorithm defined in the "c=" tag, the body length 1827 specified in the "l=" tag, and the header field names in the "h=" 1828 tag, create a canonicalized copy of the email as is described in 1829 Section 3.7. When matching header field names in the "h=" tag 1830 against the actual message header field, comparisons MUST be 1831 case-insensitive. 1833 2. Based on the algorithm indicated in the "a=" tag, compute the 1834 message hashes from the canonical copy as described in 1835 Section 3.7. 1837 3. Verify that the hash of the canonicalized message body computed 1838 in the previous step matches the hash value conveyed in the "bh=" 1839 tag. 1841 4. Using the signature conveyed in the "b=" tag, verify the 1842 signature against the header hash using the mechanism appropriate 1843 for the public key algorithm described in the "a=" tag. If the 1844 signature does not validate, the verifier SHOULD ignore the 1845 signature and return PERMFAIL (signature did not verify). 1847 5. Otherwise, the signature has correctly verified. 1849 INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to 1850 initiate the public-key query in parallel with calculating the 1851 hash as the public key is not needed until the final decryption is 1852 calculated. Implementations may also verify the signature on the 1853 message header before validating that the message hash listed in 1854 the "bh=" tag in the DKIM-Signature header field matches that of 1855 the actual message body; however, if the body hash does not match, 1856 the entire signature must be considered to have failed. 1858 A body length specified in the "l=" tag of the signature limits the 1859 number of bytes of the body passed to the verification algorithm. 1860 All data beyond that limit is not validated by DKIM. Hence, 1861 verifiers might treat a message that contains bytes beyond the 1862 indicated body length with suspicion, such as by truncating the 1863 message at the indicated body length, declaring the signature invalid 1864 (e.g., by returning PERMFAIL (unsigned content)), or conveying the 1865 partial verification to the policy module. 1867 INFORMATIVE IMPLEMENTATION NOTE: Verifiers that truncate the body 1868 at the indicated body length might pass on a malformed MIME 1869 message if the signer used the "N-4" trick described in the 1870 informative note in Section 5.5. Such verifiers may wish to check 1871 for this case and include a trailing "--CRLF" to avoid breaking 1872 the MIME structure. A simple way to achieve this might be to 1873 append "--CRLF" to any "multipart" message with a body length; if 1874 the MIME structure is already correctly formed, this will appear 1875 in the postlude and will not be displayed to the end user. 1877 6.2 Communicate Verification Results 1879 Verifiers wishing to communicate the results of verification to other 1880 parts of the mail system may do so in whatever manner they see fit. 1881 For example, implementations might choose to add an email header 1882 field to the message before passing it on. An example proposal for a 1883 header field is the Authentication-Results header field [ID-AUTH- 1884 RES]. Any such header field SHOULD be inserted before any existing 1885 DKIM-Signature or preexisting authentication status header fields in 1886 the header field block. 1888 INFORMATIVE ADVICE to MUA filter writers: Patterns intended to 1889 search for results header fields to visibly mark authenticated 1890 mail for end users should verify that such header field was added 1891 by the appropriate verifying domain and that the verified identity 1892 matches the author identity that will be displayed by the MUA. In 1893 particular, MUA filters should not be influenced by bogus results 1894 header fields added by attackers. 1896 6.3 Interpret Results/Apply Local Policy 1898 It is beyond the scope of this specification to describe what actions 1899 a verifier system should make, but an authenticated email presents an 1900 opportunity to a receiving system that unauthenticated email cannot. 1901 Specifically, an authenticated email creates a predictable identifier 1902 by which other decisions can reliably be managed, such as trust and 1903 reputation. Conversely, unauthenticated email lacks a reliable 1904 identifier that can be used to assign trust and reputation. It is 1905 reasonable to treat unauthenticated email as lacking any trust and 1906 having no positive reputation. 1908 In general verifiers SHOULD NOT reject messages solely on the basis 1909 of a lack of signature or an unverifiable signature. However, if the 1910 verifier does opt to reject such messages, and the verifier runs 1911 synchronously with the SMTP session and a signature is missing or 1912 does not verify, the MTA SHOULD reject the message with an error such 1913 as: 1915 550 5.7.1 Unsigned messages not accepted 1917 550 5.7.5 Message signature incorrect 1919 If it is not possible to fetch the public key, perhaps because the 1920 key server is not available, a temporary failure message MAY be 1921 generated, such as: 1923 451 4.7.5 Unable to verify signature - key server unavailable 1925 A temporary failure of the key server or other external service is 1926 the only condition that should use a 4xx SMTP reply code. In 1927 particular, signature verification failures MUST NOT return 4xx SMTP 1928 replies. 1930 Once the signature has been verified, that information MUST be 1931 conveyed to higher level systems (such as explicit allow/white lists 1932 and reputation systems) and/or to the end user. If the message is 1933 signed on behalf of any address other than that in the From: header 1934 field, the mail system SHOULD take pains to ensure that the actual 1935 signing identity is clear to the reader. 1937 The verifier MAY treat unsigned header fields with extreme 1938 skepticism, including marking them as untrusted or even deleting them 1939 before display to the end user. 1941 While the symptoms of a failed verification are obvious -- the 1942 signature doesn't verify -- establishing the exact cause can be more 1943 difficult. If a selector cannot be found, is that because the 1944 selector has been removed or was the value changed somehow in 1945 transit? If the signature line is missing is that because it was 1946 never there, or was it removed by an over-zealous filter? For 1947 diagnostic purposes, the exact reason why the verification fails 1948 SHOULD be made available to the policy module and possibly recorded 1949 in the system logs. However in terms of presentation to the end 1950 user, the result SHOULD be presented as a simple binary result: 1951 either the email is verified or it is not. If the email cannot be 1952 verified, then it SHOULD be rendered the same as all unverified email 1953 regardless of whether it looks like it was signed or not. 1955 7. IANA Considerations 1957 To avoid conflicts, tag names for the DKIM-Signature header and key 1958 records should be registered with IANA. 1960 Tag values for the "a=", "c=", and "q=" tags in the DKIM-Signature 1961 header field, and the "h=", "k=", "s=", and "t" tags in key records 1962 should be registered with IANA for the same reason. 1964 8. Security Considerations 1966 It has been observed that any mechanism that is introduced which 1967 attempts to stem the flow of spam is subject to intensive attack. 1968 DKIM needs to be carefully scrutinized to identify potential attack 1969 vectors and the vulnerability to each. See also [ID-DKIM-THREATS]. 1971 8.1 Misuse of Body Length Limits ("l=" Tag) 1973 Body length limits (in the form of the "l=" tag) are subject to 1974 several potential attacks. 1976 8.1.1 Addition of new MIME parts to multipart/* 1978 If the body length limit does not cover a closing MIME multipart 1979 section (including the trailing ""--CRLF"" portion), then it is 1980 possible for an attacker to intercept a properly signed multipart 1981 message and add a new body part. Depending on the details of the 1982 MIME type and the implementation of the verifying MTA and the 1983 receiving MUA, this could allow an attacker to change the information 1984 displayed to an end user from an apparently trusted source. 1986 *** Example appropriate here *** 1988 8.1.2 Addition of new HTML content to existing content 1990 Several receiving MUA implementations do not cease display after a 1991 """" tag. In particular, this allows attacks involving 1992 overlaying images on top of existing text. 1994 INFORMATIVE EXAMPLE: Appending the following text to an existing, 1995 properly closed message will in many MUAs result in inappropriate 1996 data being rendered on top of existing, correct data: 1998
1999 2001
2003 8.2 Misappropriated Private Key 2005 If the private key for a user is resident on their computer and is 2006 not protected by an appropriately secure mechanism, it is possible 2007 for malware to send mail as that user and any other user sharing the 2008 same private key. The malware would, however, not be able to 2009 generate signed spoofs of other signers' addresses, which would aid 2010 in identification of the infected user and would limit the 2011 possibilities for certain types of attacks involving socially- 2012 engineered messages. 2014 A larger problem occurs if malware on many users' computers obtains 2015 the private keys for those users and transmits them via a covert 2016 channel to a site where they can be shared. The compromised users 2017 would likely not know of the misappropriation until they receive 2018 "bounce" messages from messages they are purported to have sent. 2019 Many users might not understand the significance of these bounce 2020 messages and would not take action. 2022 One countermeasure is to use a user-entered passphrase to encrypt the 2023 private key, although users tend to choose weak passphrases and often 2024 reuse them for different purposes, possibly allowing an attack 2025 against DKIM to be extended into other domains. Nevertheless, the 2026 decoded private key might be briefly available to compromise by 2027 malware when it is entered, or might be discovered via keystroke 2028 logging. The added complexity of entering a passphrase each time one 2029 sends a message would also tend to discourage the use of a secure 2030 passphrase. 2032 A somewhat more effective countermeasure is to send messages through 2033 an outgoing MTA that can authenticate the submitter using existing 2034 techniques (e.g., SMTP Authentication), possibly validate the message 2035 itself (e.g., verify that the header is legitimate and that the 2036 content passes a spam content check), and sign the message using a 2037 key appropriate for the submitter address. Such an MTA can also 2038 apply controls on the volume of outgoing mail each user is permitted 2039 to originate in order to further limit the ability of malware to 2040 generate bulk email. 2042 8.3 Key Server Denial-of-Service Attacks 2044 Since the key servers are distributed (potentially separate for each 2045 domain), the number of servers that would need to be attacked to 2046 defeat this mechanism on an Internet-wide basis is very large. 2047 Nevertheless, key servers for individual domains could be attacked, 2048 impeding the verification of messages from that domain. This is not 2049 significantly different from the ability of an attacker to deny 2050 service to the mail exchangers for a given domain, although it 2051 affects outgoing, not incoming, mail. 2053 A variation on this attack is that if a very large amount of mail 2054 were to be sent using spoofed addresses from a given domain, the key 2055 servers for that domain could be overwhelmed with requests. However, 2056 given the low overhead of verification compared with handling of the 2057 email message itself, such an attack would be difficult to mount. 2059 8.4 Attacks Against DNS 2061 Since DNS is a required binding for key services, specific attacks 2062 against DNS must be considered. 2064 While the DNS is currently insecure [RFC3833], it is expected that 2065 the security problems should and will be solved by DNSSEC [RFC4033], 2066 and all users of the DNS will reap the benefit of that work. 2068 Secondly, the types of DNS attacks relevant to DKIM are very costly 2069 and are far less rewarding than DNS attacks on other Internet 2070 applications. 2072 To systematically thwart the intent of DKIM, an attacker must conduct 2073 a very costly and very extensive attack on many parts of the DNS over 2074 an extended period. No one knows for sure how attackers will 2075 respond, however the cost/benefit of conducting prolonged DNS attacks 2076 of this nature is expected to be uneconomical. 2078 Finally, DKIM is only intended as a "sufficient" method of proving 2079 authenticity. It is not intended to provide strong cryptographic 2080 proof about authorship or contents. Other technologies such as 2081 OpenPGP [RFC2440] and S/MIME [RFC3851] address those requirements. 2083 A second security issue related to the DNS revolves around the 2084 increased DNS traffic as a consequence of fetching Selector-based 2085 data as well as fetching signing domain policy. Widespread 2086 deployment of DKIM will result in a significant increase in DNS 2087 queries to the claimed signing domain. In the case of forgeries on a 2088 large scale, DNS servers could see a substantial increase in queries. 2090 8.5 Replay Attacks 2092 In this attack, a spammer sends a message to be spammed to an 2093 accomplice, which results in the message being signed by the 2094 originating MTA. The accomplice resends the message, including the 2095 original signature, to a large number of recipients, possibly by 2096 sending the message to many compromised machines that act as MTAs. 2097 The messages, not having been modified by the accomplice, have valid 2098 signatures. 2100 Partial solutions to this problem involve the use of reputation 2101 services to convey the fact that the specific email address is being 2102 used for spam, and that messages from that signer are likely to be 2103 spam. This requires a real-time detection mechanism in order to 2104 react quickly enough. However, such measures might be prone to 2105 abuse, if for example an attacker resent a large number of messages 2106 received from a victim in order to make them appear to be a spammer. 2108 Large verifiers might be able to detect unusually large volumes of 2109 mails with the same signature in a short time period. Smaller 2110 verifiers can get substantially the same volume information via 2111 existing collaborative systems. 2113 8.6 Limits on Revoking Keys 2115 When a large domain detects undesirable behavior on the part of one 2116 of its users, it might wish to revoke the key used to sign that 2117 user's messages in order to disavow responsibility for messages which 2118 have not yet been verified or which are the subject of a replay 2119 attack. However, the ability of the domain to do so can be limited 2120 if the same key, for scalability reasons, is used to sign messages 2121 for many other users. Mechanisms for explicitly revoking keys on a 2122 per-address basis have been proposed but require further study as to 2123 their utility and the DNS load they represent. 2125 8.7 Intentionally malformed Key Records 2127 It is possible for an attacker to publish key records in DNS which 2128 are intentionally malformed, with the intent of causing a denial-of- 2129 service attack on a non-robust verifier implementation. The attacker 2130 could then cause a verifier to read the malformed key record by 2131 sending a message to one of its users referencing the malformed 2132 record in a (not necessarily valid) signature. Verifiers MUST 2133 thoroughly verify all key records retrieved from DNS and be robust 2134 against intentionally as well as unintentionally malformed key 2135 records. 2137 8.8 Intentionally Malformed DKIM-Signature header fields 2139 Verifiers MUST be prepared to receive messages with malformed DKIM- 2140 Signature header fields, and thoroughly verify the header field 2141 before depending on any of its contents. 2143 8.9 Information Leakage 2145 An attacker could determine when a particular signature was verified 2146 by using a per-message selector and then monitoring their DNS traffic 2147 for the key lookup. This would act as the equivalent of a "web bug" 2148 for verification time rather than when the message was read. 2150 8.10 Remote Timing Attacks 2152 In some cases it may be possible to extract private keys using a 2153 remote timing attack [BONEH03]. Implementations should consider 2154 obfuscating the timing to prevent such attacks. 2156 9. References 2158 9.1 Normative References 2160 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2161 Extensions (MIME) Part One: Format of Internet Message 2162 Bodies", RFC 2045, November 1996. 2164 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 2165 Part Three: Message header field Extensions for Non-ASCII 2166 Text", RFC 2047, November 1996. 2168 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2169 Requirement Levels", BCP 14, RFC 2119, March 1997. 2171 [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, 2172 April 2001. 2174 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 2175 April 2001. 2177 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2178 Standards (PKCS) #1: RSA Cryptography Specifications 2179 Version 2.1", RFC 3447, February 2003. 2181 [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode 2182 for Internationalized Domain Names in Application(IDNA)", 2183 March 2003. 2185 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2186 Specifications: ABNF", RFC 4234, October 2005. 2188 9.2 Informative References 2190 [BONEH03] Proc. 12th USENIX Security Symposium, "Remote Timing 2191 Attacks are Practical", 2003, . 2194 [ID-AUTH-RES] 2195 Kucherawy, M., "Message header field for Indicating Sender 2196 Authentication Status", 2197 draft-kucherawy-sender-auth-header-02 (work in progress), 2198 February 2006. 2200 [ID-DKIM-THREATS] 2201 Fenton, J., "Analysis of Threats Motivating DomainKeys 2202 Identified Mail (DKIM)", draft-fenton-dkim-threats-02 2203 (work in progress), April 2006. 2205 [RFC1847] Galvin, J., Murphy, S., Crocker, S., and N. Freed, 2206 "Security Multiparts for MIME: Multipart/Signed and 2207 Multipart/Encrypted", RFC 1847, October 1995. 2209 [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, 2210 "OpenPGP Message Format", RFC 2440, November 1998. 2212 [RFC3766] Orman, H. and P. Hoffman, "Determing Strengths for Public 2213 Keys Used For Exchanging Symmetric Keys", RFC 3766, 2214 April 2004. 2216 [RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain 2217 Name System (DNS)", RFC 3833, August 2004. 2219 [RFC3851] Ramsdell, B., "S/MIME Version 3 Message Specification", 2220 RFC 3851, June 1999. 2222 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2223 Rose, "DNS Security Introduction and Requirements", 2224 RFC 4033, March 2005. 2226 Authors' Addresses 2228 Eric Allman 2229 Sendmail, Inc. 2230 6425 Christie Ave, Suite 400 2231 Emeryville, CA 94608 2232 USA 2234 Phone: +1 510 594 5501 2235 Email: eric+dkim@sendmail.org 2236 URI: 2238 Jon Callas 2239 PGP Corporation 2240 3460 West Bayshore 2241 Palo Alto, CA 94303 2242 USA 2244 Phone: +1 650 319 9016 2245 Email: jon@pgp.com 2247 Mark Delany 2248 Yahoo! Inc 2249 701 First Avenue 2250 Sunnyvale, CA 95087 2251 USA 2253 Phone: +1 408 349 6831 2254 Email: markd+dkim@yahoo-inc.com 2255 URI: 2257 Miles Libbey 2258 Yahoo! Inc 2259 701 First Avenue 2260 Sunnyvale, CA 95087 2261 USA 2263 Email: mlibbeymail-mailsig@yahoo.com 2264 URI: 2266 Jim Fenton 2267 Cisco Systems, Inc. 2268 MS SJ-24/2 2269 170 W. Tasman Drive 2270 San Jose, CA 95134-1706 2271 USA 2273 Phone: +1 408 526 5914 2274 Email: fenton@cisco.com 2275 URI: 2277 Michael Thomas 2278 Cisco Systems, Inc. 2279 MS SJ-9/2 2280 170 W. Tasman Drive 2281 San Jose, CA 95134-1706 2283 Phone: +1 408 525 5386 2284 Email: mat@cisco.com 2286 Appendix A. Example of Use (INFORMATIVE) 2288 This section shows the complete flow of an email from submission to 2289 final delivery, demonstrating how the various components fit 2290 together. 2292 A.1 The user composes an email 2294 From: Joe SixPack 2295 To: Suzie Q 2296 Subject: Is dinner ready? 2297 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2298 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2300 Hi. 2302 We lost the game. Are you hungry yet? 2304 Joe. 2306 A.2 The email is signed 2308 This email is signed by the example.com outbound email server and now 2309 looks like this: 2311 DKIM-Signature: a=rsa-sha1; s=brisbane; d=example.com; 2312 c=simple; q=dns/txt; i=joe@football.example.com; 2313 h=Received : From : To : Subject : Date : Message-ID; 2314 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 2315 VoG4ZHRNiYzR; 2316 Received: from dsl-10.2.3.4.football.example.com [10.2.3.4] 2317 by submitserver.example.com with SUBMISSION; 2318 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2319 From: Joe SixPack 2320 To: Suzie Q 2321 Subject: Is dinner ready? 2322 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2323 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2325 Hi. 2327 We lost the game. Are you hungry yet? 2329 Joe. 2331 The signing email server requires access to the private-key 2332 associated with the "brisbane" selector to generate this signature. 2334 A.3 The email signature is verified 2336 The signature is normally verified by an inbound SMTP server or 2337 possibly the final delivery agent. However, intervening MTAs can 2338 also perform this verification if they choose to do so. The 2339 verification process uses the domain "example.com" extracted from the 2340 "d=" tag and the selector "brisbane" from the "s=" tag in the "DKIM- 2341 Signature" header field to form the DNS DKIM query for: 2343 brisbane._domainkey.example.com 2345 Signature verification starts with the physically last "Received" 2346 header field, the "From" header field, and so forth, in the order 2347 listed in the "h=" tag. Verification follows with a single CRLF 2348 followed by the body (starting with "Hi."). The email is canonically 2349 prepared for verifying with the "simple" method. The result of the 2350 query and subsequent verification of the signature is stored in the 2351 "Authentication-Results" header field line. After successful 2352 verification, the email looks like this: 2354 Authentication-Results: shopping.example.net 2355 header.from=joe@football.example.com; dkim=pass 2356 Received: from mout23.football.example.com (192.168.1.1) 2357 by shopping.example.net with SMTP; 2358 Fri, 11 Jul 2003 21:01:59 -0700 (PDT) 2359 DKIM-Signature: a=rsa-sha1; s=brisbane; d=example.com; 2360 c=simple; q=dns/txt; i=joe@football.example.com; 2361 h=Received : From : To : Subject : Date : Message-ID; 2362 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 2363 VoG4ZHRNiYzR 2364 Received: from dsl-10.2.3.4.network.example.com [10.2.3.4] 2365 by submitserver.example.com with SUBMISSION; 2366 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2367 From: Joe SixPack 2368 To: Suzie Q 2369 Subject: Is dinner ready? 2370 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2371 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2373 Hi. 2375 We lost the game. Are you hungry yet? 2377 Joe. 2379 Appendix B. Usage Examples (INFORMATIVE) 2381 Studies in this appendix are for informational purposes only. In no 2382 case should these examples be used as guidance when creating an 2383 implementation. 2385 B.1 Simple Message Forwarding 2387 In some cases the recipient may request forwarding of email messages 2388 from the original address to another, through the use of a Unix 2389 .forward file or equivalent. In this case messages are typically 2390 forwarded without modification, except for the addition of a Received 2391 header field to the message and a change in the Envelope-to address. 2392 In this case, the eventual recipient should be able to verify the 2393 original signature since the signed content has not changed, and 2394 attribute the message correctly. 2396 B.2 Outsourced Business Functions 2398 Outsourced business functions represent a use case that motivates the 2399 need for selectors (the "s=" signature tag) and granularity (the "g=" 2400 key tag). Examples of outsourced business functions are legitimate 2401 email marketing providers and corporate benefits providers. In 2402 either case, the outsourced function would like to be able to send 2403 messages using the email domain of the client company. At the same 2404 time, the client may be reluctant to register a key for the provider 2405 that grants the ability to send messages for any address in the 2406 domain. 2408 The outsourcing company can generate a keypair and the client company 2409 can register the public key using a unique selector for a specific 2410 address such as winter-promotions@example.com by specifying a 2411 granularity of "g=winter-promotions" or "g=*-promotions" (to allow a 2412 range of addresses). This would enable the provider to send messages 2413 using that specific address and have them verify properly. The 2414 client company retains control over the email address because it 2415 retains the ability to revoke the key at any time. 2417 B.3 PDAs and Similar Devices 2419 PDAs are one example of the use of multiple keys per user. Suppose 2420 that John Doe wanted to be able to send messages using his corporate 2421 email address, jdoe@example.com, and the device did not have the 2422 ability to make a VPN connection to the corporate network. If the 2423 device was equipped with a private key registered for 2424 jdoe@example.com by the administrator of that domain, and appropriate 2425 software to sign messages, John could send signed messages through 2426 the outgoing network of the PDA service provider. 2428 B.4 Mailing Lists 2430 There is a wide range of behavior in forwarders and mailing lists 2431 (collectively called "forwarders" below), ranging from those which 2432 make no modification to the message itself (other than to add a 2433 Received header field and change the envelope information) to those 2434 which may add header fields, change the Subject header field, add 2435 content to the body (typically at the end), or reformat the body in 2436 some manner. 2438 Forwarders which do not modify the body or signed header fields of a 2439 message with a valid signature may re-sign the message as described 2440 below. 2442 Forwarders which make any modification to a message that could result 2443 in its signature becoming invalid should sign or re-sign using an 2444 appropriate identification (e.g., mailing-list-name@example.net). 2445 Since in so doing the (re-)signer is taking responsibility for the 2446 content of the message, modifying forwarders may elect to forward or 2447 re-sign only for messages which were received with valid signatures 2448 or other indications that the messages being signed are not spoofed. 2450 Forwarders which wish to re-sign a message must apply a Sender header 2451 field to the message to identify the address being used to sign the 2452 message and must remove any preexisting Sender header field as 2453 required by [RFC2822]. The forwarder applies a new DKIM-Signature 2454 header field with the signature, public key, and related information 2455 of the forwarder. 2457 B.5 Affinity Addresses 2459 "Affinity addresses" are email addresses that users employ to have an 2460 email address that is independent of any changes in email service 2461 provider they may choose to make. They are typically associated with 2462 college alumni associations, professional organizations, and 2463 recreational organizations with which they expect to have a long-term 2464 relationship. These domains usually provide forwarding of incoming 2465 email, but (currently) usually depend on the user to send outgoing 2466 messages through their own service provider's MTA. They usually have 2467 an associated Web application which authenticates the user and allows 2468 the forwarding address to be changed. 2470 With DKIM, affinity domains could use the Web application to allow 2471 users to register their own public keys to be used to sign messages 2472 on behalf of their affinity address. This is another application 2473 that takes advantage of user-level keying, and domains used for 2474 affinity addresses would typically have a very large number of user- 2475 level keys. Alternatively, the affinity domain could handle outgoing 2476 mail, operating a mail submission agent that authenticates users 2477 before accepting and signing messages for them. This is of course 2478 dependent on the user's service provider not blocking the relevant 2479 TCP ports used for mail submission. 2481 B.6 Third-party Message Transmission 2483 Third-party message transmission refers to the authorized sending of 2484 mail by an Internet application on behalf of a user. For example, a 2485 website providing news may allow the reader to forward a copy of the 2486 message to a friend; this is typically done using the reader's email 2487 address. This is sometimes referred to as the "Evite problem", named 2488 after the website of the same name that allows a user to send 2489 invitations to friends. 2491 One way this can be handled is to continue to put the reader's email 2492 address in the From header field of the message, but put an address 2493 owned by the site into the Sender header field, and sign the message 2494 on behalf of that address. A verifying MTA could accept this and 2495 rewrite the From header field to indicate the address that was 2496 verified, i.e., From: John Doe via news@news-site.com 2497 . (However, such rewriting must be done after the 2498 verification pass is complete, and will break any later attempts to 2499 re-verify.) 2501 Appendix C. Creating a public key (INFORMATIVE) 2503 The default signature is an RSA signed SHA256 digest of the complete 2504 email. For ease of explanation, the openssl command is used to 2505 describe the mechanism by which keys and signatures are managed. One 2506 way to generate a 768 bit private-key suitable for DKIM, is to use 2507 openssl like this: 2509 $ openssl genrsa -out rsa.private 1024 2511 This results in the file rsa.private containing the key information 2512 similar to this: 2514 -----BEGIN RSA PRIVATE KEY----- 2515 MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC 2516 jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb 2517 to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB 2518 AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX 2519 /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ 2520 gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO 2521 n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m 2522 3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/ 2523 eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj 2524 7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA 2525 qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf 2526 eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX 2527 GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc= 2528 -----END RSA PRIVATE KEY----- 2530 To extract the public-key component from the private-key, use openssl 2531 like this: 2533 $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM 2535 This results in the file rsa.public containing the key information 2536 similar to this: 2538 -----BEGIN PUBLIC KEY----- 2539 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM 2540 oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R 2541 tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI 2542 MmPSPDdQPNUYckcQ2QIDAQAB 2543 -----END PUBLIC KEY----- 2545 This public-key data (without the BEGIN and END tags) is placed in 2546 the DNS. With the signature, canonical email contents, and public 2547 key, a verifying system can test the validity of the signature. The 2548 openssl invocation to verify a signature looks like this: 2550 openssl dgst -verify rsa.public -sha256 -signature signature.file \ 2551 . 2611 Appendix F. Edit History 2613 [[This section to be removed before publication.]] 2615 F.1 Changes since -ietf-02 version 2617 The following changes were made between draft-ietf-dkim-base-02 and 2618 draft-ietf-dkim-base-03: 2620 o Section 5.2: changed key expiration text to be informational; 2621 drop "seven day" wording in favor of something vaguer. 2623 o Don't indicate that the "i=" tag value should be passed to the key 2624 lookup service; this can be added as an extension if required. 2626 o Move Section 6.6 (MUA Considerations) to be Appendix D and modify 2627 it to avoid any hint of normative language. 2629 o Soften the DKIM_STAT_ language in section 6 so that it doesn't 2630 appear normative. This involved using only PERMFAIL and TEMPFAIL 2631 as status, with parenthetical explanations. 2633 o Restructured section 6 to make it clearer which steps apply on a 2634 per-signature basis versus a per-message basis. 2636 o Clarification of "signing identity" in several places. 2638 o Clarification that DKIM-Signature header fields being signed by 2639 another DKIM-Signature header field should be treated as a normal 2640 header field (i.e., their "b=" field is unchanged). 2642 o Change ABNF on a= tag to separate the public key algorithm from 2643 the hash algorithm. 2645 o Add t=s flag in key record to disallow subdomains in the i= tag 2646 relative to the d= tag of the DKIM-Signature header field. 2648 o Add a new definition for "dkim-quoted-printable", which is a 2649 simple case of quoted-printable from RFC2045. dkim-quoted- 2650 printable requires that all white space in the original text be 2651 escaped, and all unescaped white space in the encoded field should 2652 be ignored to allow arbitrary wrapping of the header fields which 2653 may contain the content. 2655 o Use dkim-quoted-printable as the encoding used in z= rather than 2656 referring to RFC2045, since they are different. 2658 o Rewrite description of g= tag in the key record. 2660 o Deleted use of Domain in ABNF, which permits address-literals; 2661 define domain-name to act in stead. 2663 F.2 Changes since -ietf-01 version 2665 The following changes were made between draft-ietf-dkim-base-01 and 2666 draft-ietf-dkim-base-02: 2668 o Change wording on "x=" tag in DKIM-Signature header field 2669 regarding verifier handling of expired signatures from MUST to MAY 2670 (per 20 April Jabber session). Also, make it clear that received 2671 time is to be preferred over current time if reliably available. 2673 o Several changes to limit wording that would intrude into verifier 2674 policy. This is largely changing statements such as "... MUST 2675 reject the message" to "... MUST consider the signature invalid." 2677 o Drop normative references to ID-DKIM-RR, OpenSSL, PEM, and 2678 Stringprep. 2680 o Change "v=" tag in DKIM-Signature from "MUST NOT" to "MUST"; the 2681 version number is 0.2 for this draft, with the expectation that 2682 the first official version will be "v=1". (Per 18 May Jabber 2683 session.) 2685 o Change "q=dns" query access method to "q=dnstxt" to emphasize the 2686 use of the TXT record. The expectation is that a later extension 2687 will define "q=dnsdkk" to indicate use of a DKK record. (Per 18 2688 May Jabber session.) 2690 o Several typos fixed, including removing a paragraph that implied 2691 that the DKIM-Signature header field should be hashed with the 2692 body (it should not). 2694 F.3 Changes since -ietf-00 version 2696 The following changes were made between draft-ietf-dkim-base-00 and 2697 draft-ietf-dkim-base-01: 2699 o Added section 8.9 (Information Leakage). 2701 o Replace section 4 (Multiple Signatures) with much less vague text. 2703 o Fixed ABNF for base64string. 2705 o Added rsa-sha256 signing algorithm. 2707 o Expanded several examples. 2709 o Changed signing algorithm to use separate hash of the body of the 2710 message; this is represented as the "bh=" tag in the DKIM- 2711 Signature header field. 2713 o Changed "z=" tag so that it need not have the same header field 2714 names as the "h=" tag. 2716 o Significant wordsmithing. 2718 F.4 Changes since -allman-01 version 2720 The following changes were made between draft-allman-dkim-base-01 and 2721 draft-ietf-dkim-base-00: 2723 o Remove references to Sender Signing Policy document. Such 2724 consideration is implicitly included in Section 6.3. 2726 o Added ABNF for all tags. 2728 o Updated references (still includes some references to expired 2729 drafts, notably [ID-AUTH-RES]. 2731 o Significant wordsmithing. 2733 F.5 Changes since -allman-00 version 2735 The following changes were made between draft-allman-dkim-base-00 and 2736 draft-allman-dkim-base-01: 2738 o Changed "c=" tag to separate out header from body 2739 canonicalization. 2741 o Eliminated "nowsp" canonicalization in favor of "relaxed", which 2742 is somewhat less relaxed (but more secure) than "nowsp". 2744 o Moved the (empty) Compliance section to the Sender Signing Policy 2745 document. 2747 o Added several IANA Considerations. 2749 o Fixed a number of grammar and formatting errors. 2751 Intellectual Property Statement 2753 The IETF takes no position regarding the validity or scope of any 2754 Intellectual Property Rights or other rights that might be claimed to 2755 pertain to the implementation or use of the technology described in 2756 this document or the extent to which any license under such rights 2757 might or might not be available; nor does it represent that it has 2758 made any independent effort to identify any such rights. Information 2759 on the procedures with respect to rights in RFC documents can be 2760 found in BCP 78 and BCP 79. 2762 Copies of IPR disclosures made to the IETF Secretariat and any 2763 assurances of licenses to be made available, or the result of an 2764 attempt made to obtain a general license or permission for the use of 2765 such proprietary rights by implementers or users of this 2766 specification can be obtained from the IETF on-line IPR repository at 2767 http://www.ietf.org/ipr. 2769 The IETF invites any interested party to bring to its attention any 2770 copyrights, patents or patent applications, or other proprietary 2771 rights that may cover technology that may be required to implement 2772 this standard. Please address the information to the IETF at 2773 ietf-ipr@ietf.org. 2775 The IETF has been notified of intellectual property rights claimed in 2776 regard to some or all of the specification contained in this 2777 document. For more information consult the online list of claimed 2778 rights. 2780 Disclaimer of Validity 2782 This document and the information contained herein are provided on an 2783 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2784 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2785 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2786 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2787 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2788 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2790 Copyright Statement 2792 Copyright (C) The Internet Society (2006). This document is subject 2793 to the rights, licenses and restrictions contained in BCP 78, and 2794 except as set forth therein, the authors retain all their rights. 2796 Acknowledgment 2798 Funding for the RFC Editor function is currently provided by the 2799 Internet Society.