X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/7ef88aa0c4c0608ee54ed2ff90b4b34c518d9bb5..fbc48a247f1014e8c6a0c9772082dbd7e00c6a55:/doc/doc-txt/experimental-spec.txt diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index e9a557aec..56ee10f82 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -292,128 +292,6 @@ These four steps are explained in more details below. -SRS (Sender Rewriting Scheme) Support (using libsrs_alt) --------------------------------------------------------------- -See also below, for an alternative native support implementation. - -Exim 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. - -The following main-section options become available: - srs_config string - srs_hashlength int - srs_hashmin int - srs_maxage int - srs_secrets string - srs_usehash bool - srs_usetimestamp bool - -The redirect router gains these options (all of type string, unset by default): - srs - srs_alias - srs_condition - srs_dbinsert - srs_dbselect - -The following variables become available: - $srs_db_address - $srs_db_key - $srs_orig_recipient - $srs_orig_sender - $srs_recipient - $srs_status - -The predefined feature-macro _HAVE_SRS will be present. -Additional delivery log line elements, tagged with "SRS=" will show the srs sender. -For configuration information see https://github.com/Exim/exim/wiki/SRS . - - - - -SRS (Sender Rewriting Scheme) Support (native) --------------------------------------------------------------- -This is less full-featured than the libsrs_alt version above. - -The Exim build needs to be done with this in Local/Makefile: -EXPERIMENTAL_SRS_NATIVE=yes - -The following are provided: -- an expansion item "srs_encode" - This takes three arguments: - - a site SRS secret - - the return_path - - the pre-forwarding domain - -- an expansion condition "inbound_srs" - This takes two arguments: the local_part to check, and a site SRS secret. - If the secret is zero-length, only the pattern of the local_part is checked. - The $srs_recipient variable is set as a side-effect. - -- an expansion variable $srs_recipient - This gets the original return_path encoded in the SRS'd local_part - -- predefined macros _HAVE_SRS and _HAVE_NATIVE_SRS - -Sample usage: - - #macro - SRS_SECRET = - - #routers - - outbound: - driver = dnslookup - # if outbound, and forwarding has been done, use an alternate transport - domains = ! +my_domains - transport = ${if eq {$local_part@$domain} \ - {$original_local_part@$original_domain} \ - {remote_smtp} {remote_forwarded_smtp}} - - inbound_srs: - driver = redirect - senders = : - domains = +my_domains - # detect inbound bounces which are SRS'd, and decode them - condition = ${if inbound_srs {$local_part} {SRS_SECRET}} - data = $srs_recipient - - inbound_srs_failure: - driver = redirect - senders = : - domains = +my_domains - # detect inbound bounces which look SRS'd but are invalid - condition = ${if inbound_srs {$local_part} {}} - allow_fail - data = :fail: Invalid SRS recipient address - - #... further routers here - - - # transport; should look like the non-forward outbound - # one, plus the max_rcpt and return_path options - remote_forwarded_smtp: - driver = smtp - # modify the envelope from, for mails that we forward - max_rcpt = 1 - return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}} - - - - DCC Support -------------------------------------------------------------- Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ @@ -532,52 +410,6 @@ Rationale: 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. @@ -642,6 +474,9 @@ 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. +[RFC 8617 was published 2019/06. Draft 11 was 2018/01. A review of the +changes has not yet been done] + 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. @@ -650,10 +485,18 @@ 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. +Described in RFC 5598 (section 2.3), this is essentially a set of +mail-handling systems that mail transits that are all under the control +of one organisation. 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. + + +Building with ARC Support +-- +Enable using EXPERIMENTAL_ARC=yes in your Local/Makefile. +You must also have DKIM present (not disabled), and you very likely +want to have SPF enabled. Verification @@ -670,7 +513,9 @@ standard header. 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 . + that claim to be from our own . Eg: + + remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N There are four new variables: @@ -739,62 +584,81 @@ used via the transport in question. +Dovecot authenticator via inet socket +-------------------------------------------------------------- +If Dovecot is configured similar to :- + +service auth { +... +#SASL + inet_listener { + name = exim + port = 12345 + } +... +} + +then an Exim authenticator can be configured :- + + dovecot-plain: + driver = dovecot + public_name = PLAIN + server_socket = dovecot_server_name 12345 + server_tls = true + server_set_id = $auth1 + +If the server_socket does not start with a / it is taken as a hostname (or IP); +and a whitespace-separated port number must be given. + + + + +Logging protocol unusual states +--------------------------------------------------------------- +An extra log_selector, "protocol_detail" has been added in the default build. +The name may change in future, hence the Experimental status. + +Currrently the only effect is to enable logging, under TLS, +of a TCP RST received directly after a QUIT (in server mode). + +Outlook is consistently doing this; not waiting for the SMTP response +to its QUIT, not properly closing the TLS session and not properly closing +the TCP connection. Previously this resulted is an error from SSL_write +being logged. + + + +XCLIENT proxy support +--------------------------------------------------------------- +Per https://www.postfix.org/XCLIENT_README.html + +XCLIENT is an ESMTP extension supporting an inbound proxy. +The only client immplementation known is in Nginx +(https://nginx.org/en/docs/mail/ngx_mail_proxy_module.html) + +If compiled with EXPERIMENTAL_XCLIENT=yes :- + +As a server, Exim will advertise XCLIENT support (conditional on a new option +"hosts_xclient") and service XCLIENT commands with parameters + ADDR + NAME + PORT + LOGIN + DESTADDR + DESTPORT +A fresh HELO/EHLO is required after a succesful XCLIENT, and the usual +values are derived from that (making the HELO and PROTO paramemters redundant). + +An XCLIENT command must give both ADDR and PORT parameters if no previous +XCLIENT has succeeded in the SMTP session. + +After a success: + $proxy_session variable becomes "yes" + $proxy_local_address, $proxy_local_port have the proxy "inside" values + $proxy_external_address, $proxy_external_port have the proxy "outside" values + $sender_host_address, $sender_host_port have the remot client values + -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. - - Since a new hints DB is used, the hints DB maintenance should be updated - to additionally handle "tls". - -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 (OpenSSL: 1hr, and one previous key is used for - overlap; GnuTLS 6hr but does not specify any overlap). - Tickets have limited lifetime (2hr, and new ones issued after 1hr under - OpenSSL. GnuTLS 2hr, appears to not do overlap). - - 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 bits 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 {}{}}. - -Issues: - In a resumed session: - $tls_{in,out}_cipher will have values different to the original (under GnuTLS) - $tls_{in,out}_ocsp will be "not requested" or "no response", and - hosts_require_ocsp will fail --------------------------------------------------------------