X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/8fe685ad2737a1c3e87dd4dfa3970253a03e0ca5..b26eacf1a6a3db6148b97145795d96c9159b91df:/doc/doc-txt/experimental-spec.txt?ds=inline diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 8ca491c1a..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.7 2007/07/27 13:56:24 magnus 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,256 +8,7 @@ about experimenatal features, all of which are unstable and liable to incompatibile change. - -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 @@ -543,10 +294,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. @@ -610,11 +361,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 --------------------- */ @@ -647,6 +399,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 @@ -656,9 +411,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