Avast: implement pass_unscanned option
[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt
index cf80e92f7ae747a41ee9cab42702d6de42fc5c8e..f455c9f0c7515fae848739872e8977fdba1ec830 100644 (file)
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
-2017
+2018
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -7839,6 +7839,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 +9154,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 +9173,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 +11595,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 +11943,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 +12905,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 &<<SECSPF>>&.
@@ -23913,6 +23941,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 +26137,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 +28120,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 +28175,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 +28186,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
@@ -31798,9 +31858,7 @@ If the value of &%av_scanner%& starts with a dollar character, it is expanded
 before use.
 The usual list-parsing of the content (see &<<SECTlistconstruct>>&) 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%&
@@ -31814,11 +31872,22 @@ 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
@@ -31835,8 +31904,9 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO:
     PACK
 .endd
 
-Only the first virus detected will be reported.
-
+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"
@@ -31887,7 +31957,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.
 
@@ -38890,7 +38960,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
@@ -38902,6 +38973,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.
@@ -38916,6 +39002,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
@@ -38986,6 +39084,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
@@ -39101,7 +39205,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
@@ -39245,6 +39350,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"
@@ -39274,18 +39385,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
@@ -39333,6 +39437,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