-$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
-2. Sender Policy Framework (SPF) support
+3. Sender Policy Framework (SPF) support
--------------------------------------------------------------
To learn more about SPF, visit http://spf.pobox.com. This
-3. SRS (Sender Rewriting Scheme) Support
+4. SRS (Sender Rewriting Scheme) Support
--------------------------------------------------------------
Exiscan currently includes SRS support via Miles Wilton's
git://git.exim.org / users / jgh / exim.git / commitdiff