+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Support for DKIM (DomainKeys Identified Mail) - RFC4871" "CHID12" &&&
+ "DKIM Support"
+.cindex "DKIM"
+
+Since version 4.70, DKIM support is compiled into Exim by default. It can be
+disabled by setting DISABLE_DKIM=yes in Local/Makefile.
+
+Exim's DKIM implementation allows to
+.olist
+Sign outgoing messages: This function is implemented in the SMTP transport.
+It can co-exist with all other Exim features, including transport filters.
+.next
+Verify signatures in incoming messages: This is implemented by an additional
+ACL (acl_smtp_dkim), which can be called several times per message, with
+different signature contexts.
+.endlist
+
+In typical Exim style, the verification implementation does not include any
+default "policy". Instead it enables you to build your own policy using
+Exim's standard controls.
+
+Please note that verification of DKIM signatures in incoming mail is turned
+on by default for logging purposes. For each signature in incoming email,
+exim will log a line displaying the most important signature details, and the
+signature status. Here is an example:
+.code
+2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: d=facebookmail.com s=q1-2009b c=relaxed/relaxed a=rsa-sha1 i=@facebookmail.com t=1252484542 [verification succeeded]
+.endd
+You might want to turn off DKIM verification processing entirely for internal
+or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
+control modifier. This should typically be done in the RCPT ACL, at points
+where you accept mail from relay sources (internal hosts or authenticated
+senders).
+
+
+.section "Signing outgoing messages" "SECID513"
+.cindex "DKIM" "signing"
+
+Signing is implemented by setting private options on the SMTP transport.
+These options take (expandable) strings as arguments.
+
+.option dkim_domain smtp string&!! unset
+MANDATORY:
+The domain you want to sign with. The result of this expanded
+option is put into the &%$dkim_domain%& expansion variable.
+
+.option dkim_selector smtp string&!! unset
+MANDATORY:
+This sets the key selector string. You can use the &%$dkim_domain%& expansion
+variable to look up a matching selector. The result is put in the expansion
+variable &%$dkim_selector%& which should be used in the &%dkim_private_key%&
+option along with &%$dkim_domain%&.
+
+.option dkim_private_key smtp string&!! unset
+MANDATORY:
+This sets the private key to use. You can use the &%$dkim_domain%& and
+&%$dkim_selector%& expansion variables to determine the private key to use.
+The result can either
+.ilist
+be a valid RSA private key in ASCII armor, including line breaks.
+.next
+start with a slash, in which case it is treated as a file that contains
+the private key.
+.next
+be "0", "false" or the empty string, in which case the message will not
+be signed. This case will not result in an error, even if &%dkim_strict%&
+is set.
+.endlist
+
+.option dkim_canon smtp string&!! unset
+OPTIONAL:
+This option sets the canonicalization method used when signing a message.
+The DKIM RFC currently supports two methods: "simple" and "relaxed".
+The option defaults to "relaxed" when unset. Note: the current implementation
+only supports using the same canonicalization method for both headers and body.
+
+.option dkim_strict smtp string&!! unset
+OPTIONAL:
+This option defines how Exim behaves when signing a message that
+should be signed fails for some reason. When the expansion evaluates to
+either "1" or "true", Exim will defer. Otherwise Exim will send the message
+unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
+variables here.
+
+.option dkim_sign_headers smtp string&!! unset
+OPTIONAL:
+When set, this option must expand to (or be specified as) a colon-separated
+list of header names. Headers with these names will be included in the message
+signature. When unspecified, the header names recommended in RFC4871 will be
+used.
+
+
+.section "Verifying DKIM signatures in incoming mail" "SECID514"
+.cindex "DKIM" "verification"
+
+Verification of DKIM signatures in incoming email is implemented via the
+&%acl_smtp_dkim%& ACL. By default, this ACL is called once for each
+syntactically(!) correct signature in the incoming message.
+
+To evaluate the signature in the ACL a large number of expansion variables
+containing the signature status and its details are set up during the
+runtime of the ACL.
+
+Calling the ACL only for existing signatures is not sufficient to build
+more advanced policies. For that reason, the global option
+&%dkim_verify_signers%&, and a global expansion variable
+&%$dkim_signers%& exist.
+
+The global option &%dkim_verify_signers%& can be set to a colon-separated
+list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
+called. It is expanded when the message has been received. At this point,
+the expansion variable &%$dkim_signers%& already contains a colon-separated
+list of signer domains and identities for the message. When
+&%dkim_verify_signers%& is not specified in the main configuration,
+it defaults as:
+.code
+dkim_verify_signers = $dkim_signers
+.endd
+This leads to the default behaviour of calling &%acl_smtp_dkim%& for each
+DKIM signature in the message. Current DKIM verifiers may want to explicitly
+call the ACL for known domains or identities. This would be achieved as follows:
+.code
+dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
+.endd
+This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
+and "ebay.com", plus all domains and identities that have signatures in the message.
+You can also be more creative in constructing your policy. For example:
+.code
+dkim_verify_signers = $sender_address_domain:$dkim_signers
+.endd
+
+If a domain or identity is listed several times in the (expanded) value of
+&%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
git://git.exim.org / exim.git / blobdiff