doc/doc-txt/openssl.txt

   1 OpenSSL
   2 =======
   3
   4 The OpenSSL Project documents their supported releases at
   5 <https://www.openssl.org/policies/releasestrat.html>.  The Exim
   6 Maintainers are unwilling to try to support Exim built with a
   7 version of a critical security library which is unmaintained.
   8
   9 Thus as versions of OpenSSL become unsupported by OpenSSL, they become
  10 unsupported by Exim.  Exim might build with older releases of OpenSSL,
  11 but that's risky behaviour.
  12
  13 If your operating system vendor continues to ship an older version of
  14 OpenSSL and is diligently backporting security fixes, and they support
  15 Exim, then they will be backporting fixes to their packages of Exim too.
  16 If you wish to stick purely to packages of OpenSSL, then stick to
  17 packages of Exim too.
  18
  19 If someone maintains "backports", that is worth exploring too.
  20
  21 Note that a number of OSes use Exim with GnuTLS, not OpenSSL.
  22
  23 Otherwise, assuming that your operating system has old OpenSSL, and you
  24 wish to use current Exim with OpenSSL, then you need to build and
  25 install your own, without interfering with the system libraries.
  26 Fortunately, this is easy.
  27
  28 So this only applies if you build Exim yourself.
  29
  30
  31 Build
  32 -----
  33
  34 Extract the current source of OpenSSL.  Change into that directory.
  35
  36 This assumes that `/opt/openssl` is not in use.  If it is, pick
  37 something else.  `/opt/exim/openssl` perhaps.
  38
  39 If you pick a location shared amongst various local packages, such as
  40 `/usr/local` on Linux, then the new OpenSSL will be used by all of those
  41 packages.  If that's what you want, great!  If instead you want to
  42 ensure that only software you explicitly set to use the newer OpenSSL
  43 will try to use the new OpenSSL, then stick to something like
  44 `/opt/openssl`.
  45
  46     ./config --prefix=/opt/openssl --openssldir=/etc/ssl  \
  47         -L/opt/openssl/lib -Wl,-R/opt/openssl/lib         \
  48         enable-ssl-trace shared
  49     make
  50     make install
  51
  52 On some systems, the linker uses `-rpath` instead of `-R`; on such systems,
  53 replace the parameter starting `-Wl` with: `-Wl,-rpath,/opt/openssl/lib`.
  54 There are more variations on less common systems.
  55
  56 You now have an installed OpenSSL under /opt/openssl which will not be
  57 used by any system programs.
  58
  59 When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
  60 choose the pkg-config approach in that file, but also tell Exim to add
  61 the relevant directory into the rpath stamped into the binary:
  62
  63     PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
  64
  65     SUPPORT_TLS=yes
  66     USE_OPENSSL_PC=openssl
  67     LDFLAGS+=-ldl -Wl,-rpath,/opt/openssl/lib
  68
  69 The -ldl is needed by OpenSSL 1.0.2+ on Linux and is not needed on most
  70 other platforms.  The LDFLAGS is needed because `pkg-config` doesn't know
  71 how to emit information about RPATH-stamping, but we can still leverage
  72 `pkg-config` for everything else.
  73
  74 Then build Exim:
  75
  76     make
  77     sudo make install
  78
  79
  80 Confirming
  81 ----------
  82
  83 Run:
  84
  85     exim -d-all+expand --version
  86
  87 and look for the `Library version: OpenSSL:` lines.
  88
  89 To look at the libraries _probably_ found by the linker, use:
  90
  91     ldd $(which exim)           # most platforms
  92     otool -L $(which exim)      # MacOS
  93
  94 although that does not correctly handle restrictions imposed upon
  95 executables which are setuid.
  96
  97 If the `chrpath` package is installed, then:
  98
  99     chrpath -l $(which exim)
 100
 101 will show the DT_RPATH stamped into the binary.
 102
 103 Your `binutils` package should come with `readelf`, so an alternative
 104 is to run:
 105
 106     readelf -d $(which exim) | grep RPATH
 107
 108 It is important to use `RPATH` and not `RUNPATH`!
 109
 110 The gory details about `RUNPATH` (skip unless interested):
 111 The OpenSSL library might be opened indirectly by some other library
 112 which Exim depends upon.  If the executable does have `RUNPATH` then
 113 that will inhibit using either of `RPATH` or `RUNPATH` from the
 114 executable for finding the OpenSSL library when that other library tries
 115 to load it.
 116 In fact, if the intermediate library has a `RUNPATH` stamped into it,
 117 then this will block `RPATH` too, and will create problems with Exim.
 118 If you're in such a situation, and those libraries were supplied to you
 119 instead of built by you, then you're reaching the limits of sane
 120 repairability and it's time to prioritize rebuilding your mail-server
 121 hosts to be a current OS release which natively pulls in an
 122 upstream-supported OpenSSL, or stick to the OS releases of Exim.
 123
 124
 125 Very Advanced
 126 -------------
 127
 128 You can not use $ORIGIN for portably packing OpenSSL in with Exim with
 129 normal Exim builds, because Exim is installed setuid which causes the
 130 runtime linker to ignore $ORIGIN in DT_RPATH.
 131
 132 _If_ following the steps for a non-setuid Exim, _then_ you can use:
 133
 134     EXTRALIBS_EXIM=-ldl '-Wl,-rpath,$$ORIGIN/../lib'
 135
 136 The doubled `$$` is needed for the make(1) layer and the quotes needed
 137 for the shell invoked by make(1) for calling the linker.
 138
 139 Note that this is sufficiently far outside normal that the build-system
 140 doesn't support it by default; you'll want to drop a symlink to the lib
 141 directory into the Exim release top-level directory, so that lib exists
 142 as a sibling to the build-$platform directory.
 143