Certificate variables and field-extractor expansions. Bug 1358
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index d0503d9e847e9fa61a5ed3f351c48fca9310515d..16738a51ff25fc60426f5d17f7dbceae9d666c7d 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
@@ -86,7 +87,7 @@ 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.
 
-Also, given EXPERIMENTAL_OCSP and OpenSSL, the smtp transport gains
+Also, given EXPERIMENTAL_OCSP, 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"
@@ -99,6 +100,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 +111,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 +464,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 +1091,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 +1120,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