Docs: expand OCSP description
[exim.git] / doc / doc-docbook / spec.xfpt
index 10f21f7aba6716ad5631f961cc1d7bc5d33036af..6545d091be164d36c8b677a3785f47b3624260db 100644 (file)
@@ -7803,7 +7803,8 @@ connection timeout (the system timeout is used), no user or password, no limit
 on the number of entries returned, and no time limit on queries.
 
 When a DN is quoted in the USER= setting for LDAP authentication, Exim
-removes any URL quoting that it may contain before passing it LDAP. Apparently
+removes any URL quoting that it may contain before passing it to the LDAP library.
+Apparently
 some libraries do this for themselves, but some do not. Removing the URL
 quoting has two advantages:
 
@@ -15620,7 +15621,12 @@ by a setting such as this:
 .code
 dns_again_means_nonexist = *.in-addr.arpa
 .endd
-This option applies to all DNS lookups that Exim does. It also applies when the
+This option applies to all DNS lookups that Exim does,
+.new
+except for TLSA lookups (where knowing about such failures
+is security-relevant).
+.wen
+It also applies when the
 &[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors,
 since these are most likely to be caused by DNS lookup problems. The
 &(dnslookup)& router has some options of its own for controlling what happens
@@ -18448,20 +18454,27 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
 acceptable bound from 1024 to 2048.
 
 
-.option tls_eccurve main string&!! &`auto`&
+.option tls_eccurve main string list&!! &`auto`&
 .cindex TLS "EC cryptography"
-This option selects a EC curve for use by Exim when used with OpenSSL.
-It has no effect when Exim is used with GnuTLS.
+This option selects EC curves for use by Exim when used with OpenSSL.
+It has no effect when Exim is used with GnuTLS
+ (the equivalent can be done using a priority string for the
+&%tls_require_ciphers%& option).
 
-After expansion it must contain a valid EC curve parameter, such as
-&`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual
-for valid selections.
+After expansion it must contain
+.new
+one or (only for OpenSSL versiona 1.1.1 onwards) more
+.wen
+EC curve names, such as &`prime256v1`&, &`secp384r1`&, or &`P-521`&.
+Consult your OpenSSL manual for valid curve names.
 
 For OpenSSL versions before (and not including) 1.0.2, the string
 &`auto`& selects &`prime256v1`&. For more recent OpenSSL versions
 &`auto`& tells the library to choose.
 
-If the option expands to an empty string, no EC curves will be enabled.
+.new
+If the option expands to an empty string, the effect is undefined.
+.wen
 
 
 .option tls_ocsp_file main string&!! unset
@@ -22396,7 +22409,7 @@ its removal from incoming messages, so that delivered messages can safely be
 resent to other recipients.
 
 &*Note:*& If used on a transport handling multiple recipients
-(the smtp transport unless &%rcpt_max%& is 1, the appendfile, pipe or lmtp
+(the smtp transport unless &%max_rcpt%& is 1, the appendfile, pipe or lmtp
 transport if &%batch_max%& is greater than 1)
 then information about Bcc recipients will be leaked.
 Doing so is generally not advised.
@@ -25777,12 +25790,22 @@ If this option is set true when the &%protocol%& option is set to &"lmtp"&, the
 string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server
 has advertised support for IGNOREQUOTA in its response to the LHLO command.
 
-.option max_rcpt smtp integer 100
+.option max_rcpt smtp integer&!! 100
 .cindex "RCPT" "maximum number of outgoing"
-This option limits the number of RCPT commands that are sent in a single
-SMTP message transaction. Each set of addresses is treated independently, and
+This option,
+.new
+after expansion,
+.wen
+limits the number of RCPT commands that are sent in a single
+SMTP message transaction.
+A value setting of zero disables the limit.
+
+.new
+If a constant is given,
+.wen
+each set of addresses is treated independently, and
 so can cause parallel connections to the same host if &%remote_max_parallel%&
-permits this. A value setting of zero disables the limit.
+permits this.
 
 
 .option message_linelength_limit smtp integer 998
@@ -29977,10 +30000,13 @@ file from every certificate authority they know of.
 .next
 The way with most moving parts at query time is Online Certificate
 Status Protocol (OCSP), where the client verifies the certificate
-against an OCSP server run by the CA.  This lets the CA track all
-usage of the certs.  It requires running software with access to the
-private key of the CA, to sign the responses to the OCSP queries.  OCSP
-is based on HTTP and can be proxied accordingly.
+against an OCSP server run by the CA.
+OCSP is based on HTTP and can be proxied accordingly.
+It requires the CA running software with access to the
+private key of the CA, to sign the responses to the OCSP queries.
+Because every client TLS transaction with a server results in an OCSP
+access to the CA, it results in a heavy load on the CA.
+It also lets the CA track all usage of the certs, which is a privacy problem.
 
 The only widespread OCSP server implementation (known to this writer)
 comes as part of OpenSSL and aborts on an invalid request, such as
@@ -29990,7 +30016,8 @@ re-entering the passphrase each time some random client does this.
 .next
 The third way is OCSP Stapling; in this, the server using a certificate
 issued by the CA periodically requests an OCSP proof of validity from
-the OCSP server, then serves it up inline as part of the TLS
+the OCSP server (probably using the original OCSP above),
+then serves it up inline as part of the TLS
 negotiation.   This approach adds no extra round trips, does not let the
 CA track users, scales well with number of certs issued by the CA and is
 resilient to temporary OCSP server failures, as long as the server