Move OCSP out of EXPERIMENTAL

1 files changed, 103 insertions, 0 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 46c83adf9..990df6241 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -13222,6 +13222,7 @@ listed in more than one group.
 .row &%tls_crl%&                     "certificate revocation list"
 .row &%tls_dh_max_bits%&             "clamp D-H bit count suggestion"
 .row &%tls_dhparam%&                 "DH parameters for server"
+.row &%tls_ocsp_file%&               "location of server certificate status proof"
 .row &%tls_on_connect_ports%&        "specify SSMTP (SMTPS) ports"
 .row &%tls_privatekey%&              "location of server private key"
 .row &%tls_remember_esmtp%&          "don't reset after starting TLS"
@@ -16341,6 +16342,13 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
 acceptable bound from 1024 to 2048.
 
 
+.option tls_ocsp_file main string&!! unset
+This option
+must if set expand to the absolute path to a file which contains a current
+status proof for the server's certificate, as obtained from the
+Certificate Authority.
+
+
 .option tls_on_connect_ports main "string list" unset
 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
 operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
@@ -23005,6 +23013,18 @@ hard failure if required. See also &%hosts_try_auth%&, and chapter
 &<<CHAPSMTPAUTH>>& for details of authentication.
 
 
+.option hosts_request_ocsp smtp "host list&!!" *
+.cindex "TLS" "requiring for certain servers"
+Exim will request a Certificate Status on a
+TLS session for any host that matches this list.
+&%tls_verify_certificates%& should also be set for the transport.
+
+.option hosts_require_ocsp smtp "host list&!!" unset
+.cindex "TLS" "requiring for certain servers"
+Exim will request, and check for a valid Certificate Status being given, on a
+TLS session for any host that matches this list.
+&%tls_verify_certificates%& should also be set for the transport.
+
 .option hosts_require_tls smtp "host list&!!" unset
 .cindex "TLS" "requiring for certain servers"
 Exim will insist on using a TLS session when delivering to any host that
@@ -26164,12 +26184,79 @@ certificate is supplied, &$tls_in_peerdn$& is empty.
 .cindex "TLS" "revoked certificates"
 .cindex "revocation list"
 .cindex "certificate" "revocation list"
+.cindex "OCSP" "stapling"
 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
 certificates are revoked. If you have such a list, you can pass it to an Exim
 server using the global option called &%tls_crl%& and to an Exim client using
 an identically named option for the &(smtp)& transport. In each case, the value
 of the option is expanded and must then be the name of a file that contains a
 CRL in PEM format.
+The downside is that clients have to periodically re-download a potentially huge
+file from every certificate authority the know of.
+
+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.
+
+The only widespread OCSP server implementation (known to this writer)
+comes as part of OpenSSL and aborts on an invalid request, such as
+connecting to the port and then disconnecting.  This requires
+re-entering the passphrase each time some random client does this.
+
+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
+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
+starts retrying to fetch an OCSP proof some time before its current
+proof expires.  The downside is that it requires server support.
+
+Unless Exim is built with the support disabled,
+or with GnuTLS earlier than version 3.1.3,
+support for OCSP stapling is included.
+
+There is a global option called &%tls_ocsp_file%&.
+The file specified therein is expected to be in DER format, and contain
+an OCSP proof.  Exim will serve it as part of the TLS handshake.  This
+option will be re-expanded for SNI, if the &%tls_certificate%& option
+contains &`tls_in_sni`&, as per other TLS options.
+
+Exim does not at this time implement any support for fetching a new OCSP
+proof.  The burden is on the administrator to handle this, outside of
+Exim.  The file specified should be replaced atomically, so that the
+contents are always valid.  Exim will expand the &%tls_ocsp_file%& option
+on each connection, so a new file will be handled transparently on the
+next connection.
+
+When built with OpenSSL Exim will check for a valid next update timestamp
+in the OCSP proof; if not present, or if the proof has expired, it will be
+ignored.
+
+For the client to be able to verify the stapled OCSP the server must
+also supply, in its stapled information, any intermediate
+certificates for the chain leading to the OCSP proof from the signer
+of the server certificate.  There may be zero or one such. These
+intermediate certificates should be added to the server OCSP stapling
+file named by &%tls_ocsp_file%&.
+
+Note that the proof only covers the terminal server certificate,
+not any of the chain from CA to it.
+
+.code
+  A helper script "ocsp_fetch.pl" for fetching a proof from a CA
+  OCSP server is supplied.  The server URL may be included in the
+  server certificate, if the CA is helpful.
+
+  One failure mode seen was the OCSP Signer cert expiring before the end
+  of validity of the OCSP proof. The checking done by Exim/OpenSSL
+  noted this as invalid overall, but the re-fetch script did not.
+.endd
+
+
 
 
 .section "Configuring an Exim client to use TLS" "SECID185"
@@ -26225,6 +26312,19 @@ The &%tls_verify_hosts%& and &%tls_try_verify_hosts%& options restrict
 certificate verification to the listed servers.  Verification either must
 or need not succeed respectively.
 
+The &(smtp)& transport has two OCSP-related options:
+&%hosts_require_ocsp%&; a host-list for which a Certificate Status
+is requested and required for the connection to proceed.  The default
+value is empty.
+&%hosts_request_ocsp%&; a host-list for which (additionally)
+a Certificate Status is requested (but not necessarily verified).  The default
+value is "*" meaning that requests are made unless configured
+otherwise.
+
+The host(s) should also be in &%hosts_require_tls%&, and
+&%tls_verify_certificates%& configured for the transport,
+for OCSP to be relevant.
+
 If
 &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a
 list of permitted cipher suites. If either of these checks fails, delivery to
@@ -26310,6 +26410,9 @@ during TLS session handshake, to permit alternative values to be chosen:
 .next
 .vindex "&%tls_verify_certificates%&"
 &%tls_verify_certificates%&
+.next
+.vindex "&%tls_ocsp_file%&"
+&%tls_verify_certificates%&
 .endlist
 
 Great care should be taken to deal with matters of case, various injection