X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/12fa0e31a7141100d816dcd6d4eba165fdfa8df7..b6effdcc2df0529ca646743a2655ffb5228607df:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 738ed332f..1d5c0fa38 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -52,7 +52,7 @@ .set I "    " .macro copyyear -2017 +2018 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -448,12 +448,11 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section .section "FTP and web sites" "SECID2" .cindex "web site" .cindex "FTP site" -The primary site for Exim source distributions is currently the University of -Cambridge's FTP site, whose contents are described in &'Where to find the Exim -distribution'& below. In addition, there is a web site and an FTP site at -&%exim.org%&. These are now also hosted at the University of Cambridge. The -&%exim.org%& site was previously hosted for a number of years by Energis -Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. +.new +The primary site for Exim source distributions is the &%exim.org%& FTP site, +available over HTTPS, HTTP and FTP. These services, and the &%exim.org%& +website, are hosted at the University of Cambridge. +.wen .cindex "wiki" .cindex "FAQ" @@ -462,12 +461,18 @@ differently formatted versions of the documentation. A recent addition to the online information is the Exim wiki (&url(http://wiki.exim.org)), which contains what used to be a separate FAQ, as well as various other examples, tips, and know-how that have been contributed by Exim users. +.new +The wiki site should always redirect to the correct place, which is currently +provided by GitHub, and is open to editing by anyone with a GitHub account. +.wen .cindex Bugzilla An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use this to report bugs, and also to add items to the wish list. Please search first to check that you are not duplicating a previous entry. - +.new +Please do not ask for configuration help in the bug-tracker. +.wen .section "Mailing lists" "SECID3" @@ -505,26 +510,45 @@ message to the &'exim-dev'& mailing list and have it discussed. .section "Where to find the Exim distribution" "SECTavail" .cindex "FTP site" +.cindex "HTTPS download site" .cindex "distribution" "ftp site" -The master ftp site for the Exim distribution is +.cindex "distribution" "https site" +.new +The master distribution site for the Exim distribution is .display -&*ftp://ftp.exim.org/pub/exim*& +&*https://downloads.exim.org/*& .endd -The file references that follow are relative to the &_exim_& directories at -these sites. There are now quite a number of independent mirror sites around +The service is available over HTTPS, HTTP and FTP. +We encourage people to migrate to HTTPS. + +The content served at &'https://downloads.exim.org/'& is identical to the +content served at &'https://ftp.exim.org/pub/exim'& and +&'ftp://ftp.exim.org/pub/exim'&. + +If accessing via a hostname containing &'ftp'&, then the file references that +follow are relative to the &_exim_& directories at these sites. +If accessing via the hostname &'downloads'& then the subdirectories described +here are top-level directories. +.wen + +There are now quite a number of independent mirror sites around the world. Those that I know about are listed in the file called &_Mirrors_&. -Within the &_exim_& directory there are subdirectories called &_exim3_& (for +Within the top exim directory there are subdirectories called &_exim3_& (for previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 distributions), and &_Testing_& for testing versions. In the &_exim4_& subdirectory, the current release can always be found in files called .display +&_exim-n.nn.tar.xz_& &_exim-n.nn.tar.gz_& &_exim-n.nn.tar.bz2_& .endd -where &'n.nn'& is the highest such version number in the directory. The two +where &'n.nn'& is the highest such version number in the directory. The three files contain identical data; the only difference is the type of compression. -The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. +.new +The &_.xz_& file is usually the smallest, while the &_.gz_& file is the +most portable to old systems. +.wen .cindex "distribution" "signing details" .cindex "distribution" "public key" @@ -538,17 +562,16 @@ PGP key, a version of which can be found in the release directory in the file &_nigel-pubkey.asc_&. All keys used will be available in public keyserver pools, such as &'pool.sks-keyservers.net'&. -At time of last update, releases were being made by Phil Pennock and signed with -key &'0x403043153903637F'&, although that key is expected to be replaced in 2013. -A trust path from Nigel's key to Phil's can be observed at -&url(https://www.security.spodhuis.org/exim-trustpath). - -Releases have also been authorized to be performed by Todd Lyons who signs with -key &'0xC4F4F94804D29EBA'&. A direct trust path exists between previous RE Phil -Pennock and Todd Lyons through a common associate. +.new +At time of last update, releases were being made by Jeremy Harris and signed +with key &'0xBCE58C8CE41F32DF'&. Other recent keys used for signing are those +of Heiko Schlittermann, &'0x26101B62F69376CE'&, +and of Phil Pennock, &'0x4D1E900E14C1CC04'&. +.wen The signatures for the tar bundles are in: .display +&_exim-n.nn.tar.xz.asc_& &_exim-n.nn.tar.gz.asc_& &_exim-n.nn.tar.bz2.asc_& .endd @@ -566,8 +589,10 @@ inside the &_exim4_& directory of the FTP site: &_exim-postscript-n.nn.tar.gz_& &_exim-texinfo-n.nn.tar.gz_& .endd +.new These tar files contain only the &_doc_& directory, not the complete -distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. +distribution, and are also available in &_.bz2_& and &_.xz_& forms. +.wen .section "Limitations" "SECID6" @@ -7839,6 +7864,19 @@ ${lookup redis{set keyname ${quote_redis:objvalue plus}}} ${lookup redis{get keyname}} .endd +.new +As of release 4.91, "lightweight" support for Redis Cluster is available. +Requires &%redis_servers%& list to contain all the servers in the cluster, all +of which must be reachable from the running exim instance. If the cluster has +master/slave replication, the list must contain all the master and slave +servers. + +When the Redis Cluster returns a "MOVED" response to a query, exim does not +immediately follow the redirection but treats the response as a DEFER, moving on +to the next server in the &%redis_servers%& list until the correct server is +reached. +.wen + .ecindex IIDfidalo1 .ecindex IIDfidalo2 @@ -9141,6 +9179,7 @@ If the ACL returns defer the result is a forced-fail. Otherwise the expansion f .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&" .cindex authentication "results header" .cindex headers "authentication-results:" +.cindex authentication "expansion item" This item returns a string suitable for insertion as an &'Authentication-Results"'& header line. @@ -9159,6 +9198,7 @@ Example use (as an ACL modifier): .code add_header = :at_start:${authresults {$primary_hostname}} .endd +This is safe even if no authentication reselts are available. .wen @@ -11580,10 +11620,15 @@ preserve some of the authentication information in the variable user/password authenticator configuration might preserve the user name for use in the routers. Note that this is not the same information that is saved in &$sender_host_authenticated$&. + When a message is submitted locally (that is, not over a TCP connection) the value of &$authenticated_id$& is normally the login name of the calling process. However, a trusted user can override this by means of the &%-oMai%& command line option. +.new +This second case also sets up inforamtion used by the +&$authresults$& expansion item. +.wen .vitem &$authenticated_fail_id$& .cindex "authentication" "fail" "id" @@ -11923,6 +11968,13 @@ lookup succeeds, but there is a lookup problem such as a timeout when checking the result, the name is not accepted, and &$host_lookup_deferred$& is set to &"1"&. See also &$sender_host_name$&. +.new +.cindex authentication "expansion item" +Performing these checks sets up information used by the +&$authresults$& expansion item. +.wen + + .vitem &$host_lookup_failed$& .vindex "&$host_lookup_failed$&" See &$host_lookup_deferred$&. @@ -12878,6 +12930,7 @@ is compiled with the content-scanning extension. For details, see section .vitem &$spf_header_comment$& &&& &$spf_received$& &&& &$spf_result$& &&& + &$spf_result_guessed$& &&& &$spf_smtp_comment$& These variables are only available if Exim is built with SPF support. For details see section &<>&. @@ -23913,6 +23966,24 @@ For testing purposes, this value can be overridden by the &%-oB%& command line option. +.new +.option dane_require_tls_ciphers smtp string&!! unset +.cindex "TLS" "requiring specific ciphers for DANE" +.cindex "cipher" "requiring specific" +.cindex DANE "TLS ciphers" +This option may be used to override &%tls_require_ciphers%& for connections +where DANE has been determined to be in effect. +If not set, then &%tls_require_ciphers%& will be used. +Normal SMTP delivery is not able to make strong demands of TLS cipher +configuration, because delivery will fall back to plaintext. Once DANE has +been determined to be in effect, there is no plaintext fallback and making the +TLS cipherlist configuration stronger will increase security, rather than +counter-intuitively decreasing it. +If the option expands to be empty or is forced to fail, then it will +be treated as unset and &%tls_require_ciphers%& will be used instead. +.wen + + .option data_timeout smtp time 5m This sets a timeout for the transmission of each block in the data portion of the message. As a result, the overall timeout for a message depends on the size @@ -26091,6 +26162,12 @@ public name) of the authenticator driver that successfully authenticated the client from which the message was received. This variable is empty if there was no successful authentication. +.new +.cindex authentication "expansion item" +Successful authentication sets up information used by the +&$authresults$& expansion item. +.wen + @@ -28068,8 +28145,7 @@ that DNS lookups they do for the server have not been tampered with. The domain to this server, its A record, its TLSA record and any associated CNAME records must all be covered by DNSSEC. 2) add TLSA DNS records. These say what the server certificate for a TLS connection should be. -3) offer a server certificate, or certificate chain, in TLS connections which is traceable to the one -defined by (one of?) the TSLA records +3) offer a server certificate, or certificate chain, in TLS connections which is is anchored by one of the TLSA records. There are no changes to Exim specific to server-side operation of DANE. Support for client-side operation of DANE can be included at compile time by defining SUPPORT_DANE=yes @@ -28124,8 +28200,9 @@ This modification of hosts_request_ocsp is only done if it has the default value those who use &%hosts_require_ocsp%&, should consider the interaction with DANE in their OCSP settings. -For client-side DANE there are two new smtp transport options, &%hosts_try_dane%& and &%hosts_require_dane%&. -The latter variant will result in failure if the target host is not DNSSEC-secured. +For client-side DANE there are three new smtp transport options, &%hosts_try_dane%&, &%hosts_require_dane%& +and &%dane_require_tls_ciphers%&. +The require variant will result in failure if the target host is not DNSSEC-secured. DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records. @@ -28134,6 +28211,14 @@ If a TLSA lookup is done and succeeds, a DANE-verified TLS connection will be required for the host. If it does not, the host will not be used; there is no fallback to non-DANE or non-TLS. +If DANE is requested and usable, then the TLS cipher list configuration +prefers to use the option &%dane_require_tls_ciphers%& and falls +back to &%tls_require_ciphers%& only if that is unset. +This lets you configure "decent crypto" for DANE and "better than nothing +crypto" as the default. Note though that while GnuTLS lets the string control +which versions of TLS/SSL will be negotiated, OpenSSL does not and you're +limited to ciphersuite constraints. + If DANE is requested and useable (see above) the following transport options are ignored: .code hosts_require_tls @@ -28153,7 +28238,16 @@ If verification was successful using DANE then the "CV" item in the delivery log There is a new variable &$tls_out_dane$& which will have "yes" if verification succeeded using DANE and "no" otherwise (only useful -in combination with EXPERIMENTAL_EVENT), and a new variable &$tls_out_tlsa_usage$& (detailed above). +in combination with events; see &<>&), +and a new variable &$tls_out_tlsa_usage$& (detailed above). + +.cindex DANE reporting +An event (see &<>&) of type "dane:fail" will be raised on failures +to achieve DANE-verified connection, if one was either requested and offered, or +required. This is intended to support TLS-reporting as defined in +&url(https://tools.ietf.org/html/draft-ietf-uta-smtp-tlsrpt-17). +The &$event_data$& will be one of the Result Types defined in +Section 4.3 of that document. Under GnuTLS, DANE is only supported from version 3.0.0 onwards. .wen @@ -31789,27 +31883,36 @@ If the value of &%av_scanner%& starts with a dollar character, it is expanded before use. The usual list-parsing of the content (see &<>&) applies. The following scanner types are supported in this release, -.new though individual ones can be included or not at build time: -.wen .vlist .vitem &%avast%& .cindex "virus scanners" "avast" This is the scanner daemon of Avast. It has been tested with Avast Core -Security (currently at version 1.1.7). -You can get a trial version at &url(http://www.avast.com) or for Linux -at &url(http://www.avast.com/linux-server-antivirus). +Security (currently at version 2.2.0). +You can get a trial version at &url(https://www.avast.com) or for Linux +at &url(https://www.avast.com/linux-server-antivirus). This scanner type takes one option, which can be either a full path to a UNIX socket, or host and port specifiers separated by white space. The host may be a name or an IP address; the port is either a single number or a pair of numbers with a dash between. -Any further options are given, on separate lines, -to the daemon as options before the main scan command. +A list of options may follow. These options are interpreted on the +Exim's side of the malware scanner, or are given on separate lines to +the daemon as options before the main scan command. + +.new +.cindex &`pass_unscanned`& "avast" +If &`pass_unscanned`& +is set, any files the Avast scanner can't scan (e.g. +decompression bombs, or invalid archives) are considered clean. Use with +care. +.wen + For example: .code av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup +av_scanner = avast:/var/run/avast/scan.sock:pass_unscanned:FLAGS -fullfiles:SENSITIVITY -pup av_scanner = avast:192.168.2.22 5036 .endd If you omit the argument, the default path @@ -31826,6 +31929,9 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO: PACK .endd +If the scanner returns a temporary failure (e.g. license issues, or +permission problems), the message is deferred and a paniclog entry is +written. The usual &`defer_ok`& option is available. .vitem &%aveserver%& .cindex "virus scanners" "Kaspersky" @@ -31876,7 +31982,7 @@ av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234 If the value of av_scanner points to a UNIX socket file or contains the &`local`& option, then the ClamAV interface will pass a filename containing the data -to be scanned, which will should normally result in less I/O happening and be +to be scanned, which should normally result in less I/O happening and be more efficient. Normally in the TCP case, the data is streamed to ClamAV as Exim does not assume that there is a common filesystem with the remote host. @@ -36420,6 +36526,7 @@ selection marked by asterisks: &` queue_time_overall `& time on queue for whole message &` pid `& Exim process id &` proxy `& proxy address on <= and => lines +&` receive_time `& time taken to receive message &` received_recipients `& recipients on <= lines &` received_sender `& sender on <= lines &`*rejected_header `& header contents on reject log @@ -38879,7 +38986,8 @@ The result can either be a valid RSA private key in ASCII armor (.pem file), including line breaks .new .next -with GnuTLS 3.6.0 or later, be a valid Ed25519 private key (same format as above) +with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, +be a valid Ed25519 private key (same format as above) .wen .next start with a slash, in which case it is treated as a file that contains @@ -38891,6 +38999,21 @@ is set. .endlist .new +To generate keys under OpenSSL: +.code +openssl genrsa -out dkim_rsa.private 2048 +openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM +.endd +Take the base-64 lines from the output of the second command, concatenated, +for the DNS TXT record. +See section 3.6 of RFC6376 for the record specification. + +Under GnuTLS: +.code +certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private +certtool --load-privkey=dkim_rsa.private --pubkey-info +.endd + Note that RFC 8301 says: .code Signers MUST use RSA keys of at least 1024 bits for all keys. @@ -38905,6 +39028,18 @@ As they are a recent development, users should consider dual-signing for some transition period. The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC keys. + +OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys: +.code +openssl genpkey -algorithm ed25519 -out dkim_ed25519.private +certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private +.endd + +To produce the required public key value for a DNS record: +.code +openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64 +certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64 +.endd .wen .option dkim_hash smtp string&!! sha256 @@ -38975,6 +39110,12 @@ To evaluate the signature in the ACL a large number of expansion variables containing the signature status and its details are set up during the runtime of the ACL. +.new +.cindex authentication "expansion item" +Performing verification sets up information used by the +&$authresults$& expansion item. +.wen + Calling the ACL only for existing signatures is not sufficient to build more advanced policies. For that reason, the global option &%dkim_verify_signers%&, and a global expansion variable @@ -39090,7 +39231,8 @@ The key record selector string. .vitem &%$dkim_algo%& The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. .new -If running under GnuTLS 3.6.0 or later, may also be 'ed25519-sha256'. +If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, +may also be 'ed25519-sha256'. The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC keys. .wen @@ -39234,6 +39376,12 @@ There is no Exim involvement on the trasmission of messages; publishing certain DNS records is all that is required. For verification, an ACL condition and an expansion lookup are provided. +.new +.cindex authentication "expansion item" +Performing verification sets up information used by the +&$authresults$& expansion item. +.wen + .cindex SPF "ACL condition" .cindex ACL "spf condition" @@ -39263,18 +39411,11 @@ its domain as well. This should be treated like "none". .vitem &%permerror%& This indicates a syntax error in the SPF record of the queried domain. -You may deny messages when this occurs. (Changed in 4.83) +You may deny messages when this occurs. .vitem &%temperror%& This indicates a temporary error during all processing, including Exim's SPF processing. You may defer messages when this occurs. -(Changed in 4.83) - -.vitem &%err_temp%& -Same as permerror, deprecated in 4.83, will be removed in a future release. - -.vitem &%err_perm%& -Same as temperror, deprecated in 4.83, will be removed in a future release. .endlist You can prefix each string with an exclamation mark to invert @@ -39322,6 +39463,11 @@ variables: one of pass, fail, softfail, none, neutral, permerror or temperror. +.vitem &$spf_result_guessed$& +.vindex &$spf_result_guessed$& + This boolean is true only if a best-guess operation was used + and required in order to obtain a result. + .vitem &$spf_smtp_comment$& .vindex &$spf_smtp_comment$& This contains a string that can be used in a SMTP response @@ -39709,6 +39855,7 @@ expansion must check this, as it will be called for every possible event type. The current list of events is: .display +&`dane:fail after transport `& per connection &`msg:complete after main `& per message &`msg:delivery after transport `& per recipient &`msg:rcpt:host:defer after transport `& per recipient per host @@ -39737,6 +39884,7 @@ should define the event action. An additional variable, &$event_data$&, is filled with information varying with the event type: .display +&`dane:fail `& failure reason &`msg:delivery `& smtp confirmation message &`msg:rcpt:host:defer `& error string &`msg:rcpt:defer `& error string @@ -39764,15 +39912,12 @@ The expansion of the event_action option should normally return an empty string. Should it return anything else the following will be forced: .display -&`msg:delivery `& (ignored) -&`msg:host:defer `& (ignored) -&`msg:fail:delivery`& (ignored) &`tcp:connect `& do not connect -&`tcp:close `& (ignored) &`tls:cert `& refuse verification &`smtp:connect `& close connection .endd -No other use is made of the result string. +All other message types ignore the result string, and +no other use is made of it. For a tcp:connect event, if the connection is being made to a proxy then the address and port variables will be that of the proxy and not