Expansions: A tls option on ${readsocket }. Bug 2282

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 863a6b949f9bc820cbb9e126af0c308665eff4d6..8b939b52b1e66d5d20a47c97e2df805a7e48610a 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9878,15 +9878,26 @@ extend what can be done. Firstly, you can vary the timeout. For example:
 .code
 ${readsocket{/socket/name}{request string}{3s}}
 .endd
+
 The third argument is a list of options, of which the first element is the timeout
 and must be present if the argument is given.
 Further elements are options of form &'name=value'&.
-One option type is currently recognised, defining whether (the default)
+Two option types is currently recognised: shutdown and tls.
+The first defines whether (the default)
 or not a shutdown is done on the connection after sending the request.
 Example, to not do so (preferred, eg. by some webservers):
 .code
 ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
 .endd
+.new
+The second, tls, controls the use of TLS on the connection.  Example:
+.code
+${readsocket{/socket/name}{request string}{3s:tls=yes}}
+.endd
+The default is to not use TLS.
+If it is enabled, a shutdown as descripbed above is never done.
+.wen
+
 A fourth argument allows you to change any newlines that are in the data
 that is read, in the same way as for &%readfile%& (see above). This example
 turns them into spaces:
@@ -26769,7 +26780,7 @@ authenticator only. There is only one option:
 
 .option server_socket dovecot string unset
 
-This option must specify the socket that is the interface to Dovecot
+This option must specify the UNIX socket that is the interface to Dovecot
 authentication. The &%public_name%& option must specify an authentication
 mechanism that Dovecot is configured to support. You can have several
 authenticators for different mechanisms. For example:
@@ -27417,7 +27428,10 @@ the size of the generated prime, so it might still be too large.
 .oindex "&%tls_require_ciphers%&" "OpenSSL"
 There is a function in the OpenSSL library that can be passed a list of cipher
 suites before the cipher negotiation takes place. This specifies which ciphers
-are acceptable. The list is colon separated and may contain names like
+.new
+are acceptable for TLS versions prior to 1.3.
+.wen
+The list is colon separated and may contain names like
 DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%&
 directly to this function call.
 Many systems will install the OpenSSL manual-pages, so you may have
@@ -27482,6 +27496,18 @@ This example will prefer ECDSA-authenticated ciphers over RSA ones:
 tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT
 .endd
 
+.new
+For TLS version 1.3 the control available is less fine-grained
+and Exim does not provide access to it at present.
+The value of the &%tls_require_ciphers%& option is ignored when
+TLS version 1.3 is negotiated.
+
+As of writing the library default cipher suite list for TLSv1.3 is
+.code
+TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
+.endd
+.wen
+
 
 .section "Requiring specific ciphers or other parameters in GnuTLS" &&&
          "SECTreqciphgnu"