--- 1/draft-ietf-dkim-rfc4871bis-05.txt 2011-04-13 00:16:11.000000000 +0200 +++ 2/draft-ietf-dkim-rfc4871bis-06.txt 2011-04-13 00:16:11.000000000 +0200 @@ -1,21 +1,21 @@ Network Working Group D. Crocker, Ed. Internet-Draft Brandenburg InternetWorking Obsoletes: 4871 (if approved) T. Hansen, Ed. Intended status: Standards Track AT&T Laboratories -Expires: September 29, 2011 M. Kucherawy, Ed. +Expires: October 14, 2011 M. Kucherawy, Ed. Cloudmark - March 28, 2011 + April 12, 2011 DomainKeys Identified Mail (DKIM) Signatures - draft-ietf-dkim-rfc4871bis-05 + draft-ietf-dkim-rfc4871bis-06 Abstract DomainKeys Identified Mail (DKIM) permits a person, role, or organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message. This can be an author's organization, an operational relay or one of their agents. DKIM separates the question of the identity of the signer of the message from the purported author of the message. Assertion of responsibility is validated through a @@ -32,21 +32,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 29, 2011. + This Internet-Draft will expire on October 14, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -65,22 +65,22 @@ 1.4. Data Integrity . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 7 2.1. Signers . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2. Verifiers . . . . . . . . . . . . . . . . . . . . . . . . 7 2.3. Identity . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4. Identifier . . . . . . . . . . . . . . . . . . . . . . . . 7 2.5. Signing Domain Identifier (SDID) . . . . . . . . . . . . . 7 2.6. Agent or User Identifier (AUID) . . . . . . . . . . . . . 8 2.7. Identity Assessor . . . . . . . . . . . . . . . . . . . . 8 2.8. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . 8 - 2.9. Common ABNF Tokens . . . . . . . . . . . . . . . . . . . . 9 - 2.10. Imported ABNF Tokens . . . . . . . . . . . . . . . . . . . 9 + 2.9. Imported ABNF Tokens . . . . . . . . . . . . . . . . . . . 9 + 2.10. Common ABNF Tokens . . . . . . . . . . . . . . . . . . . . 9 2.11. DKIM-Quoted-Printable . . . . . . . . . . . . . . . . . . 9 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Selectors . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2. Tag=Value Lists . . . . . . . . . . . . . . . . . . . . . 12 3.3. Signing and Verification Algorithms . . . . . . . . . . . 13 3.4. Canonicalization . . . . . . . . . . . . . . . . . . . . . 15 3.5. The DKIM-Signature Header Field . . . . . . . . . . . . . 19 3.6. Key Management and Representation . . . . . . . . . . . . 28 3.7. Computing the Message Hashes . . . . . . . . . . . . . . . 33 3.8. Input Requirements . . . . . . . . . . . . . . . . . . . . 35 @@ -133,24 +133,25 @@ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 64 9.2. Informative References . . . . . . . . . . . . . . . . . . 65 Appendix A. Example of Use (INFORMATIVE) . . . . . . . . . . . . 66 A.1. The User Composes an Email . . . . . . . . . . . . . . . . 66 A.2. The Email is Signed . . . . . . . . . . . . . . . . . . . 67 A.3. The Email Signature is Verified . . . . . . . . . . . . . 68 Appendix B. Usage Examples (INFORMATIVE) . . . . . . . . . . . . 69 B.1. Alternate Submission Scenarios . . . . . . . . . . . . . . 69 B.2. Alternate Delivery Scenarios . . . . . . . . . . . . . . . 71 Appendix C. Creating a Public Key (INFORMATIVE) . . . . . . . . . 73 - Appendix D. Removal of Key Granularity . . . . . . . . . . . . . 74 - Appendix E. MUA Considerations . . . . . . . . . . . . . . . . . 74 - Appendix F. Acknowledgements . . . . . . . . . . . . . . . . . . 75 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 75 + C.1. Compatibility with DomainKeys Key Records . . . . . . . . 74 + + Appendix D. MUA Considerations . . . . . . . . . . . . . . . . . 74 + Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 75 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 76 1. Introduction DomainKeys Identified Mail (DKIM) permits a person, role, or organization to claim some responsibility for a message by associating a domain name [RFC1034] with the message [RFC5322], which they are authorized to use. This can be an author's organization, an operational relay or one of their agents. Assertion of responsibility is validated through a cryptographic signature and querying the signer's domain directly to retrieve the appropriate @@ -328,31 +329,21 @@ The formal ABNF for these are (WSP and LWSP are given for information only): WSP = SP / HTAB LWSP = *(WSP / CRLF WSP) FWS = [*WSP CRLF] 1*WSP The definition of FWS is identical to that in [RFC5322] except for the exclusion of obs-FWS. -2.9. Common ABNF Tokens - - The following ABNF tokens are used elsewhere in this document: - hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] - ALPHADIGITPS = (ALPHA / DIGIT / "+" / "/") - base64string = ALPHADIGITPS *([FWS] ALPHADIGITPS) - [ [FWS] "=" [ [FWS] "=" ] ] - hdr-name = field-name - qp-hdr-value = dkim-quoted-printable ; with "|" encoded - -2.10. Imported ABNF Tokens +2.9. Imported ABNF Tokens The following tokens are imported from other RFCs as noted. Those RFCs should be considered definitive. The following tokens are imported from [RFC5321]: o "Local-part" (implementation warning: this permits quoted strings) o "sub-domain" @@ -369,20 +360,30 @@ o "hex-octet" (a quoted-printable encoded octet) INFORMATIVE NOTE: Be aware that the ABNF in [RFC2045] does not obey the rules of [RFC5234] and must be interpreted accordingly, particularly as regards case folding. Other tokens not defined herein are imported from [RFC5234]. These are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF, etc. +2.10. Common ABNF Tokens + + The following ABNF tokens are used elsewhere in this document: + hyphenated-word = ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ] + ALPHADIGITPS = (ALPHA / DIGIT / "+" / "/") + base64string = ALPHADIGITPS *([FWS] ALPHADIGITPS) + [ [FWS] "=" [ [FWS] "=" ] ] + hdr-name = field-name + qp-hdr-value = dkim-quoted-printable ; with "|" encoded + 2.11. DKIM-Quoted-Printable The DKIM-Quoted-Printable encoding syntax resembles that described in Quoted-Printable [RFC2045], Section 6.7: any character MAY be encoded as an "=" followed by two hexadecimal digits from the alphabet "0123456789ABCDEF" (no lowercase characters permitted) representing the hexadecimal-encoded integer value of that character. All control characters (those with values < %x20), 8-bit characters (values > %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon (";", %x3B) MUST be encoded. Note that all whitespace, including @@ -507,24 +508,24 @@ to reuse selectors for new keys. A better strategy is to assign new keys to new selectors. 3.2. Tag=Value Lists DKIM uses a simple "tag=value" syntax in several contexts, including in messages and domain signature records. Values are a series of strings containing either plain text, "base64" text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid, - Section 6.7), or "dkim-quoted-printable" (as defined in Section 2.6). - The name of the tag will determine the encoding of each value. - Unencoded semicolon (";") characters MUST NOT occur in the tag value, - since that separates tag-specs. + Section 6.7), or "dkim-quoted-printable" (as defined in + Section 2.11). The name of the tag will determine the encoding of + each value. Unencoded semicolon (";") characters MUST NOT occur in + the tag value, since that separates tag-specs. INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined below (as "tag-value") only includes 7-bit characters, an implementation that wished to anticipate future standards would be advised not to preclude the use of UTF8-encoded text in tag=value lists. Formally, the ABNF syntax rules are as follows: tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] @@ -1247,24 +1248,25 @@ record. Records beginning with a "v=" tag with any other value MUST be discarded. Note that verifiers must do a string comparison on this value; for example, "DKIM1" is not the same as "DKIM1.0". ABNF: key-v-tag = %x76 [FWS] "=" [FWS] %x44 %x4B %x49 %x4D %x31 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to allowing all algorithms). A colon-separated list of hash - algorithms that might be used. Signers and Verifiers MUST support - the "sha256" hash algorithm. Verifiers MUST also support the - "sha1" hash algorithm. Unrecognized hash algorithms MUST be - ignored. + algorithms that might be used. Unrecognized algorithms MUST be + ignored. Refer to Section 3.3 for a discussion of the hash + algorithms implemented by Signers and Verifiers. . The set of + algorithms listed in this tag in each record is an operational + choice made by the Signer. ABNF: key-h-tag = %x68 [FWS] "=" [FWS] key-h-tag-alg 0*( [FWS] ":" [FWS] key-h-tag-alg ) key-h-tag-alg = "sha1" / "sha256" / x-key-h-tag-alg x-key-h-tag-alg = hyphenated-word ; for future extension k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and verifiers MUST support the "rsa" key type. The "rsa" key type indicates that an ASN.1 DER-encoded [ITU-X660-1997] RSAPublicKey [RFC3447] (see Sections Section 3.1 and A.1.1) is being used in @@ -2181,21 +2183,21 @@ if none, return to try another signature in the usual way". 5. If the result returned from the query does not adhere to the format defined in this specification, the verifier MUST ignore the key record and return PERMFAIL (key syntax error). Verifiers are urged to validate the syntax of key records carefully to avoid attempted attacks. In particular, the verifier MUST ignore keys with a version code ("v=" tag) that they do not implement. 6. If the "h=" tag exists in the public key record and the hash - algorithm implied by the a= tag in the DKIM-Signature header + algorithm implied by the "a=" tag in the DKIM-Signature header field is not included in the contents of the "h=" tag, the verifier MUST ignore the key record and return PERMFAIL (inappropriate hash algorithm). 7. If the public key data (the "p=" tag) is empty, then this key has been revoked and the verifier MUST treat this as a failed signature check and return PERMFAIL (key revoked). There is no defined semantic difference between a key that has been revoked and a key record that has been removed. @@ -2350,197 +2352,196 @@ which it was registered or updated, and an indication of its current status which MUST be one of "active" (in current use) or "historic" (no longer in current use). 7.1. DKIM-Signature Tag Specifications A DKIM-Signature provides for a list of tag specifications. IANA has established the DKIM-Signature Tag Specification Registry for tag specifications that can be used in DKIM-Signature fields. - The initial entries in the registry comprise: + The updated entries in the registry comprise: +------+-----------------+--------+ | TYPE | REFERENCE | STATUS | +------+-----------------+--------+ | v | (this document) | active | | a | (this document) | active | | b | (this document) | active | | bh | (this document) | active | | c | (this document) | active | | d | (this document) | active | | h | (this document) | active | | i | (this document) | active | | l | (this document) | active | | q | (this document) | active | | s | (this document) | active | | t | (this document) | active | | x | (this document) | active | | z | (this document) | active | +------+-----------------+--------+ - Table 1: DKIM-Signature Tag Specification Registry Initial - Values + Table 1: DKIM-Signature Tag Specification Registry Updated Values 7.2. DKIM-Signature Query Method Registry The "q=" tag-spec (specified in Section 3.5) provides for a list of query methods. IANA has established the DKIM-Signature Query Method Registry for mechanisms that can be used to retrieve the key that will permit validation processing of a message signed using DKIM. - The initial entry in the registry comprises: + The updated entry in the registry comprises: +------+--------+-----------------+--------+ | TYPE | OPTION | REFERENCE | STATUS | +------+--------+-----------------+--------+ | dns | txt | (this document) | active | +------+--------+-----------------+--------+ - DKIM-Signature Query Method Registry Initial Values + DKIM-Signature Query Method Registry Updated Values 7.3. DKIM-Signature Canonicalization Registry The "c=" tag-spec (specified in Section 3.5) provides for a specifier for canonicalization algorithms for the header and body of the message. IANA has established the DKIM-Signature Canonicalization Algorithm Registry for algorithms for converting a message into a canonical form before signing or verifying using DKIM. - The initial entries in the header registry comprise: + The updated entries in the header registry comprise: +---------+-----------------+--------+ | TYPE | REFERENCE | STATUS | +---------+-----------------+--------+ | simple | (this document) | active | | relaxed | (this document) | active | +---------+-----------------+--------+ DKIM-Signature Header Canonicalization Algorithm Registry - Initial Values + Updated Values - The initial entries in the body registry comprise: + The updated entries in the body registry comprise: +---------+-----------------+--------+ | TYPE | REFERENCE | STATUS | +---------+-----------------+--------+ | simple | (this document) | active | | relaxed | (this document) | active | +---------+-----------------+--------+ DKIM-Signature Body Canonicalization Algorithm Registry - Initial Values + Updated Values 7.4. _domainkey DNS TXT Record Tag Specifications A _domainkey DNS TXT record provides for a list of tag specifications. IANA has established the DKIM _domainkey DNS TXT Tag Specification Registry for tag specifications that can be used in DNS TXT Records. - The initial entries in the registry comprise: + The updated entries in the registry comprise: +------+-----------------+----------+ | TYPE | REFERENCE | STATUS | +------+-----------------+----------+ | v | (this document) | active | | g | [RFC4871] | historic | | h | (this document) | active | | k | (this document) | active | | n | (this document) | active | | p | (this document) | active | | s | (this document) | active | | t | (this document) | active | +------+-----------------+----------+ DKIM _domainkey DNS TXT Record Tag Specification Registry - Initial Values + Updated Values 7.5. DKIM Key Type Registry The "k=" (specified in Section 3.6.1) and the "a=" (specified in Section 3.5) tags provide for a list of mechanisms that can be used to decode a DKIM signature. IANA has established the DKIM Key Type Registry for such mechanisms. - The initial entry in the registry comprises: + The updated entry in the registry comprises: +------+-----------+--------+ | TYPE | REFERENCE | STATUS | +------+-----------+--------+ | rsa | [RFC3447] | active | +------+-----------+--------+ - DKIM Key Type Initial Values + DKIM Key Type Updated Values 7.6. DKIM Hash Algorithms Registry The "h=" (specified in Section 3.6.1) and the "a=" (specified in Section 3.5) tags provide for a list of mechanisms that can be used to produce a digest of message data. IANA has established the DKIM Hash Algorithms Registry for such mechanisms. - The initial entries in the registry comprise: + The updated entries in the registry comprise: +--------+-------------------+--------+ | TYPE | REFERENCE | STATUS | +--------+-------------------+--------+ | sha1 | [FIPS-180-2-2002] | active | | sha256 | [FIPS-180-2-2002] | active | +--------+-------------------+--------+ - DKIM Hash Algorithms Initial Values + DKIM Hash Algorithms Updated Values 7.7. DKIM Service Types Registry The "s=" tag (specified in Section 3.6.1) provides for a list of service types to which this selector may apply. IANA has established the DKIM Service Types Registry for service types. - The initial entries in the registry comprise: + The updated entries in the registry comprise: +-------+-----------------+--------+ | TYPE | REFERENCE | STATUS | +-------+-----------------+--------+ | email | (this document) | active | | * | (this document) | active | +-------+-----------------+--------+ - DKIM Service Types Registry Initial Values + DKIM Service Types Registry Updated Values 7.8. DKIM Selector Flags Registry The "t=" tag (specified in Section 3.6.1) provides for a list of flags to modify interpretation of the selector. IANA has established the DKIM Selector Flags Registry for additional flags. - The initial entries in the registry comprise: + The updated entries in the registry comprise: +------+-----------------+--------+ | TYPE | REFERENCE | STATUS | +------+-----------------+--------+ | y | (this document) | active | | s | (this document) | active | +------+-----------------+--------+ - DKIM Selector Flags Registry Initial Values + DKIM Selector Flags Registry Updated Values 7.9. DKIM-Signature Header Field IANA has added DKIM-Signature to the "Permanent Message Header Fields" registry (see [RFC3864]) for the "mail" protocol, using this document as the reference. 8. Security Considerations It has been observed that any mechanism that is introduced that @@ -2831,28 +2832,34 @@ include From: and Subject:, The resulting message violates section 3.6 of [RFC5322]. The way such input will be handled and displayed by an MUA is unpredictable, but in some cases it might display the newly added header fields rather than those that are part of the originally signed message alongside some "valid DKIM signature" annotation. This might allow an attacker to replay a previously sent, signed message with a different Subject:, From: or To: field. - Because of this, implementers are strongly advised to reject or treat - as suspicious any message that has multiple copies of header fields - that are disallowed by Section 3.6 of [RFC5322] particularly those - that are typically displayed to end users (From:, To:, Cc:, - Subject:). A signing module could return an error rather than - generate a signature; a verifying module might return a syntax error - code or arrange not to return a positive result even if the signature - technically validates. + However, [RFC5322] also tolerates obsolete message syntax, which does + allow things like multiple From: fields on messages. The + implementation of DKIM thus potentially creates a more stringent + layer of expectation regarding the meaning of an identity, while that + additional meaning is either obscured from or incorrectly presented + to an end user in this context. + + Implementers need to consider this possibility when designing their + input handling functions. Outright rejection of messages that + violate Section 3.6 of [RFC5322] will interfere with delivery of + legacy formats. Instead, given such input, a signing module could + return an error rather than generate a signature; a verifying module + might return a syntax error code or arrange not to return a positive + result even if the signature technically validates. Senders concerned that their messages might be particularly vulnerable to this sort of attack and who do not wish to rely on receiver filtering of invalid messages can ensure that adding additional header fields will break the DKIM signature by including two copies of the header fields about which they are concerned in the signature (e.g. "h= ... from:from:to:to:subject:subject ..."). See Sections 3.5 and 5.4 for further discussion of this mechanism. Specific validity rules for all known header fields can be gleaned @@ -3315,35 +3322,40 @@ -----END PUBLIC KEY----- This public-key data (without the BEGIN and END tags) is placed in the DNS: brisbane IN TXT ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ" "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt" "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v" "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi" "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB") -Appendix D. Removal of Key Granularity +C.1. Compatibility with DomainKeys Key Records - An important change since [RFC4871] is the removal of the "g=" tag - from key records, which enabled signers to constrain use of a signing - key to specific users by requiring a match to the local-part of the - "i=" tag. [RFC4871] also discussed enabling backward compatibility - with DomainKeys [RFC4870] when "g=" is present without a value. + DKIM key records were designed to be backwards-compatible in many + cases with key records used by DomainKeys [RFC4870] (sometimes + referred to as "selector records" in the DomainKeys context). One + area of incompatibility warrants particular attention. The "g=" tag/ + value may be used in DomainKeys and [RFC4871] key records to provide + finer granularity of the validity of the key record to a specific + local-part. A null "g=" value in DomainKeys is valid for all + addresses in the domain. This differs from the usage in the original + DKIM specification, where a null "g=" value is not valid for any + address. In particular, the example public key record in Section + 3.2.3 of [RFC4870] with DKIM. - As use of "g=" is now deprecated, a verifier compliant with this - document will now ignore that tag completely for records that still - contain it. Signers should thus be aware that compliant verifiers - will no longer constrain use of the key based on any value found in a - "g=" tag. + Although the "g=" tag has been deprecated in this version of the DKIM + specification, signers are advised not to include the "g=" tag in key + records because some [RFC4871]-compliant verifiers will be in use for + a considerable period to come. -Appendix E. MUA Considerations +Appendix D. MUA Considerations When a DKIM signature is verified, the processing system sometimes makes the result available to the recipient user's MUA. How to present this information to the user in a way that helps them is a matter of continuing human factors usability research. The tendency is to have the MUA highlight the SDID, in an attempt to show the user the identity that is claiming responsibility for the message. An MUA might do this with visual cues such as graphics, or it might include the address in an alternate view, or it might even rewrite the original From address using the verified information. Some MUAs @@ -3356,21 +3368,21 @@ unsigned header fields in a way that might be construed by the end user as having been signed. If the message has an l= tag whose value does not extend to the end of the message, the MUA might also hide or mark the portion of the message body that was not signed. The aforementioned information is not intended to be exhaustive. The MUA may choose to highlight, accentuate, hide, or otherwise display any other information that may, in the opinion of the MUA author, be deemed important to the end user. -Appendix F. Acknowledgements +Appendix E. Acknowledgements The previous IETF version of DKIM [RFC4871] was edited by: Eric Allman, Jon Callas, Mark Delany, Miles Libbey, Jim Fenton and Michael Thomas. That specification was the result of an extended, collaborative effort, including participation by: Russ Allbery, Edwin Aoki, Claus Assmann, Steve Atkins, Rob Austein, Fred Baker, Mark Baugher, Steve Bellovin, Nathaniel Borenstein, Dave Crocker, Michael Cudahy, Dennis Dayman, Jutta Degener, Frank Ellermann, Patrik Faeltstroem, Mark