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 Insecure versions and ciphers
  32 -----------------------------
  33
  34 Email delivery to MX hosts is usually done with automatic fallback to
  35 plaintext if TLS could not be negotiated.  There are good historical reasons
  36 for this.  You can and should avoid it by using DNSSEC for signing your DNS
  37 and publishing TLSA records, to enable "DANE" security.  This signals to
  38 senders that they should be able to verify your certificates, and that they
  39 should not fallback to cleartext.
  40
  41 In the absence of DANE, trying to increase the security of TLS by removing
  42 support for older generations of ciphers and protocols will actually _lower_
  43 the security, because the clients fallback to plaintext and retry anyway.  As
  44 a result, you should give serious thought to enabling older features which are
  45 no longer default in OpenSSL.
  46
  47 The examples below explicitly enable ssl3 and weak ciphers.
  48
  49 We don't like this, but reality doesn't care and is messy.
  50
  51
  52 Build
  53 -----
  54
  55 Extract the current source of OpenSSL.  Change into that directory.
  56
  57 This assumes that `/opt/openssl` is not in use.  If it is, pick
  58 something else.  `/opt/exim/openssl` perhaps.
  59
  60 If you pick a location shared amongst various local packages, such as
  61 `/usr/local` on Linux, then the new OpenSSL will be used by all of those
  62 packages.  If that's what you want, great!  If instead you want to
  63 ensure that only software you explicitly set to use the newer OpenSSL
  64 will try to use the new OpenSSL, then stick to something like
  65 `/opt/openssl`.
  66
  67     ./config --prefix=/opt/openssl --openssldir=/etc/ssl  \
  68         -L/opt/openssl/lib -Wl,-R/opt/openssl/lib         \
  69         enable-ssl-trace shared                           \
  70         enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers
  71     make
  72     make install
  73
  74 On some systems, the linker uses `-rpath` instead of `-R`; on such systems,
  75 replace the parameter starting `-Wl` with: `-Wl,-rpath,/opt/openssl/lib`.
  76 There are more variations on less common systems.
  77
  78 You now have an installed OpenSSL under /opt/openssl which will not be
  79 used by any system programs.
  80
  81 When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
  82 choose the pkg-config approach in that file, but also tell Exim to add
  83 the relevant directory into the rpath stamped into the binary:
  84
  85     PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
  86
  87     SUPPORT_TLS=yes
  88     USE_OPENSSL_PC=openssl
  89     LDFLAGS+=-ldl -Wl,-rpath,/opt/openssl/lib
  90
  91 The -ldl is needed by OpenSSL 1.0.2+ on Linux and is not needed on most
  92 other platforms.  The LDFLAGS is needed because `pkg-config` doesn't know
  93 how to emit information about RPATH-stamping, but we can still leverage
  94 `pkg-config` for everything else.
  95
  96 Then build Exim:
  97
  98     make
  99     sudo make install
 100
 101
 102 Confirming
 103 ----------
 104
 105 Run:
 106
 107     exim -d-all+expand --version
 108
 109 and look for the `Library version: OpenSSL:` lines.
 110
 111 To look at the libraries _probably_ found by the linker, use:
 112
 113     ldd $(which exim)           # most platforms
 114     otool -L $(which exim)      # MacOS
 115
 116 although that does not correctly handle restrictions imposed upon
 117 executables which are setuid.
 118
 119 If the `chrpath` package is installed, then:
 120
 121     chrpath -l $(which exim)
 122
 123 will show the DT_RPATH stamped into the binary.
 124
 125 Your `binutils` package should come with `readelf`, so an alternative
 126 is to run:
 127
 128     readelf -d $(which exim) | grep RPATH
 129
 130 It is important to use `RPATH` and not `RUNPATH`!
 131
 132 The gory details about `RUNPATH` (skip unless interested):
 133 The OpenSSL library might be opened indirectly by some other library
 134 which Exim depends upon.  If the executable does have `RUNPATH` then
 135 that will inhibit using either of `RPATH` or `RUNPATH` from the
 136 executable for finding the OpenSSL library when that other library tries
 137 to load it.
 138 In fact, if the intermediate library has a `RUNPATH` stamped into it,
 139 then this will block `RPATH` too, and will create problems with Exim.
 140 If you're in such a situation, and those libraries were supplied to you
 141 instead of built by you, then you're reaching the limits of sane
 142 repairability and it's time to prioritize rebuilding your mail-server
 143 hosts to be a current OS release which natively pulls in an
 144 upstream-supported OpenSSL, or stick to the OS releases of Exim.
 145
 146
 147 Very Advanced
 148 -------------
 149
 150 You can not use $ORIGIN for portably packing OpenSSL in with Exim with
 151 normal Exim builds, because Exim is installed setuid which causes the
 152 runtime linker to ignore $ORIGIN in DT_RPATH.
 153
 154 _If_ following the steps for a non-setuid Exim, _then_ you can use:
 155
 156     EXTRALIBS_EXIM=-ldl '-Wl,-rpath,$$ORIGIN/../lib'
 157
 158 The doubled `$$` is needed for the make(1) layer and the quotes needed
 159 for the shell invoked by make(1) for calling the linker.
 160
 161 Note that this is sufficiently far outside normal that the build-system
 162 doesn't support it by default; you'll want to drop a symlink to the lib
 163 directory into the Exim release top-level directory, so that lib exists
 164 as a sibling to the build-$platform directory.
 165