-$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.10 2008/01/16 09:36:19 tom 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
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
-3. Sender Policy Framework (SPF) support
+Sender Policy Framework (SPF) support
--------------------------------------------------------------
To learn more about SPF, visit http://www.openspf.org. This
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
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
git://git.exim.org / exim.git / blobdiff