diff options
| -rw-r--r-- | doc/doc-txt/experimental-spec.txt | 267 |
1 files changed, 258 insertions, 9 deletions
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 145fc42da..682b60b24 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -1,14 +1,263 @@ -$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.1 2005/01/11 10:51:15 ph10 Exp $ +$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.2 2005/03/08 15:33:05 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 -order to include the feature. This file contains information -about experimenatal features, all of which are unstable and +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 +order to include the feature. This file contains information +about experimenatal features, all of which are unstable and liable to incompatibile change. -1. Brighmail AntiSpam (BMI) suppport + +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. Brighmail AntiSpam (BMI) suppport -------------------------------------------------------------- Brightmail AntiSpam is a commercial package. Please see @@ -294,7 +543,7 @@ These four steps are explained in more details below. -2. Sender Policy Framework (SPF) support +3. Sender Policy Framework (SPF) support -------------------------------------------------------------- To learn more about SPF, visit http://spf.pobox.com. This @@ -409,7 +658,7 @@ variables. -3. SRS (Sender Rewriting Scheme) Support +4. SRS (Sender Rewriting Scheme) Support -------------------------------------------------------------- Exiscan currently includes SRS support via Miles Wilton's |