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     ./config --prefix=/opt/openssl --openssldir=/etc/ssl  \
  40         -L/opt/openssl/lib -Wl,-R/opt/openssl/lib         \
  41         enable-ssl-trace
  42     make
  43     make install
  44
  45 You now have an installed OpenSSL under /opt/openssl which will not be
  46 used by any system programs.
  47
  48 When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
  49 choose the pkg-config approach in that file, but also tell Exim to add
  50 the relevant directory into the rpath stamped into the binary:
  51
  52     SUPPORT_TLS=yes
  53     USE_OPENSSL_PC=openssl
  54     EXTRALIBS_EXIM=-ldl -Wl,-rpath,/opt/openssl/lib
  55
  56 The -ldl is needed by OpenSSL 1.1+ on Linux and is not needed on most
  57 other platforms.
  58
  59 Then tell pkg-config how to find the configuration files for your new
  60 OpenSSL install, and build Exim:
  61
  62     export PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
  63     make
  64     sudo make install
  65
  66 (From Exim 4.89, you can put that `PKG_CONFIG_PATH` directly into
  67  your `Local/Makefile` file.)
  68
  69
  70 Confirming
  71 ----------
  72
  73 Run:
  74
  75     exim -d-all+expand --version
  76
  77 and look for the `Library version: OpenSSL:` lines.
  78
  79 To look at the libraries _probably_ found by the linker, use:
  80
  81     ldd $(which exim)           # most platforms
  82     otool -L $(which exim)      # MacOS
  83
  84 although that does not correctly handle restrictions imposed upon
  85 executables which are setuid.
  86
  87 If the `chrpath` package is installed, then:
  88
  89     chrpath -l $(which exim)
  90
  91 will show the DT_RPATH stamped into the binary.
  92
  93 Your `binutils` package should come with `readelf`, so an alternative
  94 is to run:
  95
  96     readelf -d $(which exim) | grep RPATH
  97
  98
  99 Very Advanced
 100 -------------
 101
 102 You can not use $ORIGIN for portably packing OpenSSL in with Exim with
 103 normal Exim builds, because Exim is installed setuid which causes the
 104 runtime linker to ignore $ORIGIN in DT_RPATH.
 105
 106 _If_ following the steps for a non-setuid Exim, _then_ you can use:
 107
 108     EXTRALIBS_EXIM=-ldl '-Wl,-rpath,$$ORIGIN/../lib'
 109
 110 The doubled `$$` is needed for the make(1) layer and the quotes needed
 111 for the shell invoked by make(1) for calling the linker.
 112
 113 Note that this is sufficiently far outside normal that the build-system
 114 doesn't support it by default; you'll want to drop a symlink to the lib
 115 directory into the Exim release top-level directory, so that lib exists
 116 as a sibling to the build-$platform directory.
 117