X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/f413481de14352e6a8e07315459f01b45cac50e8..43e2db44c657b07340368eae5dd05e51eab829fb:/doc/doc-txt/experimental-spec.txt diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 15fd247ae..feecb3375 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -1,414 +1,12 @@ -$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.10 2008/01/16 09:36:19 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 -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 = [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 = [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] +about experimental features, all of which are unstable and +liable to incompatible change. - 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) support -------------------------------------------------------------- Brightmail AntiSpam is a commercial package. Please see @@ -444,7 +42,7 @@ These four steps are explained in more details below. 1) Adding support for BMI at compile time To compile with BMI support, you need to link Exim against - the Brighmail client SDK, consisting of a library + the Brightmail client SDK, consisting of a library (libbmiclient_single.so) and a header file (bmi_api.h). You'll also need to explicitly set a flag in the Makefile to include BMI support in the Exim binary. Both can be achieved @@ -694,139 +292,708 @@ These four steps are explained in more details below. -3. Sender Policy Framework (SPF) support +SRS (Sender Rewriting Scheme) Support -------------------------------------------------------------- -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. - -SPF support is added via the libspf2 library. Visit - - http://www.libspf2.org/ - -to obtain a copy, then compile and install it. By default, -this will put headers in /usr/local/include and the static -library in /usr/local/lib. - -To compile Exim with SPF support, set these additional flags in -Local/Makefile: - -EXPERIMENTAL_SPF=yes -CFLAGS=-DSPF -I/usr/local/include -EXTRALIBS_EXIM=-L/usr/local/lib -lspf2 - -This assumes that the libspf2 files are installed in -their default locations. - -You can now run SPF checks in incoming SMTP by using the "spf" -ACL condition in either the MAIL, RCPT or DATA ACLs. When -using it in the RCPT ACL, you can make the checks dependend on -the RCPT address (or domain), so you can check SPF records -only for certain target domains. This gives you the -possibility to opt-out certain customers that do not want -their mail to be subject to SPF checking. - -The spf condition takes a list of strings on its right-hand -side. These strings describe the outcome of the SPF check for -which the spf condition should succeed. Valid strings are: - - o pass The SPF check passed, the sending host - is positively verified by SPF. - o fail The SPF check failed, the sending host - is NOT allowed to send mail for the domain - in the envelope-from address. - o softfail The SPF check failed, but the queried - domain can't absolutely confirm that this - is a forgery. - o none The queried domain does not publish SPF - records. - o neutral The SPF check returned a "neutral" state. - This means the queried domain has published - a SPF record, but wants to allow outside - servers to send mail under its domain as well. - o err_perm This indicates a syntax error in the SPF - record of the queried domain. This should be - treated like "none". - o err_temp This indicates a temporary error during all - processing, including Exim's SPF processing. - You may defer messages when this occurs. - -You can prefix each string with an exclamation mark to invert -is meaning, for example "!fail" will match all results but -"fail". The string list is evaluated left-to-right, in a -short-circuit fashion. When a string matches the outcome of -the SPF check, the condition succeeds. If none of the listed -strings matches the outcome of the SPF check, the condition -fails. +Exiscan currently includes SRS support via Miles Wilton's +libsrs_alt library. The current version of the supported +library is 0.5, there are reports of 1.0 working. + +In order to use SRS, you must get a copy of libsrs_alt from + +https://opsec.eu/src/srs/ + +(not the original source, which has disappeared.) + +Unpack the tarball, then refer to MTAs/README.EXIM +to proceed. You need to set + +EXPERIMENTAL_SRS=yes + +in your Local/Makefile. + + + +DCC Support +-------------------------------------------------------------- +Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ + +*) 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 = * -Here is an example to fail forgery attempts from domains that -publish SPF records: +After that "$dcc_header" contains the X-DCC-Header. -/* ----------------- -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 ---------------------- */ +Return values are: + fail for overall "R", "G" from dccifd + defer for overall "T" from dccifd + accept for overall "A", "S" from dccifd -You can also give special treatment to specific domains: +dcc = */defer_ok works as for spamd. -/* ----------------- -deny message = AOL sender, but not from AOL-approved relay. - sender_domains = aol.com - spf = fail:neutral ---------------------- */ +The "$dcc_result" variable contains the overall result from DCC +answer. There will an X-DCC: header added to the mail. -Explanation: AOL publishes SPF records, but is liberal and -still allows non-approved relays to send mail from aol.com. -This will result in a "neutral" state, while mail from genuine -AOL servers will result in "pass". The example above takes -this into account and treats "neutral" like "fail", but only -for aol.com. Please note that this violates the SPF draft. +Usually you'll use + defer !dcc = * +to greylist with DCC. -When the spf condition has run, it sets up several expansion -variables. +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. - $spf_header_comment - This contains a human-readable string describing the outcome - of the SPF check. You can add it to a custom header or use - it for logging purposes. +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 to 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". - $spf_received - This contains a complete Received-SPF: header that can be - added to the message. Please note that according to the SPF - draft, this header must be added at the top of the header - list. Please see section 10 on how you can do this. +In case you've troubles with sites sending the same queue items from several +hosts and fail to get through greylisting you can use +$acl_m_dcc_override_client_ip - $spf_result - This contains the outcome of the SPF check in string form, - one of pass, fail, softfail, none, neutral, err_perm or - err_temp. +Setting $acl_m_dcc_override_client_ip to an IP address overrides the default +of $sender_host_address. eg. use the following ACL in DATA stage: - $spf_smtp_comment - This contains a string that can be used in a SMTP response - to the calling party. Useful for "fail". + warn set acl_m_dcc_override_client_ip = \ + ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}} + condition = ${if def:acl_m_dcc_override_client_ip} + log_message = dbg: acl_m_dcc_override_client_ip set to \ + $acl_m_dcc_override_client_ip +Then set something like +# cat /etc/mail/multipleip_sites +mout-xforward.gmx.net 82.165.159.12 +mout.gmx.net 212.227.15.16 +Use a reasonable IP. eg. one the sending cluster actually uses. -4. SRS (Sender Rewriting Scheme) Support + + +DMARC Support -------------------------------------------------------------- -Exiscan currently includes SRS support via Miles Wilton's -libsrs_alt library. The current version of the supported -library is 0.5. +DMARC combines feedback from SPF, DKIM, and header From: in order +to attempt to provide better indicators of the authenticity of an +email. This document does not explain the fundamentals, you +should read and understand how it works by visiting the website at +http://www.dmarc.org/. + +DMARC support is added via the libopendmarc library. Visit: + + http://sourceforge.net/projects/opendmarc/ + +to obtain a copy, or find it in your favorite rpm package +repository. If building from source, this description assumes +that headers will be in /usr/local/include, and that the libraries +are in /usr/local/lib. + +1. To compile Exim with DMARC support, you must first enable SPF. +Please read the Local/Makefile comments on enabling the SUPPORT_SPF +feature. You must also have DKIM support, so you cannot set the +DISABLE_DKIM feature. Once both of those conditions have been met +you can enable DMARC in Local/Makefile: + +EXPERIMENTAL_DMARC=yes +LDFLAGS += -lopendmarc +# CFLAGS += -I/usr/local/include +# LDFLAGS += -L/usr/local/lib + +The first line sets the feature to include the correct code, and +the second line says to link the libopendmarc libraries into the +exim binary. The commented out lines should be uncommented if you +built opendmarc from source and installed in the default location. +Adjust the paths if you installed them elsewhere, but you do not +need to uncomment them if an rpm (or you) installed them in the +package controlled locations (/usr/include and /usr/lib). + + +2. Use the following global options to configure DMARC: + +Required: +dmarc_tld_file Defines the location of a text file of valid + top level domains the opendmarc library uses + during domain parsing. Maintained by Mozilla, + the most current version can be downloaded + from a link at http://publicsuffix.org/list/. + See also util/renew-opendmarc-tlds.sh script. + The default for the option is currently + /etc/exim/opendmarc.tlds + +Optional: +dmarc_history_file Defines the location of a file to log results + of dmarc verification on inbound emails. The + contents are importable by the opendmarc tools + which will manage the data, send out DMARC + reports, and expire the data. Make sure the + directory of this file is writable by the user + exim runs as. + +dmarc_forensic_sender Alternate email address to use when sending a + forensic report detailing alignment failures + if a sender domain's dmarc record specifies it + and you have configured Exim to send them. + + If set, this is expanded and used for the + From: header line; the address is extracted + from it and used for the envelope from. + If not set, the From: header is expanded from + the dsn_from option, and <> is used for the + envelope from. + + Default: unset. + + +3. By default, the DMARC processing will run for any remote, +non-authenticated user. It makes sense to only verify DMARC +status of messages coming from remote, untrusted sources. You can +use standard conditions such as hosts, senders, etc, to decide that +DMARC verification should *not* be performed for them and disable +DMARC with a control setting: + + control = dmarc_disable_verify + +A DMARC record can also specify a "forensic address", which gives +exim an email address to submit reports about failed alignment. +Exim does not do this by default because in certain conditions it +results in unintended information leakage (what lists a user might +be subscribed to, etc). You must configure exim to submit forensic +reports to the owner of the domain. If the DMARC record contains a +forensic address and you specify the control statement below, then +exim will send these forensic emails. It's also advised that you +configure a dmarc_forensic_sender because the default sender address +construction might be inadequate. + + control = dmarc_enable_forensic + +(AGAIN: You can choose not to send these forensic reports by simply +not putting the dmarc_enable_forensic control line at any point in +your exim config. If you don't tell it to send them, it will not +send them.) + +There are no options to either control. Both must appear before +the DATA acl. + + +4. You can now run DMARC checks in incoming SMTP by using the +"dmarc_status" ACL condition in the DATA ACL. You are required to +call the spf condition first in the ACLs, then the "dmarc_status" +condition. Putting this condition in the ACLs is required in order +for a DMARC check to actually occur. All of the variables are set +up before the DATA ACL, but there is no actual DMARC check that +occurs until a "dmarc_status" condition is encountered in the ACLs. + +The dmarc_status condition takes a list of strings on its +right-hand side. These strings describe recommended action based +on the DMARC check. To understand what the policy recommendations +mean, refer to the DMARC website above. Valid strings are: + + o accept The DMARC check passed and the library recommends + accepting the email. + o reject The DMARC check failed and the library recommends + rejecting the email. + o quarantine The DMARC check failed and the library recommends + keeping it for further inspection. + o none The DMARC check passed and the library recommends + no specific action, neutral. + o norecord No policy section in the DMARC record for this + sender domain. + o nofrom Unable to determine the domain of the sender. + o temperror Library error or dns error. + o off The DMARC check was disabled for this email. + +You can prefix each string with an exclamation mark to invert its +meaning, for example "!accept" will match all results but +"accept". The string list is evaluated left-to-right in a +short-circuit fashion. When a string matches the outcome of the +DMARC check, the condition succeeds. If none of the listed +strings matches the outcome of the DMARC check, the condition +fails. -In order to use SRS, you must get a copy of libsrs_alt from +Of course, you can also use any other lookup method that Exim +supports, including LDAP, Postgres, MySQL, etc, as long as the +result is a list of colon-separated strings. -http://srs.mirtol.com/ +Performing the check sets up information used by the +${authresults } expansion item. -Unpack the tarball, then refer to MTAs/README.EXIM -to proceed. You need to set +Several expansion variables are set before the DATA ACL is +processed, and you can use them in this ACL. The following +expansion variables are available: -EXPERIMENTAL_SRS=yes + o $dmarc_status + This is a one word status indicating what the DMARC library + thinks of the email. It is a combination of the results of + DMARC record lookup and the SPF/DKIM/DMARC processing results + (if a DMARC record was found). The actual policy declared + in the DMARC record is in a separate expansion variable. -in your Local/Makefile. + o $dmarc_status_text + This is a slightly longer, human readable status. + + o $dmarc_used_domain + This is the domain which DMARC used to look up the DMARC + policy record. + + o $dmarc_domain_policy + This is the policy declared in the DMARC record. Valid values + are "none", "reject" and "quarantine". It is blank when there + is any error, including no DMARC record. + +A now-redundant variable $dmarc_ar_header has now been withdrawn. +Use the ${authresults } expansion instead. + + +5. How to enable DMARC advanced operation: +By default, Exim's DMARC configuration is intended to be +non-intrusive and conservative. To facilitate this, Exim will not +create any type of logging files without explicit configuration by +you, the admin. Nor will Exim send out any emails/reports about +DMARC issues without explicit configuration by you, the admin (other +than typical bounce messages that may come about due to ACL +processing or failure delivery issues). + +In order to log statistics suitable to be imported by the opendmarc +tools, you need to: +a. Configure the global setting dmarc_history_file. +b. Configure cron jobs to call the appropriate opendmarc history + import scripts and truncating the dmarc_history_file. + +In order to send forensic reports, you need to: +a. Configure the global setting dmarc_forensic_sender. +b. Configure, somewhere before the DATA ACL, the control option to + enable sending DMARC forensic reports. + + +6. Example usage: +(RCPT ACL) + warn domains = +local_domains + hosts = +local_hosts + control = dmarc_disable_verify + + warn !domains = +screwed_up_dmarc_records + control = dmarc_enable_forensic + + warn condition = (lookup if destined to mailing list) + set acl_m_mailing_list = 1 + +(DATA ACL) + warn dmarc_status = accept : none : off + !authenticated = * + log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain + + warn dmarc_status = !accept + !authenticated = * + log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain + + warn dmarc_status = quarantine + !authenticated = * + set $acl_m_quarantine = 1 + # Do something in a transport with this flag variable + + deny condition = ${if eq{$dmarc_domain_policy}{reject}} + condition = ${if eq{$acl_m_mailing_list}{1}} + message = Messages from $dmarc_used_domain break mailing lists + + deny dmarc_status = reject + !authenticated = * + message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT + + warn add_header = :at_start:${authresults {$primary_hostname}} + + + +DSN extra information +--------------------- +If compiled with EXPERIMENTAL_DSN_INFO extra information will be added +to DSN fail messages ("bounces"), when available. The intent is to aid +tracing of specific failing messages, when presented with a "bounce" +complaint and needing to search logs. + + +The remote MTA IP address, with port number if nonstandard. +Example: + Remote-MTA: X-ip; [127.0.0.1]:587 +Rationale: + Several addresses may correspond to the (already available) + dns name for the remote MTA. + +The remote MTA connect-time greeting. +Example: + X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000 +Rationale: + This string sometimes presents the remote MTA's idea of its + own name, and sometimes identifies the MTA software. + +The remote MTA response to HELO or EHLO. +Example: + X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1] +Limitations: + Only the first line of a multiline response is recorded. +Rationale: + This string sometimes presents the remote MTA's view of + the peer IP connecting to it. + +The reporting MTA detailed diagnostic. +Example: + X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:: 550 hard error +Rationale: + This string sometimes give extra information over the + existing (already available) Diagnostic-Code field. + + +Note that non-RFC-documented field names and data types are used. + + +LMDB Lookup support +------------------- +LMDB is an ultra-fast, ultra-compact, crash-proof key-value embedded data store. +It is modeled loosely on the BerkeleyDB API. You should read about the feature +set as well as operation modes at https://symas.com/products/lightning-memory-mapped-database/ + +LMDB single key lookup support is provided by linking to the LMDB C library. +The current implementation does not support writing to the LMDB database. + +Visit https://github.com/LMDB/lmdb to download the library or find it in your +operating systems package repository. + +If building from source, this description assumes that headers will be in +/usr/local/include, and that the libraries are in /usr/local/lib. + +1. In order to build exim with LMDB lookup support add or uncomment + +EXPERIMENTAL_LMDB=yes + +to your Local/Makefile. (Re-)build/install exim. exim -d should show +Experimental_LMDB in the line "Support for:". + +EXPERIMENTAL_LMDB=yes +LDFLAGS += -llmdb +# CFLAGS += -I/usr/local/include +# LDFLAGS += -L/usr/local/lib + +The first line sets the feature to include the correct code, and +the second line says to link the LMDB libraries into the +exim binary. The commented out lines should be uncommented if you +built LMDB from source and installed in the default location. +Adjust the paths if you installed them elsewhere, but you do not +need to uncomment them if an rpm (or you) installed them in the +package controlled locations (/usr/include and /usr/lib). + +2. Create your LMDB files, you can use the mdb_load utility which is +part of the LMDB distribution our your favourite language bindings. + +3. Add the single key lookups to your exim.conf file, example lookups +are below. + +${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}} +${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}fail} +${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}} + + +Queuefile transport +------------------- +Queuefile is a pseudo transport which does not perform final delivery. +It simply copies the exim spool files out of the spool directory into +an external directory retaining the exim spool format. + +The spool files can then be processed by external processes and then +requeued into exim spool directories for final delivery. +However, note carefully the warnings in the main documentation on +qpool file formats. + +The motivation/inspiration for the transport is to allow external +processes to access email queued by exim and have access to all the +information which would not be available if the messages were delivered +to the process in the standard email formats. + +The mailscanner package is one of the processes that can take advantage +of this transport to filter email. + +The transport can be used in the same way as the other existing transports, +i.e by configuring a router to route mail to a transport configured with +the queuefile driver. + +The transport only takes one option: + +* directory - This is used to specify the directory messages should be +copied to. Expanded. + +The generic transport options (body_only, current_directory, disable_logging, +debug_print, delivery_date_add, envelope_to_add, event_action, group, +headers_add, headers_only, headers_remove, headers_rewrite, home_directory, +initgroups, max_parallel, message_size_limit, rcpt_include_affixes, +retry_use_local_part, return_path, return_path_add, shadow_condition, +shadow_transport, transport_filter, transport_filter_timeout, user) are +ignored. + +Sample configuration: + +(Router) + +scan: + driver = accept + transport = scan + +(Transport) + +scan: + driver = queuefile + directory = /var/spool/baruwa-scanner/input + + +In order to build exim with Queuefile transport support add or uncomment + +EXPERIMENTAL_QUEUEFILE=yes + +to your Local/Makefile. (Re-)build/install exim. exim -d should show +Experimental_QUEUEFILE in the line "Support for:". + + +ARC support +----------- +Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11 +Note that this is not an RFC yet, so may change. + +ARC is intended to support the utility of SPF and DKIM in the presence of +intermediaries in the transmission path - forwarders and mailinglists - +by establishing a cryptographically-signed chain in headers. + +Normally one would only bother doing ARC-signing when functioning as +an intermediary. One might do verify for local destinations. + +ARC uses the notion of a "ADministrative Management Domain" (ADMD). +Described in RFC 5598 (section 2.3), this is essentially the set of +mail-handling systems that the mail transits. A label should be chosen to +identify the ADMD. Messages should be ARC-verified on entry to the ADMD, +and ARC-signed on exit from it. + + +Verification +-- +An ACL condition is provided to perform the "verifier actions" detailed +in section 6 of the above specification. It may be called from the DATA ACL +and succeeds if the result matches any of a given list. +It also records the highest ARC instance number (the chain size) +and verification result for later use in creating an Authentication-Results: +standard header. + + verify = arc/ none:fail:pass + + add_header = :at_start:${authresults {}} + + Note that it would be wise to strip incoming messages of A-R headers + that claim to be from our own . + +There are four new variables: + + $arc_state One of pass, fail, none + $arc_state_reason (if fail, why) + $arc_domains colon-sep list of ARC chain domains, in chain order. + problematic elements may have empty list elements + $arc_oldest_pass lowest passing instance number of chain + +Example: + logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \ + {} \ + {${if = {$arc_oldest_pass} \ + {${extract {i}{${extract {1}{;}{$item}}}}} \ + {$item} {$value}}} \ + }> + +Receive log lines for an ARC pass will be tagged "ARC". + + +Signing +-- +arc_sign = : : [ : ] +An option on the smtp transport, which constructs and prepends to the message +an ARC set of headers. The textually-first Authentication-Results: header +is used as a basis (you must have added one on entry to the ADMD). +Expanded as a whole; if unset, empty or forced-failure then no signing is done. +If it is set, all of the first three elements must be non-empty. + +The fourth element is optional, and if present consists of a comma-separated list +of options. The options implemented are + + timestamps Add a t= tag to the generated AMS and AS headers, with the + current time. + expire[=] Add an x= tag to the generated AMS header, with an expiry time. + If the value is an plain number it is used unchanged. + If it starts with a '+' then the following number is added + to the current time, as an offset in seconds. + If a value is not given it defaults to a one month offset. + +[As of writing, gmail insist that a t= tag on the AS is mandatory] + +Caveats: + * There must be an Authentication-Results header, presumably added by an ACL + while receiving the message, for the same ADMD, for arc_sign to succeed. + This requires careful coordination between inbound and outbound logic. + + Only one A-R header is taken account of. This is a limitation versus + the ARC spec (which says that all A-R headers from within the ADMD must + be used). + + * If passing a message to another system, such as a mailing-list manager + (MLM), between receipt and sending, be wary of manipulations to headers made + by the MLM. + + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve + deliverability in a pre-ARC world, but that option also renames the + Authentication-Results header, which breaks signing. + + * Even if you use multiple DKIM keys for different domains, the ARC concept + should try to stick to one ADMD, so pick a primary domain and use that for + AR headers and outbound signing. + +Signing is not compatible with cutthrough delivery; any (before expansion) +value set for the option will result in cutthrough delivery not being +used via the transport in question. + + + + +Early pipelining support +------------------------ +Ref: https://datatracker.ietf.org/doc/draft-harris-early-pipe/ + +If compiled with EXPERIMENTAL_PIPE_CONNECT support is included for this feature. +The server advertises the feature in its EHLO response, currently using the name +"X_PIPE_CONNECT" (this will change, some time in the future). +A client may cache this information, along with the rest of the EHLO response, +and use it for later connections. Those later ones can send esmtp commands before +a banner is received. + +Up to 1.5 roundtrip times can be taken out of cleartext connections, 2.5 on +STARTTLS connections. + +In combination with the traditional PIPELINING feature the following example +sequences are possible (among others): + +(client) (server) + +EHLO,MAIL,RCPT,DATA -> + <- banner,EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead +message-data -> +------ + +EHLO,MAIL,RCPT,BDAT -> + <- banner,EHLO-resp,MAIL-ack,RCPT-ack +message-data -> +------ + +EHLO,STARTTLS -> + <- banner,EHLO-resp,TLS-goahead +TLS1.2-client-hello -> + <- TLS-server-hello,cert,hello-done +client-Kex,change-cipher,finished -> + <- change-cipher,finished +EHLO,MAIL,RCPT,DATA -> + <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead + +------ +(tls-on-connect) +TLS1.2-client-hello -> + <- TLS-server-hello,cert,hello-done +client-Kex,change-cipher,finished -> + <- change-cipher,finshed + <- banner +EHLO,MAIL,RCPT,DATA -> + <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead + +Where the initial client packet is SMTP, it can combine with the TCP Fast Open +feature and be sent in the TCP SYN. + + +A main-section option "pipelining_connect_advertise_hosts" (default: *) +and an smtp transport option "hosts_pipe_connect" (default: unset) +control the feature. + +If the "pipelining" log_selector is enabled, the "L" field in server <= +log lines has a period appended if the feature was advertised but not used; +or has an asterisk appended if the feature was used. In client => lines +the "L" field has an asterisk appended if the feature was used. + +The "retry_data_expire" option controls cache invalidation. +Entries are also rewritten (or cleared) if the adverised features +change. + + +NOTE: since the EHLO command must be constructed before the connection is +made it cannot depend on the interface IP address that will be used. +Transport configurations should be checked for this. An example avoidance: + + helo_data = ${if def:sending_ip_address \ + {${lookup dnsdb{>! ptr=$sending_ip_address} \ + {${sg{$value} {^([^!]*).*\$} {\$1}}} fail}} \ + {$primary_hostname}} + + + + +TLS Session Resumption +---------------------- +TLS Session Resumption for TLS 1.2 and TLS 1.3 connections can be used (defined +in RFC 5077 for 1.2). The support for this can be included by building with +EXPERIMENTAL_TLS_RESUME defined. This requires GnuTLS 3.6.3 or OpenSSL 1.1.1 +(or later). + +Session resumption (this is the "stateless" variant) involves the server sending +a "session ticket" to the client on one connection, which can be stored by the +client and used for a later session. The ticket contains sufficient state for +the server to reconstruct the TLS session, avoiding some expensive crypto +calculation and one full packet roundtrip time. + +Operational cost/benefit: + The extra data being transmitted costs a minor amount, and the client has +extra costs in storing and retrieving the data. + +In the Exim/Gnutls implementation the extra cost on an initial connection +which is TLS1.2 over a loopback path is about 6ms on 2017-laptop class hardware. +The saved cost on a subsequent connection is about 4ms; three or more +connections become a net win. On longer network paths, two or more +connections will have an average lower startup time thanks to the one +saved packet roundtrip. TLS1.3 will save the crypto cpu costs but not any +packet roundtrips. + +Security aspects: + The session ticket is encrypted, but is obviously an additional security +vulnarability surface. An attacker able to decrypt it would have access +all connections using the resumed session. +The session ticket encryption key is not committed to storage by the server +and is rotated regularly. Tickets have limited lifetime. + +There is a question-mark over the security of the Diffie-Helman parameters +used for session negotiation. TBD. q-value; cf bug 1895 + +Observability: + New log_selector "tls_resumption", appends an asterisk to the tls_cipher "X=" +element. + +Variables $tls_{in,out}_resumption have bit 0-4 indicating respectively +support built, client requested ticket, client offered session, +server issued ticket, resume used. A suitable decode list is provided +in the builtin macro _RESUME_DECODE for ${listextract {}{}}. --------------------------------------------------------------