wip: OpenSSL docs on custom installpdp_openssl_102_min

To fix before merge: ability to use `$ORIGIN` in linker line via Exim
config file.

3 files changed, 88 insertions, 0 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4497a8f9e..75f28ef67 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -434,6 +434,7 @@ directory are:
 .row &_filter.txt_&          "specification of the filter language"
 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
+.row &_openssl.txt_&         "installing a current OpenSSL release"
 .endtable
 
 The main specification and the specification of the filtering language are also
diff --git a/doc/doc-txt/openssl.txt b/doc/doc-txt/openssl.txt
new file mode 100644
index 000000000..948612711
--- /dev/null
+++ b/doc/doc-txt/openssl.txt
@@ -0,0 +1,77 @@
+OpenSSL
+=======
+
+The OpenSSL Project documents their supported releases at
+<https://www.openssl.org/policies/releasestrat.html>.  The Exim
+Maintainers are unwilling to try to support Exim built with a
+version of a critical security library which is unmaintained.
+
+Thus as versions of OpenSSL become unsupported by OpenSSL, they become
+unsupported by Exim.  Exim might build with older releases of OpenSSL,
+but that's risky behaviour.
+
+If your operating system vendor continues to ship an older version of
+OpenSSL and is diligently backporting security fixes, and they support
+Exim, then they will be backporting fixes to their packages of Exim too.
+If you wish to stick purely to packages of OpenSSL, then stick to
+packages of Exim too.
+
+If someone maintains "backports", that is worth exploring too.
+
+Note that a number of OSes use Exim with GnuTLS, not OpenSSL.
+
+Otherwise, assuming that your operating system has old OpenSSL, and you
+wish to use current Exim with OpenSSL, then you need to build and
+install your own, without interfering with the system libraries.
+Fortunately, this is easy.
+
+So this only applies if you build Exim yourself.
+
+
+Build
+-----
+
+Extract the current source of OpenSSL.  Change into that directory.
+
+This assumes that `/opt/openssl` is not in use.  If it is, pick
+something else.  `/opt/exim/openssl` perhaps.
+
+    ./config --prefix=/opt/openssl --openssldir=/etc/ssl
+    enable-ssl-trace
+    make
+    make install
+
+You now have an installed OpenSSL under /opt/openssl which will not be
+used by any system programs.
+
+When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
+choose the pkg-config approach in that file, but also tell Exim to add
+the relevant directory into the rpath stamped into the binary:
+
+    SUPPORT_TLS=yes
+    USE_OPENSSL_PC=openssl
+    EXTRALIBS_EXIM=-ldl -Wl,-R/opt/openssl/lib
+
+The -ldl is needed by OpenSSL 1.1+ on Linux and is not needed on most
+other platforms.
+
+Then tell pkg-config how to find the configuration files for your new
+OpenSSL install, and build Exim:
+
+    export PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
+    make
+    sudo make install
+
+
+Variations
+----------
+
+If you are _only_ going to use the updated OpenSSL with Exim, then
+consider using a `lib` dir alongside the `bin` dir for Exim, and then on
+the `EXTRALIBS_EXIM=` line in `Local/Makefile` use:
+
+    EXTRALIBS_EXIM=-ldl -Wl,-R$ORIGIN/../lib
+
+FIXME-BEFORE-MERGE: make this work in Exim, instead of expanding the
+`$O` to `OS` whether quoted or not.
+
diff --git a/src/README.UPDATING b/src/README.UPDATING
index 8cb59e91e..9cebc5d75 100644
--- a/src/README.UPDATING
+++ b/src/README.UPDATING
@@ -26,6 +26,16 @@ The rest of this document contains information about changes in 4.xx releases
 that might affect a running system.
 
 
+Exim version 4.89
+-----------------
+
+ * OpenSSL: oldest supported release series is now 1.0.2, which is the oldest
+   supported by the OpenSSL project.  If you can build Exim with an older
+   release series, congratulations.  If you can't, then upgrade.  Any Exim
+   bug-reports on the topci will be closed invalid.  The file doc/openssl.txt
+   contains simple instructions for installing a current OpenSSL.
+
+
 Exim version 4.88
 -----------------