diff options
| -rw-r--r-- | doc/doc-docbook/spec.xfpt | 72 | ||||
| -rw-r--r-- | doc/doc-txt/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/doc-txt/experimental-spec.txt | 408 |
3 files changed, 77 insertions, 407 deletions
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index ec631523b..7b5d5c44a 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,4 +1,4 @@ -. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.49 2009/01/02 16:42:31 nm4 Exp $ +. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.50 2009/06/11 14:07:57 tom Exp $ . . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is @@ -34267,13 +34267,81 @@ unqualified domain &'foundation'&. .ecindex IIDforspo2 .ecindex IIDforspo3 +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.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 context. +.endlist + +.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. + +.vitem &%dkim_domain = <expanded string> [MANDATORY]%& +The domain you want to sign with. The result of this expanded +option is put into the $dkim_domain expansion variable. + +.vitem &%dkim_selector = <expanded string> [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. + +.vitem &%dkim_private_key = <expanded string> [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 +.ulist +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 + +.vitem &%dkim_canon = <expanded string> [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 support using the same canonicalization method for both headers and body. + +.vitem &%dkim_strict = <expanded string> [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. + +.vitem &%dkim_sign_headers = <expanded string> [OPTIONAL]%& +When set, this option must expand to (or be specified as) a colon-separated +list of header names. These headers will be included in the message +signature. When unspecified, the headers recommended in RFC4871 will be used. + . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// -.chapter "Adding new drivers or lookup types" "CHID12" &&& +.chapter "Adding new drivers or lookup types" "CHID13" &&& "Adding drivers or lookups" .cindex "adding drivers" .cindex "new drivers, adding" diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog index 7b1e85ef4..a3c09f801 100644 --- a/doc/doc-txt/ChangeLog +++ b/doc/doc-txt/ChangeLog @@ -1,4 +1,4 @@ -$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.562 2009/01/02 17:22:12 nm4 Exp $ +$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.563 2009/06/11 14:07:57 tom Exp $ Change log file for Exim from version 4.21 ------------------------------------------- @@ -94,6 +94,8 @@ NM/13 Bugzilla 590: Correct handling of Resent-Date headers. NM/14 Bugzilla 614: Added timeout setting to transport filter. Patch provided by Dean Brooks +TK/05 Add native DKIM support (does not depend on external libraries). + Exim version 4.69 ----------------- diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 4175173c3..be871d2b9 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -1,4 +1,4 @@ -$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.11 2008/02/12 12:52:51 nm4 Exp $ +$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.12 2009/06/11 14:07:57 tom Exp $ From time to time, experimental features may be added to Exim. While a feature is experimental, there will be a build-time @@ -8,407 +8,7 @@ about experimenatal features, all of which are unstable and liable to incompatibile change. -0. DKIM support --------------------------------------------------------------- - -DKIM support is implemented via libdkim. A compatible version -is available here: - -http://duncanthrax.net/exim-experimental/libdkim-1.0.15-tk.tar.gz - -Build the lib according to the instructions in the enclosed -INSTALL file. - -To build Exim with DKIM support, specify this in Local/Makefile: - -EXPERIMENTAL_DKIM=yes -CFLAGS += -I/home/tom/libdkim/include -LDFLAGS += -ldkim -lssl -lstdc++ -L/home/tom/libdkim/lib - -Remember to tweak the CFLAGS and LDFLAGS lines to match the -location of the libdomainkeys includes and lib on your system. - -The current experimental implementation supports two independent -functions: - -o Validate incoming DKIM-signed email. -o Sign outgoing email with DKIM. - -The former is implemented in the ACLs for SMTP, the latter as -an extension to the SMTP transport. That means both facilities -are limited to SMTP I/O. - - -1) Validate incoming email - -Incoming messages are fed to the DKIM validation process as they -are received "on the wire". This happens synchronously to Exim's -buffering of the message in the spool. - -You must set "control = dkim_verify" in one of the ACLs preceding -DATA (you will typically use acl_smtp_rcpt), at a point where -non-local, non-relay, non-submission mail is processed. If that -control flag is not set, the message will NOT be verified. - -Example: - -warn log_message = Feeding message to DKIM validator. - control = dk_verify - -You can then check for DKIM signatures in the ACL after data -(acl_smtp_data), using the 'dkim' query-style lookup type. The -query string should be a domain or DKIM identity: - -${lookup dkim{domain.example}} - -Such a lookup will yield one of the following strings: - -unverified: Exim did not (yet) verify the eventual DKIM - signatures in this message. This may happen - if a) You did not use control=dkim_verify - or b) You are using the lookup before - the DATA ACL. - -unsigned: The message does not have a signature from - the specified domain. - -good: The message has a signature from the specified - domain, and it verified successfully. - -bad: The message has a signature from the specified - domain, but it did not verify. - -defer: A temporary DNS problem was encountered while - trying to verify the signature. - - - -2) Sign outgoing email with DKIM - -Outgoing messages are signed just before Exim puts them "on -the wire". The only thing that happens after DKIM signing is -eventual TLS encryption. - -Signing is implemented by setting private options on the SMTP -transport. These options take (expandable) strings as -arguments. - - dkim_domain = <expanded string> [MANDATORY] - - The domain you want to sign with. Should optimally match - the domain in the "From:" header of the message, but - does not necessarily have to. The result of this expanded - option is put into the $dkim_domain expansion variable. - - dkim_selector = <expanded string> [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. - - dkim_private_key = <expanded string> [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 - - o be a valid RSA private key in ASCII armor, including - line breaks. - o start with a slash, in which case it is treated as - a file that contains the private key. - o 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. - - dkim_canon = <expanded string> [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 support using the same canonicalization method for - both headers and body. - - dkim_strict = <expanded string> [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. - - dkim_sign_headers = <expanded string> [OPTIONAL] - - When set, this option must expand to (or be specified as) - a colon-separated list of header names. These headers will - be included in the message signature. When unspecified, - the recommended headers will be used. Currently, these - are: - - from:sender:reply-to:subject:date: - message-id:to:cc:mime-version:content-type: - content-transfer-encoding:content-id: - content-description:resent-date:resent-from: - resent-sender:resent-to:resent-cc:resent-message-id: - in-reply-to:references: - list-id:list-help:list-unsubscribe: - list-subscribe:list-post:list-owner:list-archive - - - - -1. Yahoo DomainKeys support --------------------------------------------------------------- - -DomainKeys (DK) support is built into Exim using the -"libdomainkeys" reference library implementation. It is -available at - -http://domainkeys.sf.net - -You must build this library on your system and compile Exim -against it. To build Exim with DK support, add these lines to -your Local/Makefile: - -EXPERIMENTAL_DOMAINKEYS=yes -CFLAGS += -I/home/tom/exim-cvs/extra/libdomainkeys -LDFLAGS += -ldomainkeys -L/home/tom/exim-cvs/extra/libdomainkeys - -Remember to tweak the CFLAGS and LDFLAGS lines to match the -location of the libdomainkeys includes and lib on your system. - -The current experimental implementation supports two -independent functions: - -o Validate incoming DK-signed email. -o Sign outgoing email with DK. - -The former is implemented in the ACLs for SMTP, the latter as -an extension to the SMTP transport. That means both facilities -are limited to SMTP I/O. - - - -1) Validate incoming email - -Incoming messages are fed to the DK validation process as they -are received "on the wire". This happens synchronously to -Exim's buffering of the message in the spool. - -You must set "control = dk_verify" in one of the ACLs -preceding DATA (you will typically use acl_smtp_rcpt), at a -point where non-local, non-relay, non-submission mail is -processed. If that control flag is not set, the message will -NOT be verified. - -Example: - -warn log_message = Feeding message to DK validator. - control = dk_verify - -You can check for the outcome of the DK check in the ACL after -data (acl_smtp_data), using a number of ACL conditions and/or -expansion variables. - - - -1.1.) DK ACL conditions - - dk_sender_domains = <domain list> - - This condition takes a domainlist as argument and - succeeds if the domain that DK has been verifying for is - found in the list. - - - dk_senders = <address list> - - This condition takes an addresslist as argument and - succeeds if the address that DK has been verifying for - is found in the list. - - - dk_sender_local_parts = <local part list> - - This condition takes a local_part list as argument - and succeeds if the domain that DK has been - verifying for is found in the list. - - - dk_status = <colon separated list of keywords> - - This condition takes a list of keywords as argument, and - succeeds if one of the listed keywords matches the outcome - of the DK check. The available keywords are: - - good DK check succeeded, mail is verified. - bad DK check failed. - no signature Mail is not signed with DK. - no key Public key missing in target domain DNS. - bad format Public key available, but unuseable. - non-participant Target domain states not to participate in DK. - revoked The signing key has been revoked by the domain. - - - dk_policy = <colon separated list of keywords> - - This condition takes a list of keywords as argument, and - succeeds if one of the listed keywords matches the policy - announced by the target domain. The available keywords - are: - - signsall The target domain signs all outgoing email. - testing The target domain is currently testing DK. - - - dk_domain_source = <colon separated list of keywords> - - This condition takes a list of keywords as argument, and - succeeds if one of the listed keywords matches the - location where DK found the sender domain it verified for. - The available keywords are: - - from The domain came from the "From:" header. - sender The domain came from the "Sender:" header. - none DK was unable to find the responsible domain. - - - -1.2.) DK verification expansion variables - - $dk_sender_domain - - Contains the domain that DK has verified for. - - - $dk_sender - - Contains the address that DK has verified for. - - - $dk_sender_local_part - - Contains the local part that DK has verified for. - - - $dk_sender_source - - Contains the "source" of the above three variables, one of - - "from" The address came from the "From:" header. - "sender" The address came from the "Sender:" header. - - When DK was unable to find a valid address, this variable - is "0". - - - $dk_signsall - - Is "1" if the target domain signs all outgoing email, - "0" otherwise. - - - $dk_testing - - Is "1" if the target domain is testing DK, "0" otherwise. - - - $dk_is_signed - - Is "1" if the message is signed, "0" otherwise. - - - $dk_status - - Contains the outcome of the DK check as a string, commonly - used to add a "DomainKey-Status:" header to messages. Will - contain one of: - - good DK check succeeded, mail is verified. - bad DK check failed. - no signature Mail is not signed with DK. - no key Public key missing in target domain DNS. - bad format Public key available, but unuseable. - non-participant Target domain states not to participate in DK. - revoked The signing key has been revoked by the domain. - - - $dk_result - - Contains a human-readable result of the DK check, more - verbose than $dk_status. Useful for logging purposes. - - - -2) Sign outgoing email with DK - -Outgoing messages are signed just before Exim puts them "on -the wire". The only thing that happens after DK signing is -eventual TLS encryption. - -Signing is implemented by setting private options on the SMTP -transport. These options take (expandable) strings as -arguments. The most important variable to use in these -expansions is $dk_domain. It contains the domain that DK wants -to sign for. - - - dk_selector = <expanded string> [MANDATORY] - - This sets the key selector string. You can use the - $dk_domain expansion variable to look up a matching - selector. The result is put in the expansion variable - $dk_selector which should be used in the dk_private_key - option along with $dk_domain. - - - dk_private_key = <expanded string> [MANDATORY] - - This sets the private key to use. You SHOULD use the - $dk_domain and $dk_selector expansion variables to - determine the private key to use. The result can either - - o be a valid RSA private key in ASCII armor, including - line breaks. - o start with a slash, in which case it is treated as - a file that contains the private key. - o 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 dk_strict is set. - - - dk_canon = <expanded string> [OPTIONAL] - - This option sets the canonicalization method used when - signing a message. The DK draft currently supports two - methods: "simple" and "nofws". The option defaults to - "simple" when unset. - - - dk_strict = <expanded string> [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 and should use the $dk_domain and $dk_selector - expansion variables here. - - - dk_domain = <expanded string> [NOT RECOMMENDED] - - This option overrides DKs autodetection of the signing - domain. You should only use this option if you know what - you are doing. The result of the string expansion is also - put in $dk_domain. - - - - -2. Brightmail AntiSpam (BMI) suppport +Brightmail AntiSpam (BMI) suppport -------------------------------------------------------------- Brightmail AntiSpam is a commercial package. Please see @@ -694,7 +294,7 @@ These four steps are explained in more details below. -3. Sender Policy Framework (SPF) support +Sender Policy Framework (SPF) support -------------------------------------------------------------- To learn more about SPF, visit http://www.openspf.org. This @@ -844,7 +444,7 @@ spf_guess = v=spf1 a/16 mx/16 ptr ?all would relax host matching rules to a broader network range. -4. SRS (Sender Rewriting Scheme) Support +SRS (Sender Rewriting Scheme) Support -------------------------------------------------------------- Exiscan currently includes SRS support via Miles Wilton's |