Docs: update drweb malware scanner interface description

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d3a28a40aead7ead59b8dfe81ada8ccca5690cfb..7a65acf155aea1951bd323caf52bb5bd54ae9b4c 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8939,8 +8939,10 @@ a right angle-bracket followed immediately by the new separator.
 Recognised RDN type labels include "CN", "O", "OU" and "DC".
 
 The field selectors marked as "time" above
 Recognised RDN type labels include "CN", "O", "OU" and "DC".
 
 The field selectors marked as "time" above

-may output a number of seconds since epoch
-if the modifier "int" is used.
+take an optional modifier of "int"
+for which the result is the number of seconds since epoch.
+Otherwise the result is a human-readable string
+in the timezone selected by the main "timezone" option.

 
 The field selectors marked as "list" above return a list,
 newline-separated by default,
 
 The field selectors marked as "list" above return a list,
 newline-separated by default,


@@ -11930,10 +11932,7 @@ on which interface and/or port is being used for the incoming connection. The
 values of &$received_ip_address$& and &$received_port$& are saved with any
 messages that are received, thus making these variables available at delivery
 time.
 values of &$received_ip_address$& and &$received_port$& are saved with any
 messages that are received, thus making these variables available at delivery
 time.

-
-&*Note:*& There are no equivalent variables for outgoing connections, because
-the values are unknown (unless they are explicitly set by options of the
-&(smtp)& transport).
+For outbound connections see &$sending_ip_address$&.

 
 .vitem &$received_port$&
 .vindex "&$received_port$&"
 
 .vitem &$received_port$&
 .vindex "&$received_port$&"


@@ -12152,8 +12151,9 @@ the &%-bs%& or &%-bS%& options.
 
 .vitem &$sender_host_address$&
 .vindex "&$sender_host_address$&"
 
 .vitem &$sender_host_address$&
 .vindex "&$sender_host_address$&"

-When a message is received from a remote host, this variable contains that
-host's IP address. For locally submitted messages, it is empty.
+When a message is received from a remote host using SMTP,
+this variable contains that
+host's IP address. For locally non-SMTP submitted messages, it is empty.

 
 .vitem &$sender_host_authenticated$&
 .vindex "&$sender_host_authenticated$&"
 
 .vitem &$sender_host_authenticated$&
 .vindex "&$sender_host_authenticated$&"


@@ -15061,16 +15061,21 @@ yourself in the foot in various unpleasant ways.  This option should not be
 adjusted lightly.  An unrecognised item will be detected at startup, by
 invoking Exim with the &%-bV%& flag.
 
 adjusted lightly.  An unrecognised item will be detected at startup, by
 invoking Exim with the &%-bV%& flag.
 

+The option affects Exim operating both as a server and as a client.
+

 Historical note: prior to release 4.80, Exim defaulted this value to
 "+dont_insert_empty_fragments", which may still be needed for compatibility
 with some clients, but which lowers security by increasing exposure to
 some now infamous attacks.
 
 Historical note: prior to release 4.80, Exim defaulted this value to
 "+dont_insert_empty_fragments", which may still be needed for compatibility
 with some clients, but which lowers security by increasing exposure to
 some now infamous attacks.
 

-An example:
+Examples:

 .code
 # Make both old MS and old Eudora happy:
 openssl_options = -all +microsoft_big_sslv3_buffer \
                        +dont_insert_empty_fragments
 .code
 # Make both old MS and old Eudora happy:
 openssl_options = -all +microsoft_big_sslv3_buffer \
                        +dont_insert_empty_fragments

+
+# Disable older protocol versions:
+openssl_options = +no_sslv2 +no_sslv3

 .endd
 
 Possible options may include:
 .endd
 
 Possible options may include:


@@ -16497,12 +16502,17 @@ directory containing certificate files.
 For earlier versions of GnuTLS
 the option must be set to the name of a single file.
 
 For earlier versions of GnuTLS
 the option must be set to the name of a single file.
 

