Import Upstream version 4.92
[hcoop/debian/exim4.git] / doc / openssl.txt
CommitLineData
2ea97746
CE
1OpenSSL
2=======
3
4The OpenSSL Project documents their supported releases at
5<https://www.openssl.org/policies/releasestrat.html>. The Exim
6Maintainers are unwilling to try to support Exim built with a
7version of a critical security library which is unmaintained.
8
9Thus as versions of OpenSSL become unsupported by OpenSSL, they become
10unsupported by Exim. Exim might build with older releases of OpenSSL,
11but that's risky behaviour.
12
13If your operating system vendor continues to ship an older version of
14OpenSSL and is diligently backporting security fixes, and they support
15Exim, then they will be backporting fixes to their packages of Exim too.
16If you wish to stick purely to packages of OpenSSL, then stick to
17packages of Exim too.
18
19If someone maintains "backports", that is worth exploring too.
20
21Note that a number of OSes use Exim with GnuTLS, not OpenSSL.
22
23Otherwise, assuming that your operating system has old OpenSSL, and you
24wish to use current Exim with OpenSSL, then you need to build and
25install your own, without interfering with the system libraries.
26Fortunately, this is easy.
27
28So this only applies if you build Exim yourself.
29
30
31Insecure versions and ciphers
32-----------------------------
33
34Email delivery to MX hosts is usually done with automatic fallback to
35plaintext if TLS could not be negotiated. There are good historical reasons
36for this. You can and should avoid it by using DNSSEC for signing your DNS
37and publishing TLSA records, to enable "DANE" security. This signals to
38senders that they should be able to verify your certificates, and that they
39should not fallback to cleartext.
40
41In the absence of DANE, trying to increase the security of TLS by removing
42support for older generations of ciphers and protocols will actually _lower_
43the security, because the clients fallback to plaintext and retry anyway. As
44a result, you should give serious thought to enabling older features which are
45no longer default in OpenSSL.
46
47The examples below explicitly enable ssl3 and weak ciphers.
48
49We don't like this, but reality doesn't care and is messy.
50
51
52Build
53-----
54
55Extract the current source of OpenSSL. Change into that directory.
56
57This assumes that `/opt/openssl` is not in use. If it is, pick
58something else. `/opt/exim/openssl` perhaps.
59
60If 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
62packages. If that's what you want, great! If instead you want to
63ensure that only software you explicitly set to use the newer OpenSSL
64will 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
74On some systems, the linker uses `-rpath` instead of `-R`; on such systems,
75replace the parameter starting `-Wl` with: `-Wl,-rpath,/opt/openssl/lib`.
76There are more variations on less common systems.
77
78You now have an installed OpenSSL under /opt/openssl which will not be
79used by any system programs.
80
81When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
82choose the pkg-config approach in that file, but also tell Exim to add
83the 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
91The -ldl is needed by OpenSSL 1.0.2+ on Linux and is not needed on most
92other platforms. The LDFLAGS is needed because `pkg-config` doesn't know
93how to emit information about RPATH-stamping, but we can still leverage
94`pkg-config` for everything else.
95
96Then build Exim:
97
98 make
99 sudo make install
100
101
102Confirming
103----------
104
105Run:
106
107 exim -d-all+expand --version
108
109and look for the `Library version: OpenSSL:` lines.
110
111To look at the libraries _probably_ found by the linker, use:
112
113 ldd $(which exim) # most platforms
114 otool -L $(which exim) # MacOS
115
116although that does not correctly handle restrictions imposed upon
117executables which are setuid.
118
119If the `chrpath` package is installed, then:
120
121 chrpath -l $(which exim)
122
123will show the DT_RPATH stamped into the binary.
124
125Your `binutils` package should come with `readelf`, so an alternative
126is to run:
127
128 readelf -d $(which exim) | grep RPATH
129
130It is important to use `RPATH` and not `RUNPATH`!
131
132The gory details about `RUNPATH` (skip unless interested):
133The OpenSSL library might be opened indirectly by some other library
134which Exim depends upon. If the executable does have `RUNPATH` then
135that will inhibit using either of `RPATH` or `RUNPATH` from the
136executable for finding the OpenSSL library when that other library tries
137to load it.
138In fact, if the intermediate library has a `RUNPATH` stamped into it,
139then this will block `RPATH` too, and will create problems with Exim.
140If you're in such a situation, and those libraries were supplied to you
141instead of built by you, then you're reaching the limits of sane
142repairability and it's time to prioritize rebuilding your mail-server
143hosts to be a current OS release which natively pulls in an
144upstream-supported OpenSSL, or stick to the OS releases of Exim.
145
146
147Very Advanced
148-------------
149
150You can not use $ORIGIN for portably packing OpenSSL in with Exim with
151normal Exim builds, because Exim is installed setuid which causes the
152runtime 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
158The doubled `$$` is needed for the make(1) layer and the quotes needed
159for the shell invoked by make(1) for calling the linker.
160
161Note that this is sufficiently far outside normal that the build-system
162doesn't support it by default; you'll want to drop a symlink to the lib
163directory into the Exim release top-level directory, so that lib exists
164as a sibling to the build-$platform directory.
165