194ae7cf88435667b19cda03de0cef8e512f75ff
[users/jgh/exim.git] / 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 shared
42     make
43     make install
44
45 On some systems, the linker uses `-rpath` instead of `-R`; on such systems,
46 replace the parameter starting `-Wl` with: `-Wl,-rpath,/opt/openssl/lib`.
47 There are more variations on less common systems.
48
49 You now have an installed OpenSSL under /opt/openssl which will not be
50 used by any system programs.
51
52 When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
53 choose the pkg-config approach in that file, but also tell Exim to add
54 the relevant directory into the rpath stamped into the binary:
55
56     PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
57
58     SUPPORT_TLS=yes
59     USE_OPENSSL_PC=openssl
60     LDFLAGS+=-ldl -Wl,-rpath,/opt/openssl/lib
61
62 [jgh: I've see /usr/local/lib used]
63
64 The -ldl is needed by OpenSSL 1.0.2+ on Linux and is not needed on most
65 other platforms.  The LDFLAGS is needed because `pkg-config` doesn't know
66 how to emit information about RPATH-stamping, but we can still leverage
67 `pkg-config` for everything else.
68
69 Then build Exim:
70
71     make
72     sudo make install
73
74
75 Confirming
76 ----------
77
78 Run:
79
80     exim -d-all+expand --version
81
82 and look for the `Library version: OpenSSL:` lines.
83
84 To look at the libraries _probably_ found by the linker, use:
85
86     ldd $(which exim)           # most platforms
87     otool -L $(which exim)      # MacOS
88
89 although that does not correctly handle restrictions imposed upon
90 executables which are setuid.
91
92 If the `chrpath` package is installed, then:
93
94     chrpath -l $(which exim)
95
96 will show the DT_RPATH stamped into the binary.
97
98 Your `binutils` package should come with `readelf`, so an alternative
99 is to run:
100
101     readelf -d $(which exim) | grep RPATH
102
103 [jgh: I've seen that spelled RUNPATH]
104
105 Very Advanced
106 -------------
107
108 You can not use $ORIGIN for portably packing OpenSSL in with Exim with
109 normal Exim builds, because Exim is installed setuid which causes the
110 runtime linker to ignore $ORIGIN in DT_RPATH.
111
112 _If_ following the steps for a non-setuid Exim, _then_ you can use:
113
114     EXTRALIBS_EXIM=-ldl '-Wl,-rpath,$$ORIGIN/../lib'
115
116 The doubled `$$` is needed for the make(1) layer and the quotes needed
117 for the shell invoked by make(1) for calling the linker.
118
119 Note that this is sufficiently far outside normal that the build-system
120 doesn't support it by default; you'll want to drop a symlink to the lib
121 directory into the Exim release top-level directory, so that lib exists
122 as a sibling to the build-$platform directory.
123