idnits 2.17.1 draft-ietf-dkim-base-07.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 3281. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3253. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3260. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3266. ** 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1236 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 (December 4, 2006) is 6350 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 2913, 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 3490 (Obsoleted by RFC 5890, RFC 5891) ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA' -- 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 (~~), 4 warnings (==), 11 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: June 7, 2007 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 December 4, 2006 14 DomainKeys Identified Mail (DKIM) Signatures 15 draft-ietf-dkim-base-07 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 June 7, 2007. 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 54 protecting message signer identity and the integrity of the messages 55 they convey while retaining the functionality of Internet email as it 56 is known today. Protection of email identity may assist in the 57 global control of "spam" and "phishing". 59 Requirements Language 61 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 62 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 63 document are to be interpreted as described in [RFC2119]. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 68 1.1 Signing Identity . . . . . . . . . . . . . . . . . . . . . 6 69 1.2 Scalability . . . . . . . . . . . . . . . . . . . . . . . 6 70 1.3 Simple Key Management . . . . . . . . . . . . . . . . . . 6 71 2. Terminology and Definitions . . . . . . . . . . . . . . . . 6 72 2.1 Signers . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 2.2 Verifiers . . . . . . . . . . . . . . . . . . . . . . . . 7 74 2.3 White Space . . . . . . . . . . . . . . . . . . . . . . . 7 75 2.4 Common ABNF Tokens . . . . . . . . . . . . . . . . . . . . 7 76 2.5 Imported ABNF Tokens . . . . . . . . . . . . . . . . . . . 8 77 2.6 DKIM-Quoted-Printable . . . . . . . . . . . . . . . . . . 8 78 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . 9 79 3.1 Selectors . . . . . . . . . . . . . . . . . . . . . . . . 9 80 3.2 Tag=Value Lists . . . . . . . . . . . . . . . . . . . . . 11 81 3.3 Signing and Verification Algorithms . . . . . . . . . . . 12 82 3.4 Canonicalization . . . . . . . . . . . . . . . . . . . . . 14 83 3.5 The DKIM-Signature header field . . . . . . . . . . . . . 18 84 3.6 Key Management and Representation . . . . . . . . . . . . 25 85 3.7 Computing the Message Hashes . . . . . . . . . . . . . . . 30 86 3.8 Signing by Parent Domains . . . . . . . . . . . . . . . . 32 87 4. Semantics of Multiple Signatures . . . . . . . . . . . . . . 32 88 5. Signer Actions . . . . . . . . . . . . . . . . . . . . . . . 33 89 5.1 Determine if the Email Should be Signed and by Whom . . . 33 90 5.2 Select a private-key and corresponding selector 91 information . . . . . . . . . . . . . . . . . . . . . . . 33 92 5.3 Normalize the Message to Prevent Transport Conversions . . 34 93 5.4 Determine the header fields to Sign . . . . . . . . . . . 34 94 5.5 Compute the Message Hash and Signature . . . . . . . . . . 36 95 5.6 Insert the DKIM-Signature header field . . . . . . . . . . 37 96 6. Verifier Actions . . . . . . . . . . . . . . . . . . . . . . 37 97 6.1 Extract Signatures from the Message . . . . . . . . . . . 38 98 6.2 Communicate Verification Results . . . . . . . . . . . . . 43 99 6.3 Interpret Results/Apply Local Policy . . . . . . . . . . . 44 100 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 45 101 7.1 DKIM-Signature Tag Specifications . . . . . . . . . . . . 45 102 7.2 DKIM-Signature Query Method Registry . . . . . . . . . . . 46 103 7.3 DKIM-Signature Canonicalization Registry . . . . . . . . . 46 104 7.4 _domainkey DNS TXT Record Tag Specifications . . . . . . . 47 105 7.5 DKIM Key Type Registry . . . . . . . . . . . . . . . . . . 48 106 7.6 DKIM Hash Algorithms Registry . . . . . . . . . . . . . . 48 107 7.7 DKIM Service Types Registry . . . . . . . . . . . . . . . 48 108 7.8 DKIM Selector Flags Registry . . . . . . . . . . . . . . . 49 109 7.9 DKIM-Signature Header Field . . . . . . . . . . . . . . . 49 110 8. Security Considerations . . . . . . . . . . . . . . . . . . 49 111 8.1 Misuse of Body Length Limits ("l=" Tag) . . . . . . . . . 49 112 8.2 Misappropriated Private Key . . . . . . . . . . . . . . . 50 113 8.3 Key Server Denial-of-Service Attacks . . . . . . . . . . . 51 114 8.4 Attacks Against DNS . . . . . . . . . . . . . . . . . . . 51 115 8.5 Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 52 116 8.6 Limits on Revoking Keys . . . . . . . . . . . . . . . . . 53 117 8.7 Intentionally malformed Key Records . . . . . . . . . . . 53 118 8.8 Intentionally Malformed DKIM-Signature header fields . . . 53 119 8.9 Information Leakage . . . . . . . . . . . . . . . . . . . 53 120 8.10 Remote Timing Attacks . . . . . . . . . . . . . . . . . 53 121 8.11 Reordered Header Fields . . . . . . . . . . . . . . . . 54 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 123 9.1 Normative References . . . . . . . . . . . . . . . . . . . 54 124 9.2 Informative References . . . . . . . . . . . . . . . . . . 55 125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 55 126 A. Example of Use (INFORMATIVE) . . . . . . . . . . . . . . . . 57 127 A.1 The user composes an email . . . . . . . . . . . . . . . . 57 128 A.2 The email is signed . . . . . . . . . . . . . . . . . . . 57 129 A.3 The email signature is verified . . . . . . . . . . . . . 58 130 B. Usage Examples (INFORMATIVE) . . . . . . . . . . . . . . . . 59 131 B.1 Alternate Submission Scenarios . . . . . . . . . . . . . . 59 132 B.2 Alternate Delivery Scenarios . . . . . . . . . . . . . . . 62 133 C. Creating a public key (INFORMATIVE) . . . . . . . . . . . . 64 134 D. MUA Considerations . . . . . . . . . . . . . . . . . . . . . 65 135 E. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 66 136 F. Edit History . . . . . . . . . . . . . . . . . . . . . . . . 66 137 F.1 Changes since -ietf-06 version . . . . . . . . . . . . . . 67 138 F.2 Changes since -ietf-05 version . . . . . . . . . . . . . . 67 139 F.3 Changes since -ietf-04 version . . . . . . . . . . . . . . 68 140 F.4 Changes since -ietf-03 version . . . . . . . . . . . . . . 68 141 F.5 Changes since -ietf-02 version . . . . . . . . . . . . . . 69 142 F.6 Changes since -ietf-01 version . . . . . . . . . . . . . . 70 143 F.7 Changes since -ietf-00 version . . . . . . . . . . . . . . 71 144 F.8 Changes since -allman-01 version . . . . . . . . . . . . . 71 145 F.9 Changes since -allman-00 version . . . . . . . . . . . . . 72 146 Intellectual Property and Copyright Statements . . . . . . . 73 148 1. Introduction 150 [[Note: text in double square brackets (such as this text) will be 151 deleted before publication.]] 153 DomainKeys Identified Mail (DKIM) defines a mechanism by which email 154 messages can be cryptographically signed, permitting a signing domain 155 to claim responsibility for the introduction of a message into the 156 mail stream. Message recipients can verify the signature by querying 157 the signer's domain directly to retrieve the appropriate public key, 158 and thereby confirm that the message was attested to by a party in 159 possession of the private key for the signing domain. 161 The approach taken by DKIM differs from previous approaches to 162 message signing (e.g. S/MIME [RFC1847], OpenPGP [RFC2440]) in that: 164 o the message signature is written as a message header field so that 165 neither human recipients nor existing MUA (Mail User Agent) 166 software are confused by signature-related content appearing in 167 the message body; 169 o there is no dependency on public and private key pairs being 170 issued by well-known, trusted certificate authorities; 172 o there is no dependency on the deployment of any new Internet 173 protocols or services for public key distribution or revocation; 175 o signature verification failure does not force rejection of the 176 message; 178 o no attempt is made to include encryption as part of the mechanism; 180 o message archiving is not a design goal. 182 DKIM: 184 o is compatible with the existing email infrastructure and 185 transparent to the fullest extent possible; 187 o requires minimal new infrastructure; 189 o can be implemented independently of clients in order to reduce 190 deployment time; 192 o does not require the use of an additional trusted third party 193 (such as a certificate authority or other entity) which might 194 impose significant costs or introduce delays to deployment; 196 o can be deployed incrementally; 198 o allows delegation of signing to third parties. 200 1.1 Signing Identity 202 DKIM separates the question of the identity of the signer of the 203 message from the purported author of the message. In particular, a 204 signature includes the identity of the signer. Verifiers can use the 205 signing information to decide how they want to process the message. 206 The signing identity is included as part of the signature header 207 field. 209 INFORMATIVE RATIONALE: The signing identity specified by a DKIM 210 signature is not required to match an address in any particular 211 header field because of the broad methods of interpretation by 212 recipient mail systems, including MUAs. 214 1.2 Scalability 216 DKIM is designed to support the extreme scalability requirements 217 which characterize the email identification problem. There are 218 currently over 70 million domains and a much larger number of 219 individual addresses. DKIM seeks to preserve the positive aspects of 220 the current email infrastructure, such as the ability for anyone to 221 communicate with anyone else without introduction. 223 1.3 Simple Key Management 225 DKIM differs from traditional hierarchical public-key systems in that 226 no Certificate Authority infrastructure is required; the verifier 227 requests the public key from a repository in the domain of the 228 claimed signer directly rather than from a third party. 230 The DNS is proposed as the initial mechanism for the public keys. 231 Thus, DKIM currently depends on DNS adminstration and the security of 232 the DNS system. DKIM is designed to be extensible to other key 233 fetching services as they become available. 235 2. Terminology and Definitions 237 This section defines terms used in the rest of the document. Syntax 238 descriptions use the form described in Augmented BNF for Syntax 239 Specifications [RFC4234]. 241 2.1 Signers 243 Elements in the mail system that sign messages are referred to as 244 signers. These may be MUAs (Mail User Agents), MSAs (Mail Submission 245 Agents), MTAs (Mail Transfer Agents), or other agents such as mailing 246 list exploders. In general any signer will be involved in the 247 injection of a message into the message system in some way. The key 248 issue is that a message must be signed before it leaves the 249 administrative domain of the signer. 251 2.2 Verifiers 253 Elements in the mail system that verify signatures are referred to as 254 verifiers. These may be MTAs, Mail Delivery Agents (MDAs), or MUAs. 255 In most cases it is expected that verifiers will be close to an end 256 user (reader) of the message or some consuming agent such as a 257 mailing list exploder. 259 2.3 White Space 261 There are three forms of white space: 263 o WSP represents simple white space, i.e., a space or a tab 264 character (formal definition in [RFC4234]). 266 o LWSP is linear white space, defined as WSP plus CRLF (formal 267 definition in [RFC4234]). 269 o FWS is folding white space. It allows multiple lines separated by 270 CRLF followed by at least one white space, to be joined. 272 The formal ABNF for these are (WSP and LWSP are given for information 273 only): 275 WSP = SP / HTAB 276 LWSP = *(WSP / CRLF WSP) 277 FWS = [*WSP CRLF] 1*WSP 279 The definition of FWS is identical to that in [RFC2822] except for 280 the exclusion of obs-FWS. 282 2.4 Common ABNF Tokens 284 The following ABNF tokens are used elsewhere in this document. 286 hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] 287 base64string = 1*(ALPHA / DIGIT / "+" / "/" / LWSP) 288 [ "=" *LWSP [ "=" *LWSP ] ] 290 2.5 Imported ABNF Tokens 292 The following tokens are imported from other RFCs as noted. Those 293 RFCs should be considered definitive. 295 The following tokens are imported from [RFC2821]: 297 o "Local-part" (implementation warning: this permits quoted 298 strings) 300 o "sub-domain" 302 The following tokens are imported from [RFC2822]: 304 o "field-name" (name of a header field) 306 o "dot-atom-text" (in the local-part of an email address) 308 The following tokens are imported from [RFC2045]: 310 o "qp-section" (a single line of quoted-printable-encoded text) 312 o "hex-octet" (a quoted-printable encoded octet) 314 INFORMATIVE NOTE: Be aware that the ABNF in RFC 2045 does not 315 obey the rules of RFC 4234 and must be interpreted accordingly, 316 particularly as regards case folding. 318 Other tokens not defined herein are imported from [RFC4234]. These 319 are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF, 320 etc. 322 2.6 DKIM-Quoted-Printable 324 The DKIM-Quoted-Printable encoding syntax resembles that described in 325 Quoted-Printable [RFC2045] section 6.7: any character MAY be encoded 326 as an "=" followed by two hexadecimal digits from the alphabet 327 "0123456789ABCDEF" (no lower case characters permitted) representing 328 the hexadecimal-encoded integer value of that character. All control 329 characters (those with values < %x20), eight-bit characters (values > 330 %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon 331 (";", %x3B) MUST be encoded. Note that all white space, including 332 SPACE, CR and LF characters, MUST be encoded. After encoding, FWS 333 MAY be added at arbitrary locations in order to avoid excessively 334 long lines; such white space is NOT part of the value, and MUST be 335 removed before decoding. 337 ABNF: 338 dkim-quoted-printable = 339 *(FWS / hex-octet / dkim-safe-char) 340 ; hex-octet is from RFC 2045 341 dkim-safe-char = %x21-3A / %x3C / %x3E-7E 342 ; '!' - ':', '<', '>' - '~' 343 ; Characters not listed as "mail-safe" in 344 ; RFC 2049 are also not recommended. 346 INFORMATIVE NOTE: DKIM-Quoted-Printable differs from Quoted- 347 Printable as defined in RFC 2045 in several important ways: 349 1. White space in the input text, including CR and LF, must be 350 encoded. RFC 2045 does not require such encoding, and does 351 not permit encoding of CR or LF characters that are part of a 352 CRLF line break. 354 2. White space in the encoded text is ignored. This is to allow 355 tags encoded using DKIM-Quoted-Printable to be wrapped as 356 needed. In particular, RFC 2045 requires that line breaks in 357 the input be represented as physical line breaks; that is not 358 the case here. 360 3. The "soft line break" syntax ("=" as the last non-white-space 361 character on the line) does not apply. 363 4. DKIM-Quoted-Printable does not require that encoded lines be 364 no more than 76 characters long (although there may be other 365 requirements depending on the context in which the encoded 366 text is being used). 368 3. Protocol Elements 370 Protocol Elements are conceptual parts of the protocol that are not 371 specific to either signers or verifiers. The protocol descriptions 372 for signers and verifiers are described in later sections (Signer 373 Actions (Section 5) and Verifier Actions (Section 6)). NOTE: This 374 section must be read in the context of those sections. 376 3.1 Selectors 378 To support multiple concurrent public keys per signing domain, the 379 key namespace is subdivided using "Selectors". For example, 380 Selectors might indicate the names of office locations (e.g., 381 "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date 382 (e.g., "january2005", "february2005", etc.), or even the individual 383 user. 385 Selectors are needed to support some important use cases. For 386 example: 388 o Domains which want to delegate signing capability for a specific 389 address for a given duration to a partner, such as an advertising 390 provider or other out-sourced function. 392 o Domains which want to allow frequent travelers to send messages 393 locally without the need to connect with a particular MSA. 395 o "Affinity" domains (e.g., college alumni associations) which 396 provide forwarding of incoming mail but which do not operate a 397 mail submission agent for outgoing mail. 399 Periods are allowed in Selectors and are component separators. When 400 keys are retrieved from the DNS, periods in Selectors define DNS 401 label boundaries in a manner similar to the conventional use in 402 domain names. Selector components might be used to combine dates 403 with locations; for example, "march2005.reykjavik". In a DNS 404 implementation, this can be used to allow delegation of a portion of 405 the Selector name-space. 407 ABNF: 408 selector = sub-domain *( "." sub-domain ) 410 The number of public keys and corresponding Selectors for each domain 411 are determined by the domain owner. Many domain owners will be 412 satisfied with just one Selector whereas administratively distributed 413 organizations may choose to manage disparate Selectors and key pairs 414 in different regions or on different email servers. 416 Beyond administrative convenience, Selectors make it possible to 417 seamlessly replace public keys on a routine basis. If a domain 418 wishes to change from using a public key associated with Selector 419 "january2005" to a public key associated with Selector 420 "february2005", it merely makes sure that both public keys are 421 advertised in the public-key repository concurrently for the 422 transition period during which email may be in transit prior to 423 verification. At the start of the transition period, the outbound 424 email servers are configured to sign with the "february2005" private- 425 key. At the end of the transition period, the "january2005" public 426 key is removed from the public-key repository. 428 INFORMATIVE NOTE: A key may also be revoked as described below. 429 The distinction between revoking and removing a key selector 430 record is subtle. When phasing out keys as described above, a 431 signing domain would probably simply remove the key record after 432 the transition period. However, a signing domain could elect to 433 revoke the key (but maintain the key record) for a further period. 434 There is no defined semantic difference between a revoked key and 435 a removed key. 437 While some domains may wish to make Selector values well known, 438 others will want to take care not to allocate Selector names in a way 439 that allows harvesting of data by outside parties. For example, if 440 per-user keys are issued, the domain owner will need to make the 441 decision as to whether to associate this Selector directly with the 442 user name, or make it some unassociated random value, such as a 443 fingerprint of the public key. 445 Reusing a Selector with a new key (for example, changing the key 446 associated with a user's name) makes it impossible to tell the 447 difference between a message that didn't verify because the key is no 448 longer valid versus a message that is actually forged. Signers 449 SHOULD NOT change the key associated with a Selector. When creating 450 a new key, signers SHOULD associate it with a new Selector. 452 3.2 Tag=Value Lists 454 DKIM uses a simple "tag=value" syntax in several contexts, including 455 in messages and domain signature records. 457 Values are a series of strings containing either plain text, "base64" 458 text (as defined in [RFC2045], section 6.8), "qp-section" (ibid, 459 section 6.7), or "dkim-quoted-printable" (as defined in Section 2.6). 460 The name of the tag will determine the encoding of each value. 461 Unencoded semicolon (";") characters MUST NOT occur in the tag value, 462 since that separates tag-specs. 464 INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" 465 defined below (as "tag-value") only includes 7-bit characters, an 466 implementation that wished to anticipate future standards would be 467 advised to not preclude the use of UTF8-encoded text in tag=value 468 lists. 470 Formally, the syntax rules are: 471 tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] 472 tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] 473 tag-name = ALPHA 0*ALNUMPUNC 474 tag-value = [ tval 0*( 1*(WSP / FWS) tval ) ] 475 ; WSP and FWS prohibited at beginning and end 476 tval = 1*VALCHAR 477 VALCHAR = %x21-3A / %x3C-7E 478 ; EXCLAMATION to TILDE except SEMICOLON 479 ALNUMPUNC = ALPHA / DIGIT / "_" 481 Note that WSP is allowed anywhere around tags; in particular, any WSP 482 after the "=" and any WSP before the terminating ";" is not part of 483 the value; however, WSP inside the value is significant. 485 Tags MUST be interpreted in a case-sensitive manner. Values MUST be 486 processed as case sensitive unless the specific tag description of 487 semantics specifies case insensitivity. 489 Tags with duplicate names MUST NOT occur within a single tag-list; if 490 a tag name does occur more than once, the entire tag-list is invalid. 492 Whitespace within a value MUST be retained unless explicitly excluded 493 by the specific tag description. 495 Tag=value pairs that represent the default value MAY be included to 496 aid legibility. 498 Unrecognized tags MUST be ignored. 500 Tags that have an empty value are not the same as omitted tags. An 501 omitted tag is treated as having the default value; a tag with an 502 empty value explicitly designates the empty string as the value. For 503 example, "g=" does not mean "g=*", even though "g=*" is the default 504 for that tag. 506 3.3 Signing and Verification Algorithms 508 DKIM supports multiple digital signature algorithms. Two algorithms 509 are defined by this specification at this time: rsa-sha1, and rsa- 510 sha256. The rsa-sha256 algorithm is the default if no algorithm is 511 specified. Verifiers MUST implement both rsa-sha1 and rsa-sha256. 512 Signers MUST implement and SHOULD sign using rsa-sha256. 514 INFORMATIVE NOTE: Although sha256 is strongly encouraged, some 515 senders of low-security messages (such as routine newsletters) may 516 prefer to use sha1 because of reduced CPU requirements to compute 517 a sha1 hash. In general, sha256 should always be used whenever 518 possible. 520 3.3.1 The rsa-sha1 Signing Algorithm 522 The rsa-sha1 Signing Algorithm computes a message hash as described 523 in Section 3.7 below using SHA-1 [SHA] as the hash-alg. That hash is 524 then signed by the signer using the RSA algorithm (defined in PKCS#1 525 version 1.5 [RFC3447]) as the crypt-alg and the signer's private key. 526 The hash MUST NOT be truncated or converted into any form other than 527 the native binary form before being signed. 529 INFORMATIVE IMPLEMENTATION WARNING: Low-valued exponents should 530 be avoided, as they are believed to be subject to attack. 532 3.3.2 The rsa-sha256 Signing Algorithm 534 The rsa-sha256 Signing Algorithm computes a message hash as described 535 in Section 3.7 below using SHA-256 [SHA] as the hash-alg. That hash 536 is then signed by the signer using the RSA algorithm (defined in 537 PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the signer's 538 private key. The hash MUST NOT be truncated or converted into any 539 form other than the native binary form before being signed. 541 3.3.3 Key sizes 543 Selecting appropriate key sizes is a trade-off between cost, 544 performance and risk. Since short RSA keys more easily succumb to 545 off-line attacks, signers MUST use RSA keys of at least 1024 bits for 546 long-lived keys. Verifiers MUST be able to validate signatures with 547 keys ranging from 512 bits to 2048 bits, and they MAY be able to 548 validate signatures with larger keys. Verifier policies may use the 549 length of the signing key as one metric for determining whether a 550 signature is acceptable. 552 Factors that should influence the key size choice include: 554 o The practical constraint that large keys may not fit within a 512 555 byte DNS UDP response packet 557 o The security constraint that keys smaller than 1024 bits are 558 subject to off-line attacks 560 o Larger keys impose higher CPU costs to verify and sign email 562 o Keys can be replaced on a regular basis, thus their lifetime can 563 be relatively short 565 o The security goals of this specification are modest compared to 566 typical goals of other systems that employ digital signatures 568 See [RFC3766] for further discussion on selecting key sizes. 570 3.3.4 Other algorithms 572 Other algorithms MAY be defined in the future. Verifiers MUST ignore 573 any signatures using algorithms that they do not implement. 575 3.4 Canonicalization 577 Empirical evidence demonstrates that some mail servers and relay 578 systems modify email in transit, potentially invalidating a 579 signature. There are two competing perspectives on such 580 modifications. For most signers, mild modification of email is 581 immaterial to the authentication status of the email. For such 582 signers a canonicalization algorithm that survives modest in-transit 583 modification is preferred. 585 Other signers demand that any modification of the email, however 586 minor, result in a signature verification failure. These signers 587 prefer a canonicalization algorithm that does not tolerate in-transit 588 modification of the signed email. 590 Some signers may be willing to accept modifications to header fields 591 that are within the bounds of email standards such as [RFC2822], but 592 are unwilling to accept any modification to the body of messages. 594 To satisfy all requirements, two canonicalization algorithms are 595 defined for each of the header and the body: a "simple" algorithm 596 that tolerates almost no modification and a "relaxed" algorithm that 597 tolerates common modifications such as white-space replacement and 598 header field line re-wrapping. A signer MAY specify either algorithm 599 for header or body when signing an email. If no canonicalization 600 algorithm is specified by the signer, the "simple" algorithm defaults 601 for both header and body. Verifiers MUST implement both 602 canonicalization algorithms. Note that the header and body may use 603 different canonicalization algorithms. Further canonicalization 604 algorithms MAY be defined in the future; verifiers MUST ignore any 605 signatures that use unrecognized canonicalization algorithms. 607 Canonicalization simply prepares the email for presentation to the 608 signing or verification algorithm. It MUST NOT change the 609 transmitted data in any way. Canonicalization of header fields and 610 body are described below. 612 NOTE: This section assumes that the message is already in "network 613 normal" format (e.g., text is ASCII encoded, lines are separated with 614 CRLF characters, etc.). See also Section 5.3 for information about 615 normalizing the message. 617 3.4.1 The "simple" Header Canonicalization Algorithm 619 The "simple" header canonicalization algorithm does not change header 620 fields in any way. Header fields MUST be presented to the signing or 621 verification algorithm exactly as they are in the message being 622 signed or verified. In particular, header field names MUST NOT be 623 case folded and white space MUST NOT be changed. 625 3.4.2 The "relaxed" Header Canonicalization Algorithm 627 The "relaxed" header canonicalization algorithm MUST apply the 628 following steps in order: 630 o Convert all header field names (not the header field values) to 631 lower case. For example, convert "SUBJect: AbC" to "subject: 632 AbC". 634 o Unfold all header field continuation lines as described in 635 [RFC2822]; in particular, lines with terminators embedded in 636 continued header field values (that is, CRLF sequences followed by 637 WSP) MUST be interpreted without the CRLF. Implementations MUST 638 NOT remove the CRLF at the end of the header field value. 640 o Convert all sequences of one or more WSP characters to a single SP 641 character. WSP characters here include those before and after a 642 line folding boundary. 644 o Delete all WSP characters at the end of each unfolded header field 645 value. 647 o Delete any WSP characters remaining before and after the colon 648 separating the header field name from the header field value. The 649 colon separator MUST be retained. 651 3.4.3 The "simple" Body Canonicalization Algorithm 653 The "simple" body canonicalization algorithm ignores all empty lines 654 at the end of the message body. An empty line is a line of zero 655 length after removal of the line terminator. If there is no trailing 656 CRLF on the message, a CRLF is added. It makes no other changes to 657 the message body. In more formal terms, the "simple" body 658 canonicalization algorithm converts "0*CRLF" at the end of the body 659 to a single "CRLF". 661 3.4.4 The "relaxed" Body Canonicalization Algorithm 663 The "relaxed" body canonicalization algorithm: 665 o Ignores all white space at the end of lines. Implementations MUST 666 NOT remove the CRLF at the end of the line. 668 o Reduces all sequences of WSP within a line to a single SP 669 character. 671 o Ignores all empty lines at the end of the message body. "Empty 672 line" is defined in Section 3.4.3. 674 3.4.5 Body Length Limits 676 A body length count MAY be specified to limit the signature 677 calculation to an initial prefix of the body text, measured in 678 octets. If the body length count is not specified then the entire 679 message body is signed. 681 INFORMATIVE RATIONALE: This capability is provided because it is 682 very common for mailing lists to add trailers to messages (e.g., 683 instructions how to get off the list). Until those messages are 684 also signed, the body length count is a useful tool for the 685 verifier since it may as a matter of policy accept messages having 686 valid signatures with extraneous data. 688 INFORMATIVE IMPLEMENTATION NOTE: Using body length limits enables 689 an attack in which an attacker modifies a message to include 690 content that solely benefits the attacker. It is possible for the 691 appended content to completely replace the original content in the 692 end recipient's eyes and to defeat duplicate message detection 693 algorithms. To avoid this attack, signers should be wary of using 694 this tag, and verifiers might wish to ignore the tag or remove 695 text that appears after the specified content length, perhaps 696 based on other criteria. 698 The body length count allows the signer of a message to permit data 699 to be appended to the end of the body of a signed message. The body 700 length count MUST be calculated following the canonicalization 701 algorithm; for example, any white space ignored by a canonicalization 702 algorithm is not included as part of the body length count. Signers 703 of MIME messages that include a body length count SHOULD be sure that 704 the length extends to the closing MIME boundary string. 706 INFORMATIVE IMPLEMENTATION NOTE: A signer wishing to ensure that 707 the only acceptable modifications are to add to the MIME postlude 708 would use a body length count encompassing the entire final MIME 709 boundary string, including the final "--CRLF". A signer wishing 710 to allow additional MIME parts but not modification of existing 711 parts would use a body length count extending through the final 712 MIME boundary string, omitting the final "--CRLF". 714 A body length count of zero means that the body is completely 715 unsigned. 717 Signers wishing to ensure that no modification of any sort can occur 718 should specify the "simple" canonicalization algorithm for both 719 header and body and omit the body length count. 721 3.4.6 Canonicalization Examples (INFORMATIVE) 723 In the following examples, actual white space is used only for 724 clarity. The actual input and output text is designated using 725 bracketed descriptors: "" for a space character, "" for a 726 tab character, and "" for a carriage-return/line-feed sequence. 727 For example, "X Y" and "XY" represent the same three 728 characters. 730 Example 1: A message reading: 731 A: X 732 B : Y 733 Z 734 735 C 736 D E 737 738 740 when canonicalized using relaxed canonicalization for both header and 741 body results in a header reading: 742 a:X 743 b:Y Z 745 and a body reading: 746 C 747 D E 749 Example 2: The same message canonicalized using simple 750 canonicalization for both header and body results in a header 751 reading: 752 A: X 753 B : Y 754 Z 756 and a body reading: 757 C 758 D E 760 Example 3: When processed using relaxed header canonicalization and 761 simple body canonicalization, the canonicalized version has a header 762 of: 763 a:X 764 b:Y Z 766 and a body reading: 767 C 768 D E 770 3.5 The DKIM-Signature header field 772 The signature of the email is stored in the "DKIM-Signature:" header 773 field. This header field contains all of the signature and key- 774 fetching data. The DKIM-Signature value is a tag-list as described 775 in Section 3.2. 777 The "DKIM-Signature:" header field SHOULD be treated as though it 778 were a trace header field as defined in section 3.6 of [RFC2822], and 779 hence SHOULD NOT be reordered and SHOULD be prepended to the message. 781 The "DKIM-Signature:" header field being created or verified is 782 always included in the signature calculation, after the rest of the 783 header fields being signed; however, when calculating or verifying 784 the signature, the value of the b= tag (signature value) of that 785 DKIM-Signature header field MUST be treated as though it were an 786 empty string. Unknown tags in the "DKIM-Signature:" header field 787 MUST be included in the signature calculation but MUST be otherwise 788 ignored by verifiers. Other "DKIM-Signature:" header fields that are 789 included in the signature should be treated as normal header fields; 790 in particular, the b= tag is not treated specially. 792 The encodings for each field type are listed below. Tags described 793 as qp-section are encoded as described in section 6.7 of MIME Part 794 One [RFC2045], with the additional conversion of semicolon characters 795 to "=3B"; intuitively, this is one line of quoted-printable encoded 796 text. The dkim-quoted-printable syntax is defined in Section 2.6. 798 Tags on the DKIM-Signature header field along with their type and 799 requirement status are shown below. Unrecognized tags MUST be 800 ignored. 802 v= Version (MUST be included). This tag defines the version of this 803 specification that applies to the signature record. It MUST have 804 the value 0.5. 806 ABNF: 808 sig-v-tag = %x76 [FWS] "=" [FWS] "0.5" 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 canonicalized body part of the message as limited 843 by the "l=" tag (base64; REQUIRED). Whitespace is ignored in 844 this value and MUST be ignored when re-assembling the original 845 signature. In particular, the signing process can safely insert 846 FWS in this value in arbitrary places to conform to line-length 847 limits. See Section 3.7 for how the 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 is 872 the domain that will be queried for the public key. This domain 873 MUST be the same as or a parent domain of the "i=" tag (the 874 signing identity, as described below), or it MUST meet the 875 requirements for parent domain signing described in Section 3.8. 876 When presented with a signature that does not meet these 877 requirement, verifiers MUST consider the signature invalid. 879 Internationalized domain names MUST be encoded as described in 880 [RFC3490]. 882 ABNF: 884 sig-d-tag = %x64 [FWS] "=" [FWS] domain-name 885 domain-name = sub-domain 1*("." sub-domain) 886 ; from RFC 2821 Domain, but excluding address-literal 888 h= Signed header fields (plain-text, but see description; REQUIRED). 889 A colon-separated list of header field names that identify the 890 header fields presented to the signing algorithm. The field MUST 891 contain the complete list of header fields in the order presented 892 to the signing algorithm. The field MAY contain names of header 893 fields that do not exist when signed; nonexistent header fields 894 do not contribute to the signature computation (that is, they are 895 treated as the null input, including the header field name, the 896 separating colon, the header field value, and any CRLF 897 terminator). The field MUST NOT include the DKIM-Signature 898 header field that is being created or verified, but may include 899 others. Folding white space (FWS) MAY be included on either side 900 of the colon separator. Header field names MUST be compared 901 against actual header field names in a case insensitive manner. 902 This list MUST NOT be empty. See Section 5.4 for a discussion of 903 choosing header fields to sign. 905 ABNF: 907 sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name 908 0*( *FWS ":" *FWS hdr-name ) 909 hdr-name = field-name 911 INFORMATIVE EXPLANATION: By "signing" header fields that do 912 not actually exist, a signer can prevent insertion of those 913 header fields before verification. However, since a signer 914 cannot possibly know what header fields might be created in 915 the future, and that some MUAs might present header fields 916 that are embedded inside a message (e.g., as a message/rfc822 917 content type), the security of this solution is not total. 919 INFORMATIVE EXPLANATION: The exclusion of the header field 920 name and colon as well as the header field value for non- 921 existent header fields prevents an attacker from inserting an 922 actual header field with a null value. 924 i= Identity of the user or agent (e.g., a mailing list manager) on 925 behalf of which this message is signed (dkim-quoted-printable; 926 OPTIONAL, default is an empty local-part followed by an "@" 927 followed by the domain from the "d=" tag). The syntax is a 928 standard email address where the local-part MAY be omitted. The 929 domain part of the address MUST be the same as or a subdomain of 930 the value of the "d=" tag. 932 Internationalized domain names MUST be converted using the steps 933 listed in section 4 of [RFC3490] using the "ToASCII" function. 935 ABNF: 937 sig-i-tag = %x69 [FWS] "=" [FWS] [ Local-part ] "@" domain-name 939 INFORMATIVE NOTE: The local-part of the "i=" tag is optional 940 because in some cases a signer may not be able to establish a 941 verified individual identity. In such cases, the signer may 942 wish to assert that although it is willing to go as far as 943 signing for the domain, it is unable or unwilling to commit 944 to an individual user name within their domain. It can do so 945 by including the domain part but not the local-part of the 946 identity. 948 INFORMATIVE DISCUSSION: This document does not require the 949 value of the "i=" tag to match the identity in any message 950 header field fields. This is considered to be a verifier 951 policy issue. Constraints between the value of the "i=" tag 952 and other identities in other header fields seek to apply 953 basic authentication into the semantics of trust associated 954 with a role such as content author. Trust is a broad and 955 complex topic and trust mechanisms are subject to highly 956 creative attacks. The real-world efficacy of any but the 957 most basic bindings between the "i=" value and other 958 identities is not well established, nor is its vulnerability 959 to subversion by an attacker. Hence reliance on the use of 960 these options should be strictly limited. In particular it 961 is not at all clear to what extent a typical end-user 962 recipient can rely on any assurances that might be made by 963 successful use of the "i=" options. 965 l= Body length count (plain-text unsigned decimal integer; OPTIONAL, 966 default is entire body). This tag informs the verifier of the 967 number of octets in the body of the email after canonicalization 968 included in the cryptographic hash, starting from 0 immediately 969 following the CRLF preceding the body. This value MUST NOT be 970 larger than the actual number of octets in the canonicalized 971 message body. 973 INFORMATIVE IMPLEMENTATION WARNING: Use of the l= tag might 974 allow display of fraudulent content without appropriate 975 warning to end users. The l= tag is intended for increasing 976 signature robustness when sending to mailing lists that both 977 modify their content and do not sign their messages. 978 However, using the l= tag enables attacks in which an 979 intermediary with malicious intent modifies a message to 980 include content that solely benefits the attacker. It is 981 possible for the appended content to completely replace the 982 original content in the end recipient's eyes and to defeat 983 duplicate message detection algorithms. Examples are 984 described in Security Considerations (Section 8). To avoid 985 this attack, signers should be extremely wary of using this 986 tag, and verifiers might wish to ignore the tag or remove 987 text that appears after the specified content length. 989 INFORMATIVE NOTE: The value of the l= tag is constrained to 990 76 decimal digits, which will fit in a 256-bit binary integer 991 field. This constraint is not intended to predict the size 992 of future messages, but is intended to remind the implementer 993 to check the length of this and all other tags during 994 verification. Implementers may need to limit the actual 995 value expressed to a value smaller than 10^76, e.g., to allow 996 a message to fit within the available storage space. 998 ABNF: 1000 sig-l-tag = %x6c [FWS] "=" [FWS] 1*76DIGIT 1002 q= A colon-separated list of query methods used to retrieve the 1003 public key (plain-text; OPTIONAL, default is "dns/txt"). Each 1004 query method is of the form "type[/options]", where the syntax 1005 and semantics of the options depends on the type and specified 1006 options. If there are multiple query mechanisms listed, the 1007 choice of query mechanism MUST NOT change the interpretation of 1008 the signature. Implementations MUST use the recognized query 1009 mechanisms in the order presented. 1011 Currently the only valid value is "dns/txt" which defines the DNS 1012 TXT record lookup algorithm described elsewhere in this document. 1013 The only option defined for the "dns" query type is "txt", which 1014 MUST be included. Verifiers and signers MUST support "dns/txt". 1016 ABNF: 1018 sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 1019 *([FWS] ":" [FWS] sig-q-tag-method) 1020 sig-q-tag-method = "dns/txt" / x-sig-q-tag-type 1021 ["/" x-sig-q-tag-args] 1022 x-sig-q-tag-type = hyphenated-word ; for future extension 1023 x-sig-q-tag-args = qp-hdr-value 1024 s= The Selector subdividing the namespace for the "d=" (domain) tag 1025 (plain-text; REQUIRED). 1027 ABNF: 1029 sig-s-tag = %x73 [FWS] "=" [FWS] selector 1031 t= Signature Timestamp (plain-text unsigned decimal integer; 1032 RECOMMENDED, default is an unknown creation time). The time that 1033 this signature was created. The format is the number of seconds 1034 since 00:00:00 on January 1, 1970 in the UTC time zone. The 1035 value is expressed as an unsigned integer in decimal ASCII. This 1036 value is not constrained to fit into a 31- or 32-bit integer. 1037 Implementations SHOULD be prepared to handle values up to at 1038 least 10^12 (until approximately AD 200,000; this fits into 40 1039 bits). To avoid denial of service attacks, implementations MAY 1040 consider any value longer than 12 digits to be infinite. Leap 1041 seconds are not counted. 1043 ABNF: 1045 sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT 1047 x= Signature Expiration (plain-text unsigned decimal integer; 1048 RECOMMENDED, default is no expiration). The format is the same 1049 as in the "t=" tag, represented as an absolute date, not as a 1050 time delta from the signing timestamp. The value is expressed as 1051 an unsigned integer in decimal ASCII, with the same constraints 1052 on the value in the "t=" tag. Signatures MAY be considered 1053 invalid if the verification time at the verifier is past the 1054 expiration date. The verification time should be the time that 1055 the message was first received at the administrative domain of 1056 the verifier if that time is reliably available; otherwise the 1057 current time should be used. The value of the "x=" tag MUST be 1058 greater than the value of the "t=" tag if both are present. 1060 INFORMATIVE NOTE: The x= tag is not intended as an anti- 1061 replay defense. 1063 ABNF: 1065 sig-x-tag = %x78 [FWS] "=" [FWS] 1*12DIGIT 1066 z= Copied header fields (dkim-quoted-printable, but see description; 1067 OPTIONAL, default is null). A vertical-bar-separated list of 1068 selected header fields present when the message was signed, 1069 including both the field name and value. It is not required to 1070 include all header fields present at the time of signing. This 1071 field need not contain the same header fields listed in the "h=" 1072 tag. The header field text itself must encode the vertical bar 1073 ("|", %x7C) character (i.e., vertical bars in the z= text are 1074 metacharacters, and any actual vertical bar characters in a 1075 copied header field must be encoded). Note that all white space 1076 must be encoded, including white space between the colon and the 1077 header field value. After encoding, LWSP MAY be added at 1078 arbitrary locations in order to avoid excessively long lines; 1079 such white space is NOT part of the value of the header field, 1080 and MUST be removed before decoding. 1082 Verifiers MUST NOT use the header field names or copied values 1083 for checking the signature in any way. Copied header field 1084 values are for diagnostic use only. 1086 Header fields with characters requiring conversion (perhaps from 1087 legacy MTAs which are not [RFC2822] compliant) SHOULD be 1088 converted as described in MIME Part Three [RFC2047]. 1090 ABNF: 1091 sig-z-tag = %x7A [FWS] "=" [FWS] sig-z-tag-copy 1092 *( [FWS] "|" sig-z-tag-copy ) 1093 sig-z-tag-copy = hdr-name ":" qp-hdr-value 1094 qp-hdr-value = dkim-quoted-printable ; with "|" encoded 1096 INFORMATIVE EXAMPLE of a signature header field spread across 1097 multiple continuation lines: 1099 DKIM-Signature: a=rsa-sha256; d=example.net; s=brisbane; 1100 c=simple; q=dns/txt; i=@eng.example.net; 1101 t=1117574938; x=1118006938; 1102 h=from:to:subject:date; 1103 z=From:foo@eng.example.net|To:joe@example.com| 1104 Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700; 1105 bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=; 1106 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ 1107 VoG4ZHRNiYzR 1109 3.6 Key Management and Representation 1111 Signature applications require some level of assurance that the 1112 verification public key is associated with the claimed signer. Many 1113 applications achieve this by using public key certificates issued by 1114 a trusted third party. However, DKIM can achieve a sufficient level 1115 of security, with significantly enhanced scalability, by simply 1116 having the verifier query the purported signer's DNS entry (or some 1117 security-equivalent) in order to retrieve the public key. 1119 DKIM keys can potentially be stored in multiple types of key servers 1120 and in multiple formats. The storage and format of keys are 1121 irrelevant to the remainder of the DKIM algorithm. 1123 Parameters to the key lookup algorithm are the type of the lookup 1124 (the "q=" tag), the domain of the responsible signer (the "d=" tag of 1125 the DKIM-Signature header field), and the Selector (the "s=" tag). 1127 public_key = dkim_find_key(q_val, d_val, s_val) 1129 This document defines a single binding, using DNS TXT records to 1130 distribute the keys. Other bindings may be defined in the future. 1132 3.6.1 Textual Representation 1134 It is expected that many key servers will choose to present the keys 1135 in an otherwise unstructured text format (for example, an XML form 1136 would not be considered to be unstructured text for this purpose). 1137 The following definition MUST be used for any DKIM key represented in 1138 an otherwise unstructured textual form. 1140 The overall syntax is a tag-list as described in Section 3.2. The 1141 current valid tags are described below. Other tags MAY be present 1142 and MUST be ignored by any implementation that does not understand 1143 them. 1145 v= Version of the DKIM key record (plain-text; RECOMMENDED, default 1146 is "DKIM1"). If specified, this tag MUST be set to "DKIM1" 1147 (without the quotes). This tag MUST be the first tag in the 1148 record. Records beginning with a "v=" tag with any other value 1149 MUST be discarded. 1151 ABNF: 1153 key-v-tag = %x76 [FWS] "=" [FWS] "DKIM1" 1154 g= granularity of the key (plain-text; OPTIONAL, default is "*"). 1155 This value MUST match the Local-part of the "i=" tag of the DKIM- 1156 Signature header field (or its default value of the empty string 1157 if "i=" is not specified), with a "*" character matching a 1158 sequence of zero or more arbitrary characters ("wildcarding"). 1159 The intent of this tag is to constrain which signing address can 1160 legitimately use this Selector. An email with a signing address 1161 that does not match the value of this tag constitutes a failed 1162 verification. Wildcarding allows matching for addresses such as 1163 "user+*". An empty "g=" value never matches any addresses. 1165 ABNF: 1167 key-g-tag = %x67 [FWS] "=" [FWS] key-g-tag-lpart 1168 key-g-tag-lpart = [dot-atom-text] ["*"] [dot-atom-text] 1170 [[NON-NORMATIVE DISCUSSION POINT: "*" is legal in a "dot- 1171 atom-text". This should probably use a different character 1172 for wildcarding. Unfortunately, the options are non-mnemonic 1173 (e.g., "@", "(", ":"). Alternatively we could insist on 1174 escaping a "*" intended as a literal "*" in the address.]] 1176 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to 1177 allowing all algorithms). A colon-separated list of hash 1178 algorithms that might be used. Signers and Verifiers MUST 1179 support the "sha256" hash algorithm. Verifiers MUST also support 1180 the "sha1" hash algorithm. 1182 ABNF: 1184 key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg 1185 0*( [FWS] ":" [FWS] key-h-tag-alg ) 1186 key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg 1187 x-key-h-tag-alg = hyphenated-word ; for future extension 1189 k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and 1190 verifiers MUST support the "rsa" key type. The "rsa" key type 1191 indicates that an ASN.1 DER-encoded [X.660] RSAPublicKey 1192 [RFC3447] (see sections 3.1 and A.1.1) is being used in the p= 1193 tag. (Note: the p= tag further encodes the value using the 1194 base64 algorithm.) 1196 ABNF: 1198 key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type 1199 key-k-tag-type = "rsa" / x-key-k-tag-type 1200 x-key-k-tag-type = hyphenated-word ; for future extension 1202 n= Notes that might be of interest to a human (qp-section; OPTIONAL, 1203 default is empty). No interpretation is made by any program. 1204 This tag should be used sparingly in any key server mechanism 1205 that has space limitations (notably DNS). 1207 ABNF: 1209 key-n-tag = %x6e [FWS] "=" [FWS] qp-section 1211 p= Public-key data (base64; REQUIRED). An empty value means that 1212 this public key has been revoked. The syntax and semantics of 1213 this tag value before being encoded in base64 is defined by the 1214 k= tag. 1216 INFORMATIVE RATIONALE: If a private key has been compromised 1217 or otherwise disabled (e.g., an outsourcing contract has been 1218 terminated), a signer might want to explicitly state that it 1219 knows about the selector, but all messages using that 1220 selector should fail verification. Verifiers should ignore 1221 any DKIM-Signature header fields with a selector referencing 1222 a revoked key. 1224 ABNF: 1226 key-p-tag = %x70 [FWS] "=" [ [FWS] base64string ] 1228 s= Service Type (plain-text; OPTIONAL; default is "*"). A colon- 1229 separated list of service types to which this record applies. 1230 Verifiers for a given service type MUST ignore this record if the 1231 appropriate type is not listed. Currently defined service types 1232 are: 1234 * matches all service types 1236 email electronic mail (not necessarily limited to SMTP) 1238 This tag is intended to permit signers to constrain the use of 1239 delegated keys, e.g., where a company is willing to delegate the 1240 right to send mail in their name to an outsourcer, but not to 1241 send IM or make VoIP calls. (This of course presumes that these 1242 keys are used in other services in the future.) 1243 ABNF: 1245 key-s-tag = %x73 [FWS] "=" [FWS] key-s-tag-type 1246 0*( [FWS] ":" [FWS] key-s-tag-type 1247 key-s-tag-type = "email" / "*" / x-key-s-tag-type 1248 x-key-s-tag-type = hyphenated-word ; for future extension 1250 t= Flags, represented as a colon-separated list of names (plain- 1251 text; OPTIONAL, default is no flags set). The defined flags are: 1253 y This domain is testing DKIM. Verifiers MUST NOT treat 1254 messages from signers in testing mode differently from 1255 unsigned email, even should the signature fail to verify. 1256 Verifiers MAY wish to track testing mode results to assist 1257 the signer. 1259 s Any DKIM-Signature header fields using the "i=" tag MUST have 1260 the same domain value on the right hand side of the "@" in 1261 the "i=" tag and the value of the "d=" tag. That is, the 1262 "i=" domain MUST NOT be a subdomain of "d=". Use of this 1263 flag is RECOMMENDED unless subdomaining is required. 1265 ABNF: 1267 key-t-tag = %x74 [FWS] "=" [FWS] key-t-tag-flag 1268 0*( [FWS] ":" [FWS] key-t-tag-flag ) 1269 key-t-tag-flag = "y" / "s" / x-key-t-tag-flag 1270 x-key-t-tag-flag = hyphenated-word ; for future extension 1272 Unrecognized flags MUST be ignored. 1274 3.6.2 DNS binding 1276 A binding using DNS TXT records as a key service is hereby defined. 1277 All implementations MUST support this binding. 1279 3.6.2.1 Name Space 1281 All DKIM keys are stored in a subdomain named "_domainkey". Given a 1282 DKIM-Signature field with a "d=" tag of "example.com" and an "s=" tag 1283 of "foo.bar", the DNS query will be for 1284 "foo.bar._domainkey.example.com". 1286 INFORMATIVE OPERATIONAL NOTE: Wildcard DNS records (e.g., 1287 *.bar._domainkey.example.com) do not make sense in this context 1288 and should not be used. Note also that wildcards within domains 1289 (e.g., s._domainkey.*.example.com) are not supported by the DNS. 1291 3.6.2.2 Resource Record Types for Key Storage 1293 The DNS Resource Record type used is specified by an option to the 1294 query-type ("q=") tag. The only option defined in this base 1295 specification is "txt", indicating the use of a TXT Resource Record 1296 (RR). A later extension of this standard may define another RR type. 1298 Strings in a TXT RR MUST be concatenated together before use with no 1299 intervening white space. TXT RRs MUST be unique for a particular 1300 selector name; that is, if there are multiple records in an RRset, 1301 the results are undefined. 1303 TXT RRs are encoded as described in Section 3.6.1. 1305 3.7 Computing the Message Hashes 1307 Both signing and verifying message signatures starts with a step of 1308 computing two cryptographic hashes over the message. Signers will 1309 choose the parameters of the signature as described in Signer Actions 1310 (Section 5); verifiers will use the parameters specified in the 1311 "DKIM-Signature" header field being verified. In the following 1312 discussion, the names of the tags in the "DKIM-Signature" header 1313 field which either exists (when verifying) or will be created (when 1314 signing) are used. Note that canonicalization (Section 3.4) is only 1315 used to prepare the email for signing or verifying; it does not 1316 affect the transmitted email in any way. 1318 The signer or verifier MUST compute two hashes, one over the body of 1319 the message and one over the selected header fields of the message. 1320 Signers MUST compute them in the order shown. Verifiers MAY compute 1321 them in any order convenient to the verifier, provided that the 1322 result is semantically identical to the semantics that would be the 1323 case had they been computed in this order. 1325 In hash step 1, the signer or verifier MUST hash the message body, 1326 canonicalized using the body canonicalization algorithm specified in 1327 the "c=" tag and truncated to the length specified in the "l=" tag. 1328 That hash value is then converted to base64 form and inserted into 1329 the "bh=" tag of the DKIM-Signature: header field. 1331 In hash step 2, the signer or verifier MUST pass the following to the 1332 hash algorithm in the indicated order. 1334 1. The header fields specified by the "h=" tag, in the order 1335 specified in that tag, and canonicalized using the header 1336 canonicalization algorithm specified in the "c=" tag. Each 1337 header field MUST be terminated with a single CRLF. 1339 2. The "DKIM-Signature" header field that exists (verifying) or will 1340 be inserted (signing) in the message, with the value of the "b=" 1341 tag deleted (i.e., treated as the empty string), canonicalized 1342 using the header canonicalization algorithm specified in the "c=" 1343 tag, and without a trailing CRLF. 1345 All tags and their values in the DKIM-Signature header field are 1346 included in the cryptographic hash with the sole exception of the 1347 value portion of the "b=" (signature) tag, which MUST be treated as 1348 the null string. All tags MUST be included even if they might not be 1349 understood by the verifier. The header field MUST be presented to 1350 the hash algorithm after the body of the message rather than with the 1351 rest of the header fields and MUST be canonicalized as specified in 1352 the "c=" (canonicalization) tag. The DKIM-Signature header field 1353 MUST NOT be included in its own h= tag, although other DKIM-Signature 1354 header fields MAY be signed (see Section 4). 1356 When calculating the hash on messages that will be transmitted using 1357 base64 or quoted-printable encoding, signers MUST compute the hash 1358 after the encoding. Likewise, the verifier MUST incorporate the 1359 values into the hash before decoding the base64 or quoted-printable 1360 text. However, the hash MUST be computed before transport level 1361 encodings such as SMTP "dot-stuffing." 1363 With the exception of the canonicalization procedure described in 1364 Section 3.4, the DKIM signing process treats the body of messages as 1365 simply a string of octets. DKIM messages MAY be either in plain-text 1366 or in MIME format; no special treatment is afforded to MIME content. 1367 Message attachments in MIME format MUST be included in the content 1368 which is signed. 1370 More formally, the algorithm for the signature is: 1371 body-hash = hash-alg(canon_body) 1372 header-hash = hash-alg(canon_header || DKIM-SIG) 1373 signature = sig-alg(header-hash, key) 1375 where "sig-alg" is the signature algorithm specified by the "a=" tag, 1376 "hash-alg" is the hash algorithm specified by the "a=" tag, 1377 "canon_header" and "canon_body" are the canonicalized message header 1378 and body (respectively) as defined in Section 3.4 (excluding the 1379 DKIM-Signature header field), and "DKIM-SIG" is the canonicalized 1380 DKIM-Signature header field sans the signature value itself, but with 1381 "body-hash" included as the "bh=" tag. 1383 INFORMATIVE IMPLEMENTERS' NOTE: Many digital signature APIs 1384 provide both hashing and application of the RSA private key using 1385 a single "sign()" primitive. When using such an API the last two 1386 steps in the algorithm would probably be combined into a single 1387 call that would perform both the "hash-alg" and the "sig-alg". 1389 3.8 Signing by Parent Domains 1391 In some circumstances, it is desirable for a domain to apply a 1392 signature on behalf of any of its subdomains without the need to 1393 maintain separate selectors (key records) in each subdomain. By 1394 default, private keys corresponding to key records can be used to 1395 sign messages for any subdomain of the domain in which they reside, 1396 e.g., a key record for the domain example.com can be used to verify 1397 messages where the signing identity (i= tag of the signature) is 1398 sub.example.com, or even sub1.sub2.example.com. In order to limit 1399 the capability of such keys when this is not intended, the "s" flag 1400 may be set in the t= tag of the key record to constrain the validity 1401 of the record to exactly the domain of the signing identity. If the 1402 referenced key record contains the "s" flag as part of the t= tag, 1403 the domain of the signing identity (i= flag) MUST be the same as that 1404 of the d= domain. If this flag is absent, the domain of the signing 1405 identity MUST be the same as, or a subdomain of, the d= domain. Key 1406 records which are not intended for use with subdomains SHOULD specify 1407 the "s" flag in the t= tag. 1409 4. Semantics of Multiple Signatures 1411 A signer that is adding a signature to a message merely creates a new 1412 DKIM-Signature header, using the usual semantics of the h= option. A 1413 signer MAY sign previously existing DKIM-Signature header fields 1414 using the method described in section Section 5.4 to sign trace 1415 header fields. 1417 INFORMATIVE NOTE: Signers should be cognizant that signing DKIM- 1418 Signature header fields may result in signature failures with 1419 intermediaries that do not recognize that DKIM-Signature header 1420 fields are trace header fields and unwittingly reorder them, thus 1421 breaking such signatures. 1423 INFORMATIVE NOTE: If a header field with multiple instances is 1424 signed, those header fields are always signed from the bottom up. 1425 Thus, it is not possible to sign only specific DKIM-Signature 1426 header fields. For example, if the message being signed already 1427 contains three DKIM-Signature header fields A, B, and C, it is 1428 possible to sign all of them, B and C only, or C only, but not A 1429 only, B only, A and B only, or A and C only. 1431 When evaluating a message with multiple signatures, a verifier should 1432 evaluate signatures independently and on their own merits. For 1433 example, a verifier that by policy chooses not to accept signatures 1434 with deprecated cryptographic algorithms should consider such 1435 signatures invalid. As with messages with a single signature, 1436 verifiers are at liberty to use the presence of valid signatures as 1437 an input to local policy; likewise, the interpretation of multiple 1438 valid signatures in combination is a local policy decision of the 1439 verifier. 1441 Signers SHOULD NOT remove any DKIM-Signature header fields from 1442 messages they are signing, even if they know that the signatures 1443 cannot be verified. 1445 5. Signer Actions 1447 The following steps are performed in order by signers. 1449 5.1 Determine if the Email Should be Signed and by Whom 1451 A signer can obviously only sign email for domains for which it has a 1452 private-key and the necessary knowledge of the corresponding public 1453 key and Selector information. However there are a number of other 1454 reasons beyond the lack of a private key why a signer could choose 1455 not to sign an email. 1457 INFORMATIVE NOTE: Signing modules may be incorporated into any 1458 portion of the mail system as deemed appropriate, including an 1459 MUA, a SUBMISSION server, or an MTA. Wherever implemented, 1460 signers should beware of signing (and thereby asserting 1461 responsibility for) messages that may be problematic. In 1462 particular, within a trusted enclave the signing address might be 1463 derived from the header according to local policy; SUBMISSION 1464 servers might only sign messages from users that are properly 1465 authenticated and authorized. 1467 INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not 1468 sign Received header fields if the outgoing gateway MTA obfuscates 1469 Received header fields, for example to hide the details of 1470 internal topology. 1472 If an email cannot be signed for some reason, it is a local policy 1473 decision as to what to do with that email. 1475 5.2 Select a private-key and corresponding selector information 1477 This specification does not define the basis by which a signer should 1478 choose which private-key and Selector information to use. Currently, 1479 all Selectors are equal as far as this specification is concerned, so 1480 the decision should largely be a matter of administrative 1481 convenience. Distribution and management of private-keys is also 1482 outside the scope of this document. 1484 INFORMATIVE OPERATIONS ADVICE: A signer should not sign with a 1485 private key when the Selector containing the corresponding public 1486 key is expected to be revoked or removed before the verifier has 1487 an opportunity to validate the signature. The signer should 1488 anticipate that verifiers may choose to defer validation, perhaps 1489 until the message is actually read by the final recipient. In 1490 particular, when rotating to a new key pair, signing should 1491 immediately commence with the new private key and the old public 1492 key should be retained for a reasonable validation interval before 1493 being removed from the key server. 1495 5.3 Normalize the Message to Prevent Transport Conversions 1497 Some messages, particularly those using 8-bit characters, are subject 1498 to modification during transit, notably conversion to 7-bit form. 1499 Such conversions will break DKIM signatures. In order to minimize 1500 the chances of such breakage, signers SHOULD convert the message to a 1501 suitable MIME content transfer encoding such as quoted-printable or 1502 base64 as described in MIME Part One [RFC2045] before signing. Such 1503 conversion is outside the scope of DKIM; the actual message SHOULD be 1504 converted to 7-bit MIME by an MUA or MSA prior to presentation to the 1505 DKIM algorithm. 1507 If the message is submitted to the signer with any local encoding 1508 that will be modified before transmission, that modification to 1509 canonical [RFC2822] form MUST be done before signing. In particular, 1510 bare CR or LF characters (used by some systems as a local line 1511 separator convention) MUST be converted to the SMTP-standard CRLF 1512 sequence before the message is signed. Any conversion of this sort 1513 SHOULD be applied to the message actually sent to the recipient(s), 1514 not just to the version presented to the signing algorithm. 1516 More generally, the signer MUST sign the message as it is expected to 1517 be received by the verifier rather than in some local or internal 1518 form. 1520 5.4 Determine the header fields to Sign 1522 The From header field MUST be signed (that is, included in the h= tag 1523 of the resulting DKIM-Signature header field). Signers SHOULD NOT 1524 sign an existing header field likely to be legitimately modified or 1525 removed in transit. In particular, [RFC2821] explicitly permits 1526 modification or removal of the "Return-Path" header field in transit. 1527 Signers MAY include any other header fields present at the time of 1528 signing at the discretion of the signer. 1530 INFORMATIVE OPERATIONS NOTE: The choice of which header fields to 1531 sign is non-obvious. One strategy is to sign all existing, non- 1532 repeatable header fields. An alternative strategy is to sign only 1533 header fields that are likely to be displayed to or otherwise be 1534 likely to affect the processing of the message at the receiver. A 1535 third strategy is to sign only "well known" headers. Note that 1536 verifiers may treat unsigned header fields with extreme 1537 skepticism, including refusing to display them to the end user or 1538 even ignore the signature if it does not cover certain header 1539 fields. For this reason signing fields present in the message 1540 such as Date, Subject, Reply-To, Sender, and all MIME header 1541 fields is highly advised. 1543 The DKIM-Signature header field is always implicitly signed and MUST 1544 NOT be included in the h= tag except to indicate that other 1545 preexisting signatures are also signed. 1547 Signers MAY claim to have signed header fields that do not exist 1548 (that is, signers MAY include the header field name in the h= tag 1549 even if that header field does not exist in the message). When 1550 computing the signature, the non-existing header field MUST be 1551 treated as the null string (including the header field name, header 1552 field value, all punctuation, and the trailing CRLF). 1554 INFORMATIVE RATIONALE: This allows signers to explicitly assert 1555 the absence of a header field; if that header field is added later 1556 the signature will fail. 1558 INFORMATIVE NOTE: A header field name need only be listed once 1559 more than the actual number of that header field in a message at 1560 the time of signing in order to prevent any further additions. 1561 For example, if there is a single "Comments" header field at the 1562 time of signing, listing "Comments" twice in the h= tag is 1563 sufficient to prevent any number of Comments header fields from 1564 being appended; it is not necessary (but is legal) to list 1565 "Comments" three or more times in the h= tag. 1567 Signers choosing to sign an existing header field that occurs more 1568 than once in the message (such as Received) MUST sign the physically 1569 last instance of that header field in the header block. Signers 1570 wishing to sign multiple instances of such a header field MUST 1571 include the header field name multiple times in the h= tag of the 1572 DKIM-Signature header field, and MUST sign such header fields in 1573 order from the bottom of the header field block to the top. The 1574 signer MAY include more instances of a header field name in h= than 1575 there are actual corresponding header fields to indicate that 1576 additional header fields of that name SHOULD NOT be added. 1578 INFORMATIVE EXAMPLE: 1580 If the signer wishes to sign two existing Received header fields, 1581 and the existing header contains: 1583 Received: 1584 Received: 1585 Received: 1587 then the resulting DKIM-Signature header field should read: 1589 DKIM-Signature: ... h=Received : Received : ... 1591 and Received header fields and will be signed in that 1592 order. 1594 Signers should be careful of signing header fields that might have 1595 additional instances added later in the delivery process, since such 1596 header fields might be inserted after the signed instance or 1597 otherwise reordered. Trace header fields (such as Received and DKIM- 1598 Signature) and Resent-* blocks are the only fields prohibited by 1599 [RFC2822] from being reordered. 1601 INFORMATIVE ADMONITION: Despite the fact that [RFC2822] permits 1602 header fields to be reordered (with the exception of Received 1603 header fields), reordering of signed header fields with multiple 1604 instances by intermediate MTAs will cause DKIM signatures to be 1605 broken; such anti-social behavior should be avoided. 1607 INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this 1608 specification, all end-user visible header fields should be signed 1609 to avoid possible "indirect spamming." For example, if the 1610 "Subject" header field is not signed, a spammer can resend a 1611 previously signed mail, replacing the legitimate subject with a 1612 one-line spam. 1614 5.5 Compute the Message Hash and Signature 1616 The signer MUST compute the message hash as described in Section 3.7 1617 and then sign it using the selected public-key algorithm. This will 1618 result in a DKIM-Signature header field which will include the body 1619 hash and a signature of the header hash, where that header includes 1620 the DKIM-Signature header field itself. 1622 Entities such as mailing list managers that implement DKIM and which 1623 modify the message or a header field (for example, inserting 1624 unsubscribe information) before retransmitting the message SHOULD 1625 check any existing signature on input and MUST make such 1626 modifications before re-signing the message. 1628 The signer MAY elect to limit the number of bytes of the body that 1629 will be included in the hash and hence signed. The length actually 1630 hashed should be inserted in the "l=" tag of the "DKIM-Signature" 1631 header field. 1633 5.6 Insert the DKIM-Signature header field 1635 Finally, the signer MUST insert the "DKIM-Signature:" header field 1636 created in the previous step prior to transmitting the email. The 1637 "DKIM-Signature" header field MUST be the same as used to compute the 1638 hash as described above, except that the value of the "b=" tag MUST 1639 be the appropriately signed hash computed in the previous step, 1640 signed using the algorithm specified in the "a=" tag of the "DKIM- 1641 Signature" header field and using the private key corresponding to 1642 the Selector given in the "s=" tag of the "DKIM-Signature" header 1643 field, as chosen above in Section 5.2 1645 The "DKIM-Signature" MUST be inserted before any other DKIM-Signature 1646 fields in the header block. 1648 INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this 1649 is to insert the "DKIM-Signature" header field at the beginning of 1650 the header block. In particular, it may be placed before any 1651 existing Received header fields. This is consistent with treating 1652 "DKIM-Signature" as a trace header field. 1654 6. Verifier Actions 1656 Since a signer MAY remove or revoke a public key at any time, it is 1657 recommended that verification occur in a timely manner with the most 1658 timely place being during acceptance by the border MTA. 1660 A border or intermediate MTA MAY verify the message signature(s). An 1661 MTA who has performed verification MAY communicate the result of that 1662 verification by adding a verification header field to incoming 1663 messages. This considerably simplifies things for the user, who can 1664 now use an existing mail user agent. Most MUAs have the ability to 1665 filter messages based on message header fields or content; these 1666 filters would be used to implement whatever policy the user wishes 1667 with respect to unsigned mail. 1669 A verifying MTA MAY implement a policy with respect to unverifiable 1670 mail, regardless of whether or not it applies the verification header 1671 field to signed messages. 1673 Verifiers MUST produce a result that is semantically equivalent to 1674 applying the following steps in the order listed. In practice, 1675 several of these steps can be performed in parallel in order to 1676 improve performance. 1678 6.1 Extract Signatures from the Message 1680 The order in which verifiers try DKIM-Signature header fields is not 1681 defined; verifiers MAY try signatures in any order they would like. 1682 For example, one implementation might prefer to try the signatures in 1683 textual order, whereas another might want to prefer signatures by 1684 identities that match the contents of the "From" header field over 1685 other identities. Verifiers MUST NOT attribute ultimate meaning to 1686 the order of multiple DKIM-Signature header fields. In particular, 1687 there is reason to believe that some relays will reorder the header 1688 fields in potentially arbitrary ways. 1690 INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as 1691 a clue to signing order in the absence of any other information. 1692 However, other clues as to the semantics of multiple signatures 1693 (such as correlating the signing host with Received header fields) 1694 may also be considered. 1696 A verifier SHOULD NOT treat a message that has one or more bad 1697 signatures and no good signatures differently from a message with no 1698 signature at all; such treatment is a matter of local policy and is 1699 beyond the scope of this document. 1701 When a signature successfully verifies, a verifier will either stop 1702 processing or attempt to verify any other signatures, at the 1703 discretion of the implementation. A verifier MAY limit the number of 1704 signatures it tries to avoid denial-of-service attacks. 1706 INFORMATIVE NOTE: An attacker could send messages with large 1707 numbers of faulty signatures, each of which would require a DNS 1708 lookup and corresponding CPU time to verify the message. This 1709 could be an attack on the domain that receives the message, by 1710 slowing down the verifier by requiring it to do large number of 1711 DNS lookups and/or signature verifications. It could also be an 1712 attack against the domains listed in the signatures, essentially 1713 by enlisting innocent verifiers in launching an attack against the 1714 DNS servers of the actual victim. 1716 In the following description, text reading "return status 1717 (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL") 1718 means that the verifier MUST immediately cease processing that 1719 signature. The verifier SHOULD proceed to the next signature, if any 1720 is present, and completely ignore the bad signature. If the status 1721 is "PERMFAIL", the signature failed and should not be reconsidered. 1722 If the status is "TEMPFAIL", the signature could not be verified at 1723 this time but may be tried again later. A verifier MAY either defer 1724 the message for later processing, perhaps by queueing it locally or 1725 issuing a 451/4.7.5 SMTP reply, or try another signature; if no good 1726 signature is found and any of the signatures resulted in a TEMPFAIL 1727 status, the verifier MAY save the message for later processing. The 1728 "(explanation)" is not normative text; it is provided solely for 1729 clarification. 1731 Verifiers SHOULD ignore any DKIM-Signature header fields where the 1732 signature does not validate. Verifiers that are prepared to validate 1733 multiple signature header fields SHOULD proceed to the next signature 1734 header field, should it exist. However, verifiers MAY make note of 1735 the fact that an invalid signature was present for consideration at a 1736 later step. 1738 INFORMATIVE NOTE: The rationale of this requirement is to permit 1739 messages that have invalid signatures but also a valid signature 1740 to work. For example, a mailing list exploder might opt to leave 1741 the original submitter signature in place even though the exploder 1742 knows that it is modifying the message in some way that will break 1743 that signature, and the exploder inserts its own signature. In 1744 this case the message should succeed even in the presence of the 1745 known-broken signature. 1747 For each signature to be validated, the following steps should be 1748 performed in such a manner as to produce a result that is 1749 semantically equivalent to performing them in the indicated order. 1751 6.1.1 Validate the Signature Header Field 1753 Implementers MUST meticulously validate the format and values in the 1754 DKIM-Signature header field; any inconsistency or unexpected values 1755 MUST cause the header field to be completely ignored and the verifier 1756 to return PERMFAIL (signature syntax error). Being "liberal in what 1757 you accept" is definitely a bad strategy in this security context. 1758 Note however that this does not include the existence of unknown tags 1759 in a DKIM-Signature header field, which are explicitly permitted. 1761 Verifiers MUST ignore DKIM-Signature header fields with a "v=" tag 1762 that is inconsistent with this specification and return PERMFAIL 1763 (incompatible version). 1765 INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of 1766 course, choose to also verify signatures generated by older 1767 versions of this specification. 1769 If any tag listed as "required" in Section 3.5 is omitted from the 1770 DKIM-Signature header field, the verifier MUST ignore the DKIM- 1771 Signature header field and return PERMFAIL (signature missing 1772 required tag). 1774 INFORMATIONAL NOTE: The tags listed as required in Section 3.5 1775 are "v=", "a=", "b=", "bh=", "d=", "h=", and "s=". Should there 1776 be a conflict between this note and Section 3.5, Section 3.5 is 1777 normative. 1779 If the "DKIM-Signature" header field does not contain the "i=" tag, 1780 the verifier MUST behave as though the value of that tag were "@d", 1781 where "d" is the value from the "d=" tag. 1783 Verifiers MUST confirm that the domain specified in the "d=" tag is 1784 the same as or a parent domain of the domain part of the "i=" tag. 1785 If not, the DKIM-Signature header field MUST be ignored and the 1786 verifier should return PERMFAIL (domain mismatch). 1788 If the "h=" tag does not include the "From" header field the verifier 1789 MUST ignore the DKIM-Signature header field and return PERMFAIL (From 1790 field not signed). 1792 Verifiers MAY ignore the DKIM-Signature header field and return 1793 PERMFAIL (signature expired) if it contains an "x=" tag and the 1794 signature has expired. 1796 Verifiers MAY ignore the DKIM-Signature header field and return 1797 PERMFAIL (unacceptable signature header) for any other reason, for 1798 example, if the signature does not sign header fields that the 1799 verifier views to be essential. As a case in point, if MIME header 1800 fields are not signed, certain attacks may be possible that the 1801 verifier would prefer to avoid. 1803 6.1.2 Get the Public Key 1805 The public key for a signature is needed to complete the verification 1806 process. The process of retrieving the public key depends on the 1807 query type as defined by the "q=" tag in the "DKIM-Signature:" header 1808 field. Obviously, a public key need only be retrieved if the process 1809 of extracting the signature information is completely successful. 1810 Details of key management and representation are described in 1811 Section 3.6. The verifier MUST validate the key record and MUST 1812 ignore any public key records that are malformed. 1814 When validating a message, a verifier MUST perform the following 1815 steps in a manner that is semantically the same as performing them in 1816 the order indicated (in some cases the implementation may parallelize 1817 or reorder these steps, as long as the semantics remain unchanged): 1819 1. Retrieve the public key as described in (Section 3.6) using the 1820 algorithm in the "q=" tag, the domain from the "d=" tag, and the 1821 Selector from the "s=" tag. 1823 2. If the query for the public key fails to respond, the verifier 1824 MAY defer acceptance of this email and return TEMPFAIL (key 1825 unavailable). If verification is occurring during the incoming 1826 SMTP session, this MAY be achieved with a 451/4.7.5 SMTP reply 1827 code. Alternatively, the verifier MAY store the message in the 1828 local queue for later trial or ignore the signature. Note that 1829 storing a message in the local queue is subject to denial-of- 1830 service attacks. 1832 3. If the query for the public key fails because the corresponding 1833 key record does not exist, the verifier MUST immediately return 1834 PERMFAIL (no key for signature). 1836 4. If the query for the public key returns multiple key records, the 1837 verifier may choose one of the key records or may cycle through 1838 the key records performing the remainder of these steps on each 1839 record at the discretion of the implementer. The order of the 1840 key records is unspecified. If the verifier chooses to cycle 1841 through the key records, then the "return ..." wording in the 1842 remainder of this section means "try the next key record, if any; 1843 if none, return to try another signature in the usual way." 1845 5. If the result returned from the query does not adhere to the 1846 format defined in this specification, the verifier MUST ignore 1847 the key record and return PERMFAIL (key syntax error). Verifiers 1848 are urged to validate the syntax of key records carefully to 1849 avoid attempted attacks. In particular, the verifier MUST ignore 1850 keys with a version code ("v=" tag) that they do not implement. 1852 6. If the "g=" tag in the public key does not match the Local-part 1853 of the "i=" tag in the message signature header field, the 1854 verifier MUST ignore the key record and return PERMFAIL 1855 (inapplicable key). If the Local-part of the "i=" tag on the 1856 message signature is not present, the g= tag must be * (valid for 1857 all addresses in the domain) or the entire g= tag must be omitted 1858 (which defaults to "g=*"), otherwise the verifier MUST ignore the 1859 key record and return PERMFAIL (inapplicable key). Other than 1860 this test, verifiers SHOULD NOT treat a message signed with a key 1861 record having a g= tag any differently than one without; in 1862 particular, verifiers SHOULD NOT prefer messages that seem to 1863 have an individual signature by virtue of a g= tag versus a 1864 domain signature. 1866 7. If the "h=" tag exists in the public key record and the hash 1867 algorithm implied by the a= tag in the DKIM-Signature header 1868 field is not included in the contents of the "h=" tag, the 1869 verifier MUST ignore the key record and return PERMFAIL 1870 (inappropriate hash algorithm). 1872 8. If the public key data (the "p=" tag) is empty then this key has 1873 been revoked and the verifier MUST treat this as a failed 1874 signature check and return PERMFAIL (key revoked). There is no 1875 defined semantic difference between a key that has been revoked 1876 and a key record that has been removed. 1878 9. If the public key data is not suitable for use with the algorithm 1879 and key types defined by the "a=" and "k=" tags in the "DKIM- 1880 Signature" header field, the verifier MUST immediately return 1881 PERMFAIL (inappropriate key algorithm). 1883 6.1.3 Compute the Verification 1885 Given a signer and a public key, verifying a signature consists of 1886 actions semantically equivalent to the following steps. 1888 1. Based on the algorithm defined in the "c=" tag, the body length 1889 specified in the "l=" tag, and the header field names in the "h=" 1890 tag, prepare a canonicalized version of the message as is 1891 described in Section 3.7 (note that this version does not 1892 actually need to be instantiated). When matching header field 1893 names in the "h=" tag against the actual message header field, 1894 comparisons MUST be case-insensitive. 1896 2. Based on the algorithm indicated in the "a=" tag, compute the 1897 message hashes from the canonical copy as described in 1898 Section 3.7. 1900 3. Verify that the hash of the canonicalized message body computed 1901 in the previous step matches the hash value conveyed in the "bh=" 1902 tag. If the hash does not match, the verifier SHOULD ignore the 1903 signature and return PERMFAIL (body hash did not verify). 1905 4. Using the signature conveyed in the "b=" tag, verify the 1906 signature against the header hash using the mechanism appropriate 1907 for the public key algorithm described in the "a=" tag. If the 1908 signature does not validate, the verifier SHOULD ignore the 1909 signature and return PERMFAIL (signature did not verify). 1911 5. Otherwise, the signature has correctly verified. 1913 INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to 1914 initiate the public-key query in parallel with calculating the 1915 hash as the public key is not needed until the final decryption is 1916 calculated. Implementations may also verify the signature on the 1917 message header before validating that the message hash listed in 1918 the "bh=" tag in the DKIM-Signature header field matches that of 1919 the actual message body; however, if the body hash does not match, 1920 the entire signature must be considered to have failed. 1922 A body length specified in the "l=" tag of the signature limits the 1923 number of bytes of the body passed to the verification algorithm. 1924 All data beyond that limit is not validated by DKIM. Hence, 1925 verifiers might treat a message that contains bytes beyond the 1926 indicated body length with suspicion, such as by truncating the 1927 message at the indicated body length, declaring the signature invalid 1928 (e.g., by returning PERMFAIL (unsigned content)), or conveying the 1929 partial verification to the policy module. 1931 INFORMATIVE IMPLEMENTATION NOTE: Verifiers that truncate the body 1932 at the indicated body length might pass on a malformed MIME 1933 message if the signer used the "N-4" trick (omitting the final 1934 "--CRLF") described in the informative note in Section 3.4.5. 1935 Such verifiers may wish to check for this case and include a 1936 trailing "--CRLF" to avoid breaking the MIME structure. A simple 1937 way to achieve this might be to append "--CRLF" to any "multipart" 1938 message with a body length; if the MIME structure is already 1939 correctly formed, this will appear in the postlude and will not be 1940 displayed to the end user. 1942 6.2 Communicate Verification Results 1944 Verifiers wishing to communicate the results of verification to other 1945 parts of the mail system may do so in whatever manner they see fit. 1946 For example, implementations might choose to add an email header 1947 field to the message before passing it on. Any such header field 1948 SHOULD be inserted before any existing DKIM-Signature or preexisting 1949 authentication status header fields in the header field block. 1951 INFORMATIVE ADVICE to MUA filter writers: Patterns intended to 1952 search for results header fields to visibly mark authenticated 1953 mail for end users should verify that such header field was added 1954 by the appropriate verifying domain and that the verified identity 1955 matches the author identity that will be displayed by the MUA. In 1956 particular, MUA filters should not be influenced by bogus results 1957 header fields added by attackers. To circumvent this attack, 1958 verifiers may wish to delete existing results header fields after 1959 verification and before adding a new header field. 1961 6.3 Interpret Results/Apply Local Policy 1963 It is beyond the scope of this specification to describe what actions 1964 a verifier system should make, but an authenticated email presents an 1965 opportunity to a receiving system that unauthenticated email cannot. 1966 Specifically, an authenticated email creates a predictable identifier 1967 by which other decisions can reliably be managed, such as trust and 1968 reputation. Conversely, unauthenticated email lacks a reliable 1969 identifier that can be used to assign trust and reputation. It is 1970 reasonable to treat unauthenticated email as lacking any trust and 1971 having no positive reputation. 1973 In general verifiers SHOULD NOT reject messages solely on the basis 1974 of a lack of signature or an unverifiable signature. However, if the 1975 verifier does opt to reject such messages, and the verifier runs 1976 synchronously with the SMTP session and a signature is missing or 1977 does not verify, the MTA SHOULD reject the message with an error such 1978 as: 1980 550 5.7.1 Unsigned messages not accepted 1982 550 5.7.5 Message signature incorrect 1984 If it is not possible to fetch the public key, perhaps because the 1985 key server is not available, a temporary failure message MAY be 1986 generated, such as: 1988 451 4.7.5 Unable to verify signature - key server unavailable 1990 Temporary failures such as inability to access the key server or 1991 other external service are the only conditions that SHOULD use a 4xx 1992 SMTP reply code. In particular, cryptographic signature verification 1993 failures MUST NOT return 4xx SMTP replies. 1995 Once the signature has been verified, that information MUST be 1996 conveyed to higher level systems (such as explicit allow/white lists 1997 and reputation systems) and/or to the end user. If the message is 1998 signed on behalf of any address other than that in the From: header 1999 field, the mail system SHOULD take pains to ensure that the actual 2000 signing identity is clear to the reader. 2002 The verifier MAY treat unsigned header fields with extreme 2003 skepticism, including marking them as untrusted or even deleting them 2004 before display to the end user. 2006 While the symptoms of a failed verification are obvious -- the 2007 signature doesn't verify -- establishing the exact cause can be more 2008 difficult. If a Selector cannot be found, is that because the 2009 Selector has been removed or was the value changed somehow in 2010 transit? If the signature line is missing is that because it was 2011 never there, or was it removed by an over-zealous filter? For 2012 diagnostic purposes, the exact reason why the verification fails 2013 SHOULD be made available to the policy module and possibly recorded 2014 in the system logs. However in terms of presentation to the end 2015 user, the result SHOULD be presented as a simple binary result: 2016 either the email is verified or it is not. If the email cannot be 2017 verified, then it SHOULD be rendered the same as all unverified email 2018 regardless of whether it looks like it was signed or not. 2020 7. IANA Considerations 2022 DKIM introduces some new namespaces that require IANA registry. 2024 7.1 DKIM-Signature Tag Specifications 2026 A DKIM-Signature provides for a list of tag specifications. IANA is 2027 requested to establish the DKIM Signature Tag Specification Registry, 2028 for tag specifications that can be used in DKIM-Signature fields and 2029 that have been specified in any published RFC. 2031 The initial entries in the registry comprise: 2033 +------+-----------------+ 2034 | TYPE | REFERENCE | 2035 +------+-----------------+ 2036 | v | (this document) | 2037 | a | (this document) | 2038 | b | (this document) | 2039 | bh | (this document) | 2040 | c | (this document) | 2041 | d | (this document) | 2042 | h | (this document) | 2043 | i | (this document) | 2044 | l | (this document) | 2045 | q | (this document) | 2046 | s | (this document) | 2047 | t | (this document) | 2048 | x | (this document) | 2049 | z | (this document) | 2050 +------+-----------------+ 2052 7.2 DKIM-Signature Query Method Registry 2054 The "q=" tag-spec, as specified in Section 3.5 provides for a list of 2055 query methods. 2057 IANA is requested to establish the DKIM Query Method Registry, for 2058 mechanisms that can be used to retrieve the key that will permit 2059 validation processing of a message signed using DKIM and have been 2060 specified in any published RFC. 2062 The initial entry in the registry comprises: 2064 +------+--------+-----------------+ 2065 | TYPE | OPTION | REFERENCE | 2066 +------+--------+-----------------+ 2067 | dns | txt | (this document) | 2068 +------+--------+-----------------+ 2070 7.3 DKIM-Signature Canonicalization Registry 2072 The "c=" tag-spec, as specified in Section 3.5 provides for a 2073 specifier for canonicalization algorithms for the header and body of 2074 the message. 2076 IANA is requested to establish the DKIM Canonicalization Algorithm 2077 Registry, for algorithms for converting a message into a canonical 2078 form before signing or verifying using DKIM and have been specified 2079 in any published RFC. 2081 The initial entries in the header registry comprise: 2083 +---------+-----------------+ 2084 | TYPE | REFERENCE | 2085 +---------+-----------------+ 2086 | simple | (this document) | 2087 | relaxed | (this document) | 2088 +---------+-----------------+ 2090 The initial entries in the body registry comprise: 2092 +---------+-----------------+ 2093 | TYPE | REFERENCE | 2094 +---------+-----------------+ 2095 | simple | (this document) | 2096 | relaxed | (this document) | 2097 +---------+-----------------+ 2099 7.4 _domainkey DNS TXT Record Tag Specifications 2101 A _domainkey DNS TXT record provides for a list of tag 2102 specifications. IANA is requested to establish the DKIM _domainkey 2103 DNS TXT Tag Specification Registry, for tag specifications that can 2104 be used in DNS TXT Records and that have been specified in any 2105 published RFC. 2107 The initial entries in the registry comprise: 2109 +------+-----------------+ 2110 | TYPE | REFERENCE | 2111 +------+-----------------+ 2112 | v | (this document) | 2113 | g | (this document) | 2114 | h | (this document) | 2115 | k | (this document) | 2116 | n | (this document) | 2117 | p | (this document) | 2118 | s | (this document) | 2119 | t | (this document) | 2120 +------+-----------------+ 2122 7.5 DKIM Key Type Registry 2124 The "k=" (as specified in Section 3.6.1) and the "a=" 2125 (Section 3.5) tags provide for a list of mechanisms 2126 that can be used to decode a DKIM signature. 2128 IANA is requested to establish the DKIM Key Type Registry, for such 2129 mechanisms that have been specified in any published RFC. 2131 The initial entry in the registry comprises: 2133 +------+-----------+ 2134 | TYPE | REFERENCE | 2135 +------+-----------+ 2136 | rsa | [RFC3447] | 2137 +------+-----------+ 2139 7.6 DKIM Hash Algorithms Registry 2141 The "h=" list (specified in Section 3.6.1) and the "a=" 2142 (Section 3.5) provide for a list of mechanisms that can 2143 be used to produce a digest of message data. 2145 IANA is requested to establish the DKIM Hash Algorithms Registry, for 2146 such mechanisms that have been specified in any published RFC. 2148 The initial entries in the registry comprise: 2150 +--------+-----------+ 2151 | TYPE | REFERENCE | 2152 +--------+-----------+ 2153 | sha1 | [SHA] | 2154 | sha256 | [SHA] | 2155 +--------+-----------+ 2157 7.7 DKIM Service Types Registry 2159 The "s=" list (specified in Section 3.6.1) provides for a 2160 list of service types to which this selector may apply. 2162 IANA is requested to establish the DKIM Service Types Registry, for 2163 service types that have been specified in any published RFC. 2165 The initial entries in the registry comprise: 2167 +-------+-----------------+ 2168 | TYPE | REFERENCE | 2169 +-------+-----------------+ 2170 | email | (this document) | 2171 | * | (this document) | 2172 +-------+-----------------+ 2174 7.8 DKIM Selector Flags Registry 2176 The "t=" list (specified in Section 3.6.1) provides for a 2177 list of flags to modify interpretation of the selector. 2179 IANA is requested to establish the DKIM Selector Flags Registry, for 2180 additional flags that have been specified in any published RFC. 2182 The initial entries in the registry comprise: 2184 +------+-----------------+ 2185 | TYPE | REFERENCE | 2186 +------+-----------------+ 2187 | y | (this document) | 2188 | s | (this document) | 2189 +------+-----------------+ 2191 7.9 DKIM-Signature Header Field 2193 IANA is requested to add DKIM-Signature to the "Permanent Header 2194 Messages" registry for the "mail" protocol, using this document as 2195 the Reference. 2197 8. Security Considerations 2199 It has been observed that any mechanism that is introduced which 2200 attempts to stem the flow of spam is subject to intensive attack. 2201 DKIM needs to be carefully scrutinized to identify potential attack 2202 vectors and the vulnerability to each. See also [RFC4686]. 2204 8.1 Misuse of Body Length Limits ("l=" Tag) 2206 Body length limits (in the form of the "l=" tag) are subject to 2207 several potential attacks. 2209 8.1.1 Addition of new MIME parts to multipart/* 2211 If the body length limit does not cover a closing MIME multipart 2212 section (including the trailing ""--CRLF"" portion), then it is 2213 possible for an attacker to intercept a properly signed multipart 2214 message and add a new body part. Depending on the details of the 2215 MIME type and the implementation of the verifying MTA and the 2216 receiving MUA, this could allow an attacker to change the information 2217 displayed to an end user from an apparently trusted source. 2219 For example, if an attacker can append information to a "text/html" 2220 body part, they may be able to exploit a bug in some MUAs that 2221 continue to read after a "" marker, and thus display HTML text 2222 on top of already displayed text. If a message has a "multipart/ 2223 alternative" body part, they might be able to add a new body part 2224 that is preferred by the displaying MTA. 2226 8.1.2 Addition of new HTML content to existing content 2228 Several receiving MUA implementations do not cease display after a 2229 """" tag. In particular, this allows attacks involving 2230 overlaying images on top of existing text. 2232 INFORMATIVE EXAMPLE: Appending the following text to an existing, 2233 properly closed message will in many MUAs result in inappropriate 2234 data being rendered on top of existing, correct data: 2235
2236 2238
2240 8.2 Misappropriated Private Key 2242 If the private key for a user is resident on their computer and is 2243 not protected by an appropriately secure mechanism, it is possible 2244 for malware to send mail as that user and any other user sharing the 2245 same private key. The malware would, however, not be able to 2246 generate signed spoofs of other signers' addresses, which would aid 2247 in identification of the infected user and would limit the 2248 possibilities for certain types of attacks involving socially- 2249 engineered messages. This threat applies mainly to MUA-based 2250 implementations; protection of private keys on servers can be easily 2251 achieved through the use of specialized cryptographic hardware. 2253 A larger problem occurs if malware on many users' computers obtains 2254 the private keys for those users and transmits them via a covert 2255 channel to a site where they can be shared. The compromised users 2256 would likely not know of the misappropriation until they receive 2257 "bounce" messages from messages they are purported to have sent. 2258 Many users might not understand the significance of these bounce 2259 messages and would not take action. 2261 One countermeasure is to use a user-entered passphrase to encrypt the 2262 private key, although users tend to choose weak passphrases and often 2263 reuse them for different purposes, possibly allowing an attack 2264 against DKIM to be extended into other domains. Nevertheless, the 2265 decoded private key might be briefly available to compromise by 2266 malware when it is entered, or might be discovered via keystroke 2267 logging. The added complexity of entering a passphrase each time one 2268 sends a message would also tend to discourage the use of a secure 2269 passphrase. 2271 A somewhat more effective countermeasure is to send messages through 2272 an outgoing MTA that can authenticate the submitter using existing 2273 techniques (e.g., SMTP Authentication), possibly validate the message 2274 itself (e.g., verify that the header is legitimate and that the 2275 content passes a spam content check), and sign the message using a 2276 key appropriate for the submitter address. Such an MTA can also 2277 apply controls on the volume of outgoing mail each user is permitted 2278 to originate in order to further limit the ability of malware to 2279 generate bulk email. 2281 8.3 Key Server Denial-of-Service Attacks 2283 Since the key servers are distributed (potentially separate for each 2284 domain), the number of servers that would need to be attacked to 2285 defeat this mechanism on an Internet-wide basis is very large. 2286 Nevertheless, key servers for individual domains could be attacked, 2287 impeding the verification of messages from that domain. This is not 2288 significantly different from the ability of an attacker to deny 2289 service to the mail exchangers for a given domain, although it 2290 affects outgoing, not incoming, mail. 2292 A variation on this attack is that if a very large amount of mail 2293 were to be sent using spoofed addresses from a given domain, the key 2294 servers for that domain could be overwhelmed with requests. However, 2295 given the low overhead of verification compared with handling of the 2296 email message itself, such an attack would be difficult to mount. 2298 8.4 Attacks Against DNS 2300 Since DNS is a required binding for key services, specific attacks 2301 against DNS must be considered. 2303 While the DNS is currently insecure [RFC3833], it is expected that 2304 the security problems should and will be solved by DNSSEC [RFC4033], 2305 and all users of the DNS will reap the benefit of that work. 2307 Secondly, the types of DNS attacks relevant to DKIM are very costly 2308 and are far less rewarding than DNS attacks on other Internet 2309 protocols. For example, attacking A records (to force users to a 2310 phishing site) is likely to be a more lucrative reason to poison DNS 2311 caches. None the less, the security of DKIM is strongly tied to the 2312 security of DNS. 2314 To systematically thwart the intent of DKIM, an attacker must conduct 2315 a very costly and very extensive attack on many parts of the DNS over 2316 an extended period. No one knows for sure how attackers will 2317 respond, however the cost/benefit of conducting prolonged DNS attacks 2318 of this nature is expected to be uneconomical. 2320 Finally, DKIM is only intended as a "sufficient" method of proving 2321 authenticity. It is not intended to provide strong cryptographic 2322 proof about authorship or contents. Other technologies such as 2323 OpenPGP [RFC2440] and S/MIME [RFC3851] address those requirements. 2325 A second security issue related to the DNS revolves around the 2326 increased DNS traffic as a consequence of fetching Selector-based 2327 data as well as fetching signing domain policy. Widespread 2328 deployment of DKIM will result in a significant increase in DNS 2329 queries to the claimed signing domain. In the case of forgeries on a 2330 large scale, DNS servers could see a substantial increase in queries. 2332 8.5 Replay Attacks 2334 In this attack, a spammer sends a message to be spammed to an 2335 accomplice, which results in the message being signed by the 2336 originating MTA. The accomplice resends the message, including the 2337 original signature, to a large number of recipients, possibly by 2338 sending the message to many compromised machines that act as MTAs. 2339 The messages, not having been modified by the accomplice, have valid 2340 signatures. 2342 Partial solutions to this problem involve the use of reputation 2343 services to convey the fact that the specific email address is being 2344 used for spam, and that messages from that signer are likely to be 2345 spam. This requires a real-time detection mechanism in order to 2346 react quickly enough. However, such measures might be prone to 2347 abuse, if for example an attacker resent a large number of messages 2348 received from a victim in order to make them appear to be a spammer. 2350 Large verifiers might be able to detect unusually large volumes of 2351 mails with the same signature in a short time period. Smaller 2352 verifiers can get substantially the same volume information via 2353 existing collaborative systems. 2355 8.6 Limits on Revoking Keys 2357 When a large domain detects undesirable behavior on the part of one 2358 of its users, it might wish to revoke the key used to sign that 2359 user's messages in order to disavow responsibility for messages which 2360 have not yet been verified or which are the subject of a replay 2361 attack. However, the ability of the domain to do so can be limited 2362 if the same key, for scalability reasons, is used to sign messages 2363 for many other users. Mechanisms for explicitly revoking keys on a 2364 per-address basis have been proposed but require further study as to 2365 their utility and the DNS load they represent. 2367 8.7 Intentionally malformed Key Records 2369 It is possible for an attacker to publish key records in DNS which 2370 are intentionally malformed, with the intent of causing a denial-of- 2371 service attack on a non-robust verifier implementation. The attacker 2372 could then cause a verifier to read the malformed key record by 2373 sending a message to one of its users referencing the malformed 2374 record in a (not necessarily valid) signature. Verifiers MUST 2375 thoroughly verify all key records retrieved from DNS and be robust 2376 against intentionally as well as unintentionally malformed key 2377 records. 2379 8.8 Intentionally Malformed DKIM-Signature header fields 2381 Verifiers MUST be prepared to receive messages with malformed DKIM- 2382 Signature header fields, and thoroughly verify the header field 2383 before depending on any of its contents. 2385 8.9 Information Leakage 2387 An attacker could determine when a particular signature was verified 2388 by using a per-message Selector and then monitoring their DNS traffic 2389 for the key lookup. This would act as the equivalent of a "web bug" 2390 for verification time rather than when the message was read. 2392 8.10 Remote Timing Attacks 2394 In some cases it may be possible to extract private keys using a 2395 remote timing attack [BONEH03]. Implementations should consider 2396 obfuscating the timing to prevent such attacks. 2398 8.11 Reordered Header Fields 2400 Existing standards allow intermediate MTAs to reorder header fields. 2401 If a signer signs two or more header fields of the same name, this 2402 can cause spurious verification errors on otherwise legitimate 2403 messages. 2405 9. References 2407 9.1 Normative References 2409 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2410 Extensions (MIME) Part One: Format of Internet Message 2411 Bodies", RFC 2045, November 1996. 2413 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 2414 Part Three: Message header field Extensions for Non-ASCII 2415 Text", RFC 2047, November 1996. 2417 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2418 Requirement Levels", BCP 14, RFC 2119, March 1997. 2420 [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, 2421 April 2001. 2423 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 2424 April 2001. 2426 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2427 Standards (PKCS) #1: RSA Cryptography Specifications 2428 Version 2.1", RFC 3447, February 2003. 2430 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, 2431 "Internationalizing Domain Names in Applications (IDNA)", 2432 March 2003. 2434 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2435 Specifications: ABNF", RFC 4234, October 2005. 2437 [SHA] U.S. Department of Commerce, "Secure Hash Standard", FIPS 2438 PUB 180-2, August 2002. 2440 [X.660] "ITU-T Recommendation X.660 Information Technology - ASN.1 2441 encoding rules: Specification of Basic Encoding Rules 2442 (BER), Canonical Encoding Rules (CER) and Distinguished 2443 Encoding Rules (DER)", 1997. 2445 9.2 Informative References 2447 [BONEH03] Proc. 12th USENIX Security Symposium, "Remote Timing 2448 Attacks are Practical", 2003, . 2451 [RFC-DK] "DomainKeys specification (to be published with this 2452 RFC)", 2005. 2454 [RFC1847] Galvin, J., Murphy, S., Crocker, S., and N. Freed, 2455 "Security Multiparts for MIME: Multipart/Signed and 2456 Multipart/Encrypted", RFC 1847, October 1995. 2458 [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, 2459 "OpenPGP Message Format", RFC 2440, November 1998. 2461 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths for 2462 Public Keys Used For Exchanging Symmetric Keys", RFC 3766, 2463 April 2004. 2465 [RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain 2466 Name System (DNS)", RFC 3833, August 2004. 2468 [RFC3851] Ramsdell, B., "S/MIME Version 3 Message Specification", 2469 RFC 3851, June 1999. 2471 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2472 Rose, "DNS Security Introduction and Requirements", 2473 RFC 4033, March 2005. 2475 [RFC4686] Fenton, J., "Analysis of Threats Motivating DomainKeys 2476 Identified Mail (DKIM)", RFC 4686, September 2006. 2478 Authors' Addresses 2480 Eric Allman 2481 Sendmail, Inc. 2482 6425 Christie Ave, Suite 400 2483 Emeryville, CA 94608 2484 USA 2486 Phone: +1 510 594 5501 2487 Email: eric+dkim@sendmail.org 2488 URI: 2490 Jon Callas 2491 PGP Corporation 2492 3460 West Bayshore 2493 Palo Alto, CA 94303 2494 USA 2496 Phone: +1 650 319 9016 2497 Email: jon@pgp.com 2499 Mark Delany 2500 Yahoo! Inc 2501 701 First Avenue 2502 Sunnyvale, CA 95087 2503 USA 2505 Phone: +1 408 349 6831 2506 Email: markd+dkim@yahoo-inc.com 2507 URI: 2509 Miles Libbey 2510 Yahoo! Inc 2511 701 First Avenue 2512 Sunnyvale, CA 95087 2513 USA 2515 Email: mlibbeymail-mailsig@yahoo.com 2516 URI: 2518 Jim Fenton 2519 Cisco Systems, Inc. 2520 MS SJ-24/2 2521 170 W. Tasman Drive 2522 San Jose, CA 95134-1706 2523 USA 2525 Phone: +1 408 526 5914 2526 Email: fenton@cisco.com 2527 URI: 2529 Michael Thomas 2530 Cisco Systems, Inc. 2531 MS SJ-9/2 2532 170 W. Tasman Drive 2533 San Jose, CA 95134-1706 2535 Phone: +1 408 525 5386 2536 Email: mat@cisco.com 2538 Appendix A. Example of Use (INFORMATIVE) 2540 This section shows the complete flow of an email from submission to 2541 final delivery, demonstrating how the various components fit 2542 together. 2544 A.1 The user composes an email 2546 From: Joe SixPack 2547 To: Suzie Q 2548 Subject: Is dinner ready? 2549 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2550 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2552 Hi. 2554 We lost the game. Are you hungry yet? 2556 Joe. 2558 A.2 The email is signed 2560 This email is signed by the example.com outbound email server and now 2561 looks like this: 2563 DKIM-Signature: a=rsa-sha256; s=brisbane; d=example.com; 2564 c=simple; q=dns/txt; i=joe@football.example.com; 2565 h=Received : From : To : Subject : Date : Message-ID; 2566 bh=jpltwNFTq83Bkjt/Y2ekyqr/+i296daNkFZSdaz8VCY=; 2567 b=bnUoMBPJ5wBigyZG2V4OG2JxLWJATkSkb9Ig+8OAu3cE2x/er+B 2568 7Tp1a1kEwZKdOtlTHlvF4JKg6RZUbN5urRJoaiD4RiSbf8D6fmMHt 2569 zEn8/OHpTCcdLOJaTp8/mKz69/RpatVBas2OqWas7jrlaLGfHdBkt 2570 Hs6fxOzzAB7Wro=; 2571 Received: from dsl-10.2.3.4.football.example.com [10.2.3.4] 2572 by submitserver.example.com with SUBMISSION; 2573 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2574 From: Joe SixPack 2575 To: Suzie Q 2576 Subject: Is dinner ready? 2577 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2578 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2580 Hi. 2582 We lost the game. Are you hungry yet? 2584 Joe. 2586 The signing email server requires access to the private-key 2587 associated with the "brisbane" Selector to generate this signature. 2589 A.3 The email signature is verified 2591 The signature is normally verified by an inbound SMTP server or 2592 possibly the final delivery agent. However, intervening MTAs can 2593 also perform this verification if they choose to do so. The 2594 verification process uses the domain "example.com" extracted from the 2595 "d=" tag and the Selector "brisbane" from the "s=" tag in the "DKIM- 2596 Signature" header field to form the DNS DKIM query for: 2598 brisbane._domainkey.example.com 2600 Signature verification starts with the physically last "Received" 2601 header field, the "From" header field, and so forth, in the order 2602 listed in the "h=" tag. Verification follows with a single CRLF 2603 followed by the body (starting with "Hi."). The email is canonically 2604 prepared for verifying with the "simple" method. The result of the 2605 query and subsequent verification of the signature is stored (in this 2606 example) in the "X-Authentication-Results" header field line. After 2607 successful verification, the email looks like this: 2609 X-Authentication-Results: shopping.example.net 2610 header.from=joe@football.example.com; dkim=pass 2611 Received: from mout23.football.example.com (192.168.1.1) 2612 by shopping.example.net with SMTP; 2613 Fri, 11 Jul 2003 21:01:59 -0700 (PDT) 2614 DKIM-Signature: a=rsa-sha256; s=brisbane; d=example.com; 2615 c=simple; q=dns/txt; i=joe@football.example.com; 2616 h=Received : From : To : Subject : Date : Message-ID; 2617 bh=jpltwNFTq83Bkjt/Y2ekyqr/+i296daNkFZSdaz8VCY=; 2618 b=bnUoMBPJ5wBigyZG2V4OG2JxLWJATkSkb9Ig+8OAu3cE2x/er+B 2619 7Tp1a1kEwZKdOtlTHlvF4JKg6RZUbN5urRJoaiD4RiSbf8D6fmMHt 2620 zEn8/OHpTCcdLOJaTp8/mKz69/RpatVBas2OqWas7jrlaLGfHdBkt 2621 Hs6fxOzzAB7Wro=; 2622 Received: from dsl-10.2.3.4.network.example.com [10.2.3.4] 2623 by submitserver.example.com with SUBMISSION; 2624 Fri, 11 Jul 2003 21:01:54 -0700 (PDT) 2625 From: Joe SixPack 2626 To: Suzie Q 2627 Subject: Is dinner ready? 2628 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT) 2629 Message-ID: <20030712040037.46341.5F8J@football.example.com> 2631 Hi. 2633 We lost the game. Are you hungry yet? 2635 Joe. 2637 Appendix B. Usage Examples (INFORMATIVE) 2639 DKIM signing and validating can be used in different ways, for 2640 different operational scenarios. This Appendix discusses some common 2641 examples. 2643 NOTE: Descriptions in this Appendix are for informational 2644 purposes only. They describe various ways that DKIM can be used, 2645 given particular constraints and needs. In no case are these 2646 examples intended to be taken as providing explanation or guidance 2647 concerning DKIM specification details, when creating an 2648 implementation. 2650 B.1 Alternate Submission Scenarios 2652 In the most simple scenario, a user's MUA, MSA, and Internet 2653 (boundary) MTA are all within the same administrative environment, 2654 using the same domain name. Therefore, all of the components 2655 involved in submission and initial transfer are related. However it 2656 is common for two or more of the components to be under independent 2657 administrative control. This creates challenges for choosing and 2658 administering the domain name to use for signing, and for its 2659 relationship to common email identity header fields. 2661 B.1.1 Delegated Business Functions 2663 Some organizations assign specific business functions to discrete 2664 groups, inside or outside the organization. The goal, then, is to 2665 authorize that group to sign some mail, but to constrain what 2666 signatures they can generate. DKIM Selectors (the "s=" signature 2667 tag) and granularity (the "g=" key tag) facilitate this kind of 2668 restricted authorization. Examples of these outsourced business 2669 functions are legitimate email marketing providers and corporate 2670 benefits providers. 2672 Here, the delegated group needs to be able to send messages that are 2673 signed, using the email domain of the client company. At the same 2674 time, the client often is reluctant to register a key for the 2675 provider that grants the ability to send messages for arbitrary 2676 addresses in the domain. 2678 There are multiple ways to administer these usage scenarios. In one 2679 case, the client organization provides all of the public query 2680 service (for example, DNS) administration, and in another it uses DNS 2681 delegation to enable all on-going administration of the DKIM key 2682 record by the delegated group. 2684 If the client organization retains responsibility for all of the DNS 2685 administration, the outsourcing company can generate a key pair, 2686 supplying the public key to the client company, which then registers 2687 it in the query service, using a unique Selector that authorizes a 2688 specific From header field local-part. For example, a client with 2689 the domain "example.com" could have the Selector record specify 2690 "g=winter-promotions" so that this signature is only valid for mail 2691 with a From address of "winter-promotions@example.com". This would 2692 enable the provider to send messages using that specific address and 2693 have them verify properly. The client company retains control over 2694 the email address because it retains the ability to revoke the key at 2695 any time. 2697 If the client wants the delegated group to do the DNS administration, 2698 it can have the domain name that is specified with the selector point 2699 to the provider's DNS server. The provider then creates and 2700 maintains all of the DKIM signature information for that Selector. 2701 Hence, the client cannot provide constraints on the local-part of 2702 addresses that get signed, but it can revoke the provider's signing 2703 rights by removing the DNS delegation record. 2705 B.1.2 PDAs and Similar Devices 2707 PDAs demonstrate the need for using multiple keys per domain. 2708 Suppose that John Doe wanted to be able to send messages using his 2709 corporate email address, jdoe@example.com, and his email device did 2710 not have the ability to make a VPN connection to the corporate 2711 network, either because the device is limited or because there are 2712 restrictions enforced by his Internet access provider. If the device 2713 was equipped with a private key registered for jdoe@example.com by 2714 the administrator of the example.com domain, and appropriate software 2715 to sign messages, John could sign the message on the device itself 2716 before transmission through the outgoing network of the access 2717 service provider. 2719 B.1.3 Roaming Users 2721 Roaming users often find themselves in circumstances where it is 2722 convenient or necessary to use an SMTP server other than their home 2723 server; examples are conferences and many hotels. In such 2724 circumstances a signature that is added by the submission service 2725 will use an identity that is different from the user's home system. 2727 Ideally roaming users would connect back to their home server using 2728 either a VPN or a SUBMISSION server running with SMTP AUTHentication 2729 on port 587. If the signing can be performed on the roaming user's 2730 laptop then they can sign before submission, although the risk of 2731 further modification is high. If neither of these are possible, 2732 these roaming users will not be able to send mail signed using their 2733 own domain key. 2735 B.1.4 Independent (Kiosk) Message Submission 2737 Stand-alone services, such as walk-up kiosks and web-based 2738 information services, have no enduring email service relationship 2739 with the user, but the user occasionally requests that mail be sent 2740 on their behalf. For example, a website providing news often allows 2741 the reader to forward a copy of the article to a friend. This is 2742 typically done using the reader's own email address, to indicate who 2743 the author is. This is sometimes referred to as the "Evite problem", 2744 named after the website of the same name that allows a user to send 2745 invitations to friends. 2747 A common way this is handled is to continue to put the reader's email 2748 address in the From header field of the message, but put an address 2749 owned by the email posting site into the Sender header field. The 2750 posting site can then sign the message, using the domain that is in 2751 the Sender field. This provides useful information to the receiving 2752 email site, which is able to correlate the signing domain with the 2753 initial submission email role. 2755 Receiving sites often wish to provide their end users with 2756 information about mail that is mediated in this fashion. Although 2757 the real efficacy of different approaches is a subject for human 2758 factors usability research, one technique that is used is for the 2759 verifying system to rewrite the From header field, to indicate the 2760 address that was verified. For example: From: John Doe via 2761 news@news-site.com . (Note that, such rewriting 2762 will break a signature, unless it is done after the verification pass 2763 is complete.) 2765 B.2 Alternate Delivery Scenarios 2767 Email is often received at a mailbox that has an address different 2768 from the one used during initial submission. In these cases, an 2769 intermediary mechanism operates at the address originally used and it 2770 then passes the message on to the final destination. This mediation 2771 process presents some challenges for DKIM signatures. 2773 B.2.1 Affinity Addresses 2775 "Affinity addresses" allow a user to have an email address that 2776 remains stable, even as the user moves among different email 2777 providers. They are typically associated with college alumni 2778 associations, professional organizations, and recreational 2779 organizations with which they expect to have a long-term 2780 relationship. These domains usually provide forwarding of incoming 2781 email, and they often have an associated Web application which 2782 authenticates the user and allows the forwarding address to be 2783 changed. However these services usually depend on the user's sending 2784 outgoing messages through their own service provider's MTA. Hence, 2785 mail that is signed with the domain of the affinity address is not 2786 signed by an entity that is administered by the organization owning 2787 that domain. 2789 With DKIM, affinity domains could use the Web application to allow 2790 users to register per-user keys to be used to sign messages on behalf 2791 of their affinity address. The user would take away the secret half 2792 of the key pair for signing, and the affinity domain would publish 2793 the public half in DNS for access by verifiers. 2795 This is another application that takes advantage of user-level 2796 keying, and domains used for affinity addresses would typically have 2797 a very large number of user-level keys. Alternatively, the affinity 2798 domain could handle outgoing mail, operating a mail submission agent 2799 that authenticates users before accepting and signing messages for 2800 them. This is of course dependent on the user's service provider not 2801 blocking the relevant TCP ports used for mail submission. 2803 B.2.2 Simple Address Aliasing (.forward) 2805 In some cases a recipient is allowed to configure an email address to 2806 cause automatic redirection of email messages from the original 2807 address to another, such as through the use of a Unix .forward file. 2808 In this case messages are typically redirected by the mail handling 2809 service of the recipient's domain, without modification, except for 2810 the addition of a Received header field to the message and a change 2811 in the envelope recipient address. In this case, the recipient at 2812 the final address' mailbox is likely to be able to verify the 2813 original signature since the signed content has not changed, and DKIM 2814 is able to validate the message signature. 2816 B.2.3 Mailing Lists and Re-Posters 2818 There is a wide range of behaviors in services that take delivery of 2819 a message and then resubmit it. A primary example is with mailing 2820 lists (collectively called "forwarders" below), ranging from those 2821 which make no modification to the message itself, other than to add a 2822 Received header field and change the envelope information, to those 2823 which add header fields, change the Subject header field, add content 2824 to the body (typically at the end), or reformat the body in some 2825 manner. The simple ones produces messages that are quite similar to 2826 the automated alias services. More elaborate systems essentially 2827 create a new message. 2829 A Forwarder which does not modify the body or signed header fields of 2830 a message is likely to maintain the validity of the existing 2831 signature. It also could choose to add its own signature to the 2832 message. 2834 Forwarders which modify a message in a way that could make an 2835 existing signature invalid are particularly good candidates for 2836 adding their own signatures (e.g., mailing-list-name@example.net). 2837 Since (re-)signing is taking responsibility for the content of the 2838 message, these signing forwarders are likely to be selective, and 2839 forward or re-sign only those messages which are received with a 2840 valid signature or some other basis for knowing that the messages 2841 being signed is not spoofed. 2843 A common practice among systems that are primarily re-distributors of 2844 mail is to add a Sender header field to the message, to identify the 2845 address being used to sign the message. This practice will remove 2846 any preexisting Sender header field as required by [RFC2822]. The 2847 forwarder applies a new DKIM-Signature header field with the 2848 signature, public key, and related information of the forwarder. 2850 Appendix C. Creating a public key (INFORMATIVE) 2852 The default signature is an RSA signed SHA256 digest of the complete 2853 email. For ease of explanation, the openssl command is used to 2854 describe the mechanism by which keys and signatures are managed. One 2855 way to generate a 1024 bit, unencrypted private-key suitable for 2856 DKIM, is to use openssl like this: 2858 $ openssl genrsa -out rsa.private 1024 2860 For increased security, the "-passin" parameter can also be added to 2861 encrypt the private key. Use of this parameter will require entering 2862 a password for several of the following steps. Servers may prefer to 2863 use hardware cryptographic support. 2865 The "genrsa" step results in the file rsa.private containing the key 2866 information similar to this: 2868 -----BEGIN RSA PRIVATE KEY----- 2869 MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC 2870 jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb 2871 to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB 2872 AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX 2873 /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ 2874 gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO 2875 n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m 2876 3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/ 2877 eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj 2878 7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA 2879 qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf 2880 eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX 2881 GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc= 2882 -----END RSA PRIVATE KEY----- 2884 To extract the public-key component from the private-key, use openssl 2885 like this: 2887 $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM 2889 This results in the file rsa.public containing the key information 2890 similar to this: 2892 -----BEGIN PUBLIC KEY----- 2893 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM 2894 oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R 2895 tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI 2896 MmPSPDdQPNUYckcQ2QIDAQAB 2897 -----END PUBLIC KEY----- 2899 This public-key data (without the BEGIN and END tags) is placed in 2900 the DNS. With the signature, canonical email contents, and public 2901 key, a verifying system can test the validity of the signature. The 2902 openssl invocation to verify a signature looks like this: 2904 openssl dgst -verify rsa.public -sha256 -signature signature.file \ 2905