X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/65a7d8c381dfb4788ecd5c40a28365acb1f377e1..f9850c6c4851862a66f6ce58bb9ac19ddac7895c:/doc/doc-txt/experimental-spec.txt diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 4175173c3..047440611 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.11 2008/02/12 12:52:51 nm4 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,407 +6,67 @@ about experimenatal features, all of which are unstable and liable to incompatibile change. -0. DKIM support +OCSP Stapling 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. +X509 PKI certificates expire and can be revoked; to handle this, the +clients need some way to determine if a particular certificate, from a +particular Certificate Authority (CA), is still valid. There are three +main ways to do so. -bad: The message has a signature from the specified - domain, but it did not verify. +The simplest way is to serve up a Certificate Revocation List (CRL) with +an ordinary web-server, regenerating the CRL before it expires. The +downside is that clients have to periodically re-download a potentially +huge file from every certificate authority it knows of. -defer: A temporary DNS problem was encountered while - trying to verify the signature. +The way with most moving parts at query time is Online Certificate +Status Protocol (OCSP), where the client verifies the certificate +against an OCSP server run by the CA. This lets the CA track all +usage of the certs. This requires running software with access to the +private key of the CA, to sign the responses to the OCSP queries. OCSP +is based on HTTP and can be proxied accordingly. +The only widespread OCSP server implementation (known to this writer) +comes as part of OpenSSL and aborts on an invalid request, such as +connecting to the port and then disconnecting. This requires +re-entering the passphrase each time some random client does this. +The third way is OCSP Stapling; in this, the server using a certificate +issued by the CA periodically requests an OCSP proof of validity from +the OCSP server, then serves it up inline as part of the TLS +negotiation. This approach adds no extra round trips, does not let the +CA track users, scales well with number of certs issued by the CA and is +resilient to temporary OCSP server failures, as long as the server +starts retrying to fetch an OCSP proof some time before its current +proof expires. The downside is that it requires server support. -2) Sign outgoing email with DKIM +If Exim is built with EXPERIMENTAL_OCSP and it was built with OpenSSL, +then it gains one new option: "tls_ocsp_file". -Outgoing messages are signed just before Exim puts them "on -the wire". The only thing that happens after DKIM signing is -eventual TLS encryption. +The file specified therein is expected to be in DER format, and contain +an OCSP proof. Exim will serve it as part of the TLS handshake. This +option will be re-expanded for SNI, if the tls_certificate option +contains $tls_sni, as per other TLS options. -Signing is implemented by setting private options on the SMTP -transport. These options take (expandable) strings as -arguments. +Exim does not at this time implement any support for fetching a new OCSP +proof. The burden is on the administrator to handle this, outside of +Exim. The file specified should be replaced atomically, so that the +contents are always valid. Exim will expand the "tls_ocsp_file" option +on each connection, so a new file will be handled transparently on the +next connection. - dkim_domain = [MANDATORY] +Exim will check for a valid next update timestamp in the OCSP proof; +if not present, or if the proof has expired, it will be ignored. - 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. +At this point in time, we're gathering feedback on use, to determine if +it's worth adding complexity to the Exim daemon to periodically re-fetch +OCSP files and somehow handling multiple files. There is no client support +for OCSP in Exim, this is feature expected to be used by mail clients. - 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. - - dkim_sign_headers = [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 = - - 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 @@ -694,7 +352,7 @@ 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://www.openspf.org. This @@ -844,7 +502,7 @@ 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 @@ -863,6 +521,139 @@ EXPERIMENTAL_SRS=yes in your Local/Makefile. +DCC Support +-------------------------------------------------------------- + +*) Building exim + +In order to build exim with DCC support add + +EXPERIMENTAL_DCC=yes + +to your Makefile. (Re-)build/install exim. exim -d should show +EXPERIMENTAL_DCC under "Support for". + + +*) Configuration + +In the main section of exim.cf add at least + dccifd_address = /usr/local/dcc/var/dccifd +or + dccifd_address = + +In the DATA ACL you can use the new condition + dcc = * + +After that "$dcc_header" contains the X-DCC-Header. + +Returnvalues are: + fail for overall "R", "G" from dccifd + defer for overall "T" from dccifd + accept for overall "A", "S" from dccifd + +dcc = */defer_ok works as for spamd. + +The "$dcc_result" variable contains the overall result from DCC +answer. There will an X-DCC: header added to the mail. + +Usually you'll use + defer !dcc = * +to greylist with DCC. + +If you set, in the main section, + dcc_direct_add_header = true +then the dcc header will be added "in deep" and if the spool +file was already written it gets removed. This forces Exim to +write it again if needed. This helps to get the DCC Header +through to eg. SpamAssassin. + +If you want to pass even more headers in the middle of the +DATA stage you can set + $acl_m_dcc_add_header +to tell the DCC routines add more information; eg, you might set +this to some results from ClamAV. Be careful. Header syntax is +not checked and is added "as is". + +DBL (Database Logging) +-------------------------------------------------------------- + +This feature allows to write exim internal log information +(not available otherwise) into a database. +Initially implemented is logging of details about successfully +completed remote deliveries, which are needed for reputation +systems, and deferrals caused by a host error. + +In order to use DBL, you must set + +EXPERIMENTAL_DBL=yes + +in your Local/Makefile + +and define the database queries in the runtime config file, to +be executed at end of delivery. + +Additionally, there are 8 more variables, available at end of +delivery: + +dbl_delivery_ip IP of host, which has accepted delivery +dbl_delivery_port Port of remote host which has accepted delivery +dbl_delivery_fqdn FQDN of host, which has accepted delivery +dbl_delivery_local_part local part of address being delivered +dbl_delivery_domain domain part of address being delivered +dbl_delivery_confirmation SMTP confirmation message + +In case of a deferral caused by a host-error: +dbl_defer_errno Error number +dbl_defer_errstr Error string possibly containing more details + + +To log successful deliveries, set the following option in the main +option part of runtime config. + +dbl_delivery_query + +An example might look like: + +dbl_delivery_query = \ +${lookup pgsql {SELECT * FROM record_Delivery( \ + '${quote_pgsql:$sender_address_domain}',\ + '${quote_pgsql:${lc:$sender_address_local_part}}', \ + '${quote_pgsql:$dbl_delivery_domain}', \ + '${quote_pgsql:${lc:$dbl_delivery_local_part}}', \ + '${quote_pgsql:$dbl_delivery_ip}', \ + '${quote_pgsql:${lc:$dbl_delivery_fqdn}}', \ + '${quote_pgsql:$message_exim_id}')}} + + +In order to log host deferrals, add the following option to an SMTP +transport: + +dbl_host_defer_query + +This is a private option of the SMTP transport. It is intended to +log failures of remote hosts. It is executed only when exim has +attempted to deliver a message to a remote host and failed due to +an error which doesn't seem to be related to the individual +message, sender, or recipient address. +See section 45.2 of the exim documentation for more details on how +this is determined. + +Example: + +dbl_host_defer_query = \ +${lookup mysql {insert into delivlog set \ + msgid = '${quote_mysql:$message_exim_id}', \ + senderlp = '${quote_mysql:${lc:$sender_address_local_part}}', \ + senderdom = '${quote_mysql:$sender_address_domain}', \ + delivlp = '${quote_mysql:${lc:$dbl_delivery_local_part}}', \ + delivdom = '${quote_mysql:$dbl_delivery_domain}', \ + delivip = '${quote_mysql:$dbl_delivery_ip}', \ + delivport = '${quote_mysql:$dbl_delivery_port}', \ + delivfqdn = '${quote_mysql:$dbl_delivery_fqdn}', \ + deliverrno = '${quote_mysql:$dbl_defer_errno}', \ + deliverrstr = '${quote_mysql:$dbl_defer_errstr}' \ + }} + -------------------------------------------------------------- End of file --------------------------------------------------------------