+With OpenSSL the certificates specified
+explicitly
+either by file or directory
+are added to those given by the system default location.
+

 These certificates should be for the certificate authorities trusted, rather
 than the public cert of individual clients.  With both OpenSSL and GnuTLS, if
 the value is a file then the certificates are sent by Exim as a server to
 connecting clients, defining the list of accepted certificate authorities.
 Thus the values defined should be considered public data.  To avoid this,
 These certificates should be for the certificate authorities trusted, rather
 than the public cert of individual clients.  With both OpenSSL and GnuTLS, if
 the value is a file then the certificates are sent by Exim as a server to
 connecting clients, defining the list of accepted certificate authorities.
 Thus the values defined should be considered public data.  To avoid this,

-use OpenSSL with a directory.
+use the explicit directory version.

 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 
 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 


@@ -23423,7 +23433,7 @@ unknown state), opens a new one to the same host, and then tries the delivery
 in clear.
 
 
 in clear.
 
 

-.option tls_try_verify_hosts smtp "host list&!! unset
+.option tls_try_verify_hosts smtp "host list&!!" unset

 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 This option gives a list of hosts for which, on encrypted connections,
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 This option gives a list of hosts for which, on encrypted connections,


@@ -23431,7 +23441,7 @@ certificate verification will be tried but need not succeed.
 The &%tls_verify_certificates%& option must also be set.
 Note that unless the host is in this list
 TLS connections will be denied to hosts using self-signed certificates
 The &%tls_verify_certificates%& option must also be set.
 Note that unless the host is in this list
 TLS connections will be denied to hosts using self-signed certificates

-when &%tls_verify_certificates%& is set.
+when &%tls_verify_certificates%& is matched.

 The &$tls_out_certificate_verified$& variable is set when
 certificate verification succeeds.
 
 The &$tls_out_certificate_verified$& variable is set when
 certificate verification succeeds.
 


@@ -23450,6 +23460,12 @@ you can set
 files.
 For earlier versions of GnuTLS the option must be set to the name of a
 single file.
 files.
 For earlier versions of GnuTLS the option must be set to the name of a
 single file.

+
+With OpenSSL the certificates specified
+explicitly
+either by file or directory
+are added to those given by the system default location.
+

 The values of &$host$& and
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
 The values of &$host$& and
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.


@@ -23459,7 +23475,7 @@ if neither tls_verify_hosts nor tls_try_verify_hosts are set
 and certificate verification fails the TLS connection is closed.
 
 
 and certificate verification fails the TLS connection is closed.
 
 

-.option tls_verify_hosts smtp "host list&!! unset
+.option tls_verify_hosts smtp "host list&!!" unset

 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 This option gives a list of hosts for which. on encrypted connections,
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 This option gives a list of hosts for which. on encrypted connections,


@@ -26130,7 +26146,8 @@ The GnuTLS library allows the caller to provide a "priority string", documented
 as part of the &[gnutls_priority_init]& function.  This is very similar to the
 ciphersuite specification in OpenSSL.
 
 as part of the &[gnutls_priority_init]& function.  This is very similar to the
 ciphersuite specification in OpenSSL.
 

-The &%tls_require_ciphers%& option is treated as the GnuTLS priority string.
+The &%tls_require_ciphers%& option is treated as the GnuTLS priority string
+and controls both protocols and ciphers.

 
 The &%tls_require_ciphers%& option is available both as an global option,
 controlling how Exim behaves as a server, and also as an option of the
 
 The &%tls_require_ciphers%& option is available both as an global option,
 controlling how Exim behaves as a server, and also as an option of the


@@ -26147,6 +26164,12 @@ installed on your system.  If you are using GnuTLS 3,
 &url(http://www.gnutls.org/manual/gnutls.html#Listing-the-ciphersuites-in-a-priority-string, then the example code)
 on that site can be used to test a given string.
 
 &url(http://www.gnutls.org/manual/gnutls.html#Listing-the-ciphersuites-in-a-priority-string, then the example code)
 on that site can be used to test a given string.
 

+For example:
+.code
+# Disable older versions of protocols
+tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0
+.endd
+

 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
 additional options, "&%gnutls_require_kx%&", "&%gnutls_require_mac%&" and
 "&%gnutls_require_protocols%&".  &%tls_require_ciphers%& was an Exim list.
 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
 additional options, "&%gnutls_require_kx%&", "&%gnutls_require_mac%&" and
 "&%gnutls_require_protocols%&".  &%tls_require_ciphers%& was an Exim list.


@@ -26197,8 +26220,11 @@ tls_privatekey = /some/file/name
 These options are, in fact, expanded strings, so you can make them depend on
 the identity of the client that is connected if you wish. The first file
 contains the server's X509 certificate, and the second contains the private key
 These options are, in fact, expanded strings, so you can make them depend on
 the identity of the client that is connected if you wish. The first file
 contains the server's X509 certificate, and the second contains the private key

-that goes with it. These files need to be readable by the Exim user, and must
-always be given as full path names. They can be the same file if both the
+that goes with it. These files need to be
+PEM format and readable by the Exim user, and must
+always be given as full path names.
+The key must not be password-protected.
+They can be the same file if both the

 certificate and the key are contained within it. If &%tls_privatekey%& is not
 set, or if its expansion is forced to fail or results in an empty string, this
 is assumed to be the case. The certificate file may also contain intermediate
 certificate and the key are contained within it. If &%tls_privatekey%& is not
 set, or if its expansion is forced to fail or results in an empty string, this
 is assumed to be the case. The certificate file may also contain intermediate


@@ -26547,7 +26573,7 @@ during TLS session handshake, to permit alternative values to be chosen:
 &%tls_verify_certificates%&
 .next
 .vindex "&%tls_ocsp_file%&"
 &%tls_verify_certificates%&
 .next
 .vindex "&%tls_ocsp_file%&"

-&%tls_verify_certificates%&
+&%tls_ocsp_file%&

 .endlist
 
 Great care should be taken to deal with matters of case, various injection
 .endlist
 
 Great care should be taken to deal with matters of case, various injection


@@ -30330,9 +30356,13 @@ av_scanner = cmdline:\
 .endd
 .vitem &%drweb%&
 .cindex "virus scanners" "DrWeb"
 .endd
 .vitem &%drweb%&
 .cindex "virus scanners" "DrWeb"

-The DrWeb daemon scanner (&url(http://www.sald.com/)) interface takes one
-argument, either a full path to a UNIX socket, or an IP address and port
-separated by white space, as in these examples:
+The DrWeb daemon scanner (&url(http://www.sald.com/)) interface
+takes one option,
+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.
+For example:

 .code
 av_scanner = drweb:/var/run/drwebd.sock
 av_scanner = drweb:192.168.2.20 31337
 .code
 av_scanner = drweb:/var/run/drwebd.sock
 av_scanner = drweb:192.168.2.20 31337


@@ -30340,6 +30370,17 @@ av_scanner = drweb:192.168.2.20 31337
 If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_&
 is used. Thanks to Alex Miller for contributing the code for this scanner.
 
 If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_&
 is used. Thanks to Alex Miller for contributing the code for this scanner.
 

+.vitem &%f-protd%&
+.cindex "virus scanners" "f-protd"
+The f-protd scanner is accessed via HTTP over TCP.
+One argument is taken, being a space-separated hostname and port number
+(or port-range).
+For example:
+.code
+av_scanner = f-protd:localhost 10200-10204
+.endd
+If you omit the argument, the default values show above are used.
+

 .vitem &%fsecure%&
 .cindex "virus scanners" "F-Secure"
 The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one
 .vitem &%fsecure%&
 .cindex "virus scanners" "F-Secure"
 The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one