OCSP observability: variables $tls_{in,out}_ocsp
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index d0503d9e847e9fa61a5ed3f351c48fca9310515d..1ec323433b70263e948603b2c754236152748c4c 100644 (file)
@@ -69,7 +69,8 @@ starts retrying to fetch an OCSP proof some time before its current
 proof expires.  The downside is that it requires server support.
 
 If Exim is built with EXPERIMENTAL_OCSP and it was built with OpenSSL,
-then it gains a new global option: "tls_ocsp_file".
+or with GnuTLS 3.1.3 or later, then it gains a new global option:
+"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
@@ -83,14 +84,21 @@ 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.
 
-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.
+Under 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.
 
-Also, given EXPERIMENTAL_OCSP and OpenSSL, the smtp transport gains
-a "hosts_require_ocsp" option; a host-list for which an OCSP Stapling
-is requested and required for the connection to proceed.  The host(s)
-should also be in "hosts_require_tls", and "tls_verify_certificates"
-configured for the transport.
+Also, given EXPERIMENTAL_OCSP, the smtp transport gains two options:
+- "hosts_require_ocsp"; a host-list for which an OCSP Stapling
+is requested and required for the connection to proceed.  The default
+value is empty.
+- "hosts_request_ocsp"; a host-list for which (additionally) an OCSP
+Stapling 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 the client to be able to verify the stapled OCSP the server must
 also supply, in its stapled information, any intermediate
@@ -99,6 +107,9 @@ 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.
+
 At this point in time, we're gathering feedback on use, to determine if
 it's worth adding complexity to the Exim daemon to periodically re-fetch
 OCSP files and somehow handling multiple files.
@@ -107,8 +118,8 @@ OCSP files and somehow handling multiple files.
   OCSP server is supplied.  The server URL may be included in the
   server certificate, if the CA is helpful.
 
-  One fail mode seen was the OCSP Signer cert expiring before the end
-  of vailidity of the OCSP proof. The checking done by Exim/OpenSSL
+  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.
 
 
@@ -460,9 +471,13 @@ which the spf condition should succeed. Valid strings are:
               processing, including Exim's SPF processing.
               You may defer messages when this occurs.
               (Changed in 4.83)
+  o err_temp  Same as permerror, deprecated in 4.83, will be
+              removed in a future release.
+  o err_perm  Same as temperror, deprecated in 4.83, will be
+              removed in a future release.
 
 You can prefix each string with an exclamation mark to  invert
-is meaning,  for example  "!fail" will  match all  results but
+its meaning,  for example  "!fail" will  match all  results but
 "fail".  The  string  list is  evaluated  left-to-right,  in a
 short-circuit fashion.  When a  string matches  the outcome of
 the SPF check, the condition  succeeds. If none of the  listed
@@ -1083,10 +1098,16 @@ Proxy Protocol server at 192.168.1.2 will look like this:
 
 3. In the ACL's the following expansion variables are available.
 
-proxy_host_address  The src IP of the proxy server making the connection
-proxy_host_port     The src port the proxy server is using
-proxy_session       Boolean, yes/no, the connected host is required to use
-                    Proxy Protocol.
+proxy_host_address   The (internal) src IP of the proxy server
+                     making the connection to the Exim server.
+proxy_host_port      The (internal) src port the proxy server is
+                     using to connect to the Exim server.
+proxy_target_address The dest (public) IP of the remote host to
+                     the proxy server.
+proxy_target_port    The dest port the remote host is using to
+                     connect to the proxy server.
+proxy_session        Boolean, yes/no, the connected host is required
+                     to use Proxy Protocol.
 
 There is no expansion for a failed proxy session, however you can detect
 it by checking if $proxy_session is true but $proxy_host is empty.  As
@@ -1106,6 +1127,13 @@ an example, in my connect ACL, I have:
                            [$sender_host_address] through proxy protocol \
                            host $proxy_host_address
 
+  # Possibly more clear
+  warn logwrite = Remote Source Address: $sender_host_address:$sender_host_port
+       logwrite = Proxy Target Address: $proxy_target_address:$proxy_target_port
+       logwrite = Proxy Internal Address: $proxy_host_address:$proxy_host_port
+       logwrite = Internal Server Address: $received_ip_address:$received_port
+
+
 4. Runtime issues to be aware of:
    - Since the real connections are all coming from your proxy, and the
      per host connection tracking is done before Proxy Protocol is