tls_dhparam size constraint suggestions.

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 800ef5ec16f038dd6b90b03ec69de5106710f50f..371b28e43773d028f6cc0f11a2186361f146d966 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9777,6 +9777,16 @@ This operator converts a hex string into one that is base64 encoded. This can
 be useful for processing the output of the MD5 and SHA-1 hashing functions.
 
 
+
+.vitem &*${hexquote:*&<&'string'&>&*}*&
+.cindex "quoting" "hex-encoded unprintable characters"
+.cindex "&%hexquote%& expansion item"
+This operator converts non-printable characters in a string into a hex
+escape form. Byte values between 33 (!) and 126 (~) inclusive are left
+as is, and other byte values are converted to &`\xNN`&, for example a
+byt value 127 is converted to &`\x7f`&.
+
+
 .vitem &*${lc:*&<&'string'&>&*}*&
 .cindex "case forcing in strings"
 .cindex "string" "case forcing"
@@ -10327,6 +10337,8 @@ ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
 The value of &$item$& is saved and restored while &*forany*& or &*forall*& is
 being processed, to enable these expansion items to be nested.
 
+To scan a named list, expand it with the &*listnamed*& operator.
+
 
 .vitem &*ge&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
        &*gei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
@@ -13974,7 +13986,7 @@ This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with
 the p11-kit configuration files in &_/etc/pkcs11/modules/_&.
 
 See
-&url(http://www.gnu.org/software/gnutls/manual/gnutls.html#Smart-cards-and-HSMs)
+&url(http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs)
 for documentation.
 .wen
 
@@ -14730,6 +14742,8 @@ Possible options may include:
 .next
 &`no_tlsv1_2`&
 .next
+&`safari_ecdhe_ecdsa_bug`&
+.next
 &`single_dh_use`&
 .next
 &`single_ecdh_use`&
@@ -14745,6 +14759,15 @@ Possible options may include:
 &`tls_rollback_bug`&
 .endlist
 
+.new
+As an aside, the &`safari_ecdhe_ecdsa_bug`& item is a misnomer and affects
+all clients connecting using the MacOS SecureTransport TLS facility prior
+to MacOS 10.8.4, including email clients.  If you see old MacOS clients failing
+to negotiate TLS then this option value might help, provided that your OpenSSL
+release is new enough to contain this work-around.  This may be a situation
+where you have to upgrade OpenSSL to get buggy clients working.
+.wen
+
 
 .option oracle_servers main "string list" unset
 .cindex "Oracle" "server list"
@@ -16008,6 +16031,21 @@ The available primes are:
 Some of these will be too small to be accepted by clients.
 Some may be too large to be accepted by clients.
 
+The TLS protocol does not negotiate an acceptable size for this; clients tend
+to hard-drop connections if what is offered by the server is unacceptable,
+whether too large or too small, and there's no provision for the client to
+tell the server what these constraints are.  Thus, as a server operator, you
+need to make an educated guess as to what is most likely to work for your
+userbase.
+
+Some known size constraints suggest that a bit-size in the range 2048 to 2236
+is most likely to maximise interoperability.  The upper bound comes from
+applications using the Mozilla Network Security Services (NSS) library, which
+used to set its &`DH_MAX_P_BITS`& upper-bound to 2236.  This affects many
+mail user agents (MUAs). The lower bound comes from Debian installs of Exim4
+prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
+acceptable bound from 1024 to 2048.
+
 
 .option tls_on_connect_ports main "string list" unset
 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
@@ -25574,10 +25612,10 @@ aware of future feature enhancements of GnuTLS.
 
 Documentation of the strings accepted may be found in the GnuTLS manual, under
 "Priority strings".  This is online as
-&url(http://www.gnu.org/software/gnutls/manual/html_node/Priority-Strings.html),
+&url(http://www.gnutls.org/manual/html_node/Priority-Strings.html),
 but beware that this relates to GnuTLS 3, which may be newer than the version
 installed on your system.  If you are using GnuTLS 3,
-&url(http://www.gnu.org/software/gnutls/manual/html_node/Listing-the-ciphersuites-in-a-priority-string.html, then the example code)
+&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.
 
 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
@@ -25663,7 +25701,7 @@ tls_dhparam = none
 This may also be set to a string identifying a standard prime to be used for
 DH; if it is set to &`default`& or, for OpenSSL, is unset, then the prime
 used is &`ike23`&.  There are a few standard primes available, see the
-documetnation for &%tls_dhparam%& for the complete list.
+documentation for &%tls_dhparam%& for the complete list.
 
 See the command
 .code
@@ -27074,6 +27112,21 @@ the message is ultimately accepted. For details, see section &<<SECTremoveheadac
 .cindex "&%set%& ACL modifier"
 This modifier puts a value into one of the ACL variables (see section
 &<<SECTaclvariables>>&).
+
+
+.vitem &*udpsend*&&~=&~<&'parameters'&>
+This modifier sends a UDP packet, for purposes such as statistics
+collection or behaviour monitoring. The parameters are expanded, and
+the result of the expansion must be a colon-separated list consisting
+of a destination server, port number, and the packet contents. The
+server can be specified as a host name or IPv4 or IPv6 address. The
+separator can be changed with the usual angle bracket syntax. For
+example, you might want to collect information on which hosts connect
+when:
+.code
+udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
+             $tod_zulu $sender_host_address
+.endd
 .endlist