Import Upstream version 4.89
[hcoop/debian/exim4.git] / doc / openssl.txt
CommitLineData
2813c06e
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
31Build
32-----
33
34Extract the current source of OpenSSL. Change into that directory.
35
36This assumes that `/opt/openssl` is not in use. If it is, pick
37something 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
45You now have an installed OpenSSL under /opt/openssl which will not be
46used by any system programs.
47
48When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
49choose the pkg-config approach in that file, but also tell Exim to add
50the 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
56The -ldl is needed by OpenSSL 1.1+ on Linux and is not needed on most
57other platforms.
58
59Then tell pkg-config how to find the configuration files for your new
60OpenSSL 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
70Confirming
71----------
72
73Run:
74
75 exim -d-all+expand --version
76
77and look for the `Library version: OpenSSL:` lines.
78
79To look at the libraries _probably_ found by the linker, use:
80
81 ldd $(which exim) # most platforms
82 otool -L $(which exim) # MacOS
83
84although that does not correctly handle restrictions imposed upon
85executables which are setuid.
86
87If the `chrpath` package is installed, then:
88
89 chrpath -l $(which exim)
90
91will show the DT_RPATH stamped into the binary.
92
93Your `binutils` package should come with `readelf`, so an alternative
94is to run:
95
96 readelf -d $(which exim) | grep RPATH
97
98
99Very Advanced
100-------------
101
102You can not use $ORIGIN for portably packing OpenSSL in with Exim with
103normal Exim builds, because Exim is installed setuid which causes the
104runtime 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
110The doubled `$$` is needed for the make(1) layer and the quotes needed
111for the shell invoked by make(1) for calling the linker.
112
113Note that this is sufficiently far outside normal that the build-system
114doesn't support it by default; you'll want to drop a symlink to the lib
115directory into the Exim release top-level directory, so that lib exists
116as a sibling to the build-$platform directory.
117