Avast: implement pass_unscanned option

[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 295cb15c19c5a4d856292f4cb2adca61bf87f635..f455c9f0c7515fae848739872e8977fdba1ec830 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9154,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:"
 .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.
 This item returns a string suitable for insertion as an
 &'Authentication-Results"'&
 header line.


@@ -9172,6 +9173,7 @@ Example use (as an ACL modifier):
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd

+This is safe even if no authentication reselts are available.

 .wen
 
 
 .wen
 
 


@@ -11593,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$&.
 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.
 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"
 
 .vitem &$authenticated_fail_id$&
 .cindex "authentication" "fail" "id"


@@ -11936,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$&.
 
 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$&.
 .vitem &$host_lookup_failed$&
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.


@@ -12891,6 +12905,7 @@ is compiled with the content-scanning extension. For details, see section
 .vitem &$spf_header_comment$& &&&
        &$spf_received$& &&&
        &$spf_result$& &&&
 .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>>&.
        &$spf_smtp_comment$&
 These variables are only available if Exim is built with SPF support.
 For details see section &<<SECSPF>>&.


@@ -23926,6 +23941,24 @@ For testing purposes, this value can be overridden by the &%-oB%& command line
 option.
 
 
 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
 .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


@@ -26104,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.
 
 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
+

 
 
 
 
 
 


@@ -28081,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.
 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
 
 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


@@ -28137,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.
 
 
 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.
 
 
 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records.
 


@@ -28147,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.
 
 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
 If DANE is requested and useable (see above) the following transport options are ignored:
 .code
   hosts_require_tls


@@ -31811,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,
 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:
 though individual ones can be included or not at build time:

-.wen

 
 .vlist
 .vitem &%avast%&
 
 .vlist
 .vitem &%avast%&


@@ -31827,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.
 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
 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
 av_scanner = avast:192.168.2.22 5036
 .endd
 If you omit the argument, the default path


@@ -31848,8 +31904,9 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO:
     PACK
 .endd
 
     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"
 
 .vitem &%aveserver%&
 .cindex "virus scanners" "Kaspersky"


@@ -31900,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
 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.
 
 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.
 


@@ -38916,6 +38973,21 @@ is set.
 .endlist
 
 .new
 .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.
 Note that RFC 8301 says:
 .code
 Signers MUST use RSA keys of at least 1024 bits for all keys.


@@ -38930,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.
 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
 .wen
 
 .option dkim_hash smtp string&!! sha256


@@ -39000,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.
 
 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
 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


@@ -39260,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.
 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"
 
 .cindex SPF "ACL condition"
 .cindex ACL "spf condition"


@@ -39289,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.
 
 .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.
 
 .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
 .endlist
 
 You can prefix each string with an exclamation mark to  invert


@@ -39348,6 +39437,11 @@ variables:
   one of pass, fail, softfail, none, neutral, permerror or
   temperror.
 
   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
 .vitem &$spf_smtp_comment$&
 .vindex &$spf_smtp_comment$&
   This contains a string that can be used in a SMTP response