X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/b80649a90444b89433d174d3de4dc1518325882c..9d38e6c3845871c8774cd6494163b1625235080a:/doc/doc-txt/experimental-spec.txt?ds=sidebyside diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 3ad0825d5..1d290c26b 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -1,5 +1,3 @@ -$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.8 2007/09/28 12:58:41 tom Exp $ - From time to time, experimental features may be added to Exim. While a feature is experimental, there will be a build-time option whose name starts "EXPERIMENTAL_" that must be set in @@ -8,391 +6,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 = [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 = [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 = [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 = [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 = [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. - - - - - -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 = - - 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 =
- - 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 = - - 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 = - - 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 = - - 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 = - - 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 = [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 = [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 = [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 = [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 = [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 @@ -678,10 +292,10 @@ 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://spf.pobox.com. This +To learn more about SPF, visit http://www.openspf.org. This document does not explain the SPF fundamentals, you should read and understand the implications of deploying SPF on your system before doing so. @@ -745,11 +359,12 @@ the SPF check, the condition succeeds. If none of the listed strings matches the outcome of the SPF check, the condition fails. -Here is a simple example to fail forgery attempts from domains -that publish SPF records: +Here is an example to fail forgery attempts from domains that +publish SPF records: /* ----------------- -deny message = $sender_host_address is not allowed to send mail from $sender_address_domain +deny message = $sender_host_address is not allowed to send mail from ${if def:sender_address_domain {$sender_address_domain}{$sender_helo_name}}. \ + Please see http://www.openspf.org/Why?scope=${if def:sender_address_domain {mfrom}{helo}};identity=${if def:sender_address_domain {$sender_address}{$sender_helo_name}};ip=$sender_host_address spf = fail --------------------- */ @@ -782,6 +397,9 @@ variables. draft, this header must be added at the top of the header list. Please see section 10 on how you can do this. + Note: in case of "Best-guess" (see below), the convention is + to put this string in a header called X-SPF-Guess: instead. + $spf_result This contains the outcome of the SPF check in string form, one of pass, fail, softfail, none, neutral, err_perm or @@ -791,9 +409,40 @@ variables. This contains a string that can be used in a SMTP response to the calling party. Useful for "fail". +In addition to SPF, you can also perform checks for so-called +"Best-guess". Strictly speaking, "Best-guess" is not standard +SPF, but it is supported by the same framework that enables SPF +capability. Refer to http://www.openspf.org/FAQ/Best_guess_record +for a description of what it means. + +To access this feature, simply use the spf_guess condition in place +of the spf one. For example: + +/* ----------------- +deny message = $sender_host_address doesn't look trustworthy to me + spf_guess = fail +--------------------- */ + +In case you decide to reject messages based on this check, you +should note that although it uses the same framework, "Best-guess" +is NOT SPF, and therefore you should not mention SPF at all in your +reject message. + +When the spf_guess condition has run, it sets up the same expansion +variables as when spf condition is run, described above. + +Additionally, since Best-guess is not standarized, you may redefine +what "Best-guess" means to you by redefining spf_guess variable in +global config. For example, the following: + +/* ----------------- +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