Annotate

INSTALL @ 13801:a5d5fefb8b68 13.0

mod_tls: Enable Prosody's certificate checking for incoming s2s connections (fixes #1916) (thanks Damian, Zash) Various options in Prosody allow control over the behaviour of the certificate verification process For example, some deployments choose to allow falling back to traditional "dialback" authentication (XEP-0220), while others verify via DANE, hard-coded fingerprints, or other custom plugins. Implementing this flexibility requires us to override OpenSSL's default certificate verification, to allow Prosody to verify the certificate itself, apply custom policies and make decisions based on the outcome. To enable our custom logic, we have to suppress OpenSSL's default behaviour of aborting the connection with a TLS alert message. With LuaSec, this can be achieved by using the verifyext "lsec_continue" flag. We also need to use the lsec_ignore_purpose flag, because XMPP s2s uses server certificates as "client" certificates (for mutual TLS verification in outgoing s2s connections). Commit 99d2100d2918 moved these settings out of the defaults and into mod_s2s, because we only really need these changes for s2s, and they should be opt-in, rather than automatically applied to all TLS services we offer. That commit was incomplete, because it only added the flags for incoming direct TLS connections. StartTLS connections are handled by mod_tls, which was not applying the lsec_* flags. It previously worked because they were already in the defaults. This resulted in incoming s2s connections with "invalid" certificates being aborted early by OpenSSL, even if settings such as `s2s_secure_auth = false` or DANE were present in the config. Outgoing s2s connections inherit verify "none" from the defaults, which means OpenSSL will receive the cert but will not terminate the connection when it is deemed invalid. This means we don't need lsec_continue there, and we also don't need lsec_ignore_purpose (because the remote peer is a "server"). Wondering why we can't just use verify "none" for incoming s2s? It's because in that mode, OpenSSL won't request a certificate from the peer for incoming connections. Setting verify "peer" is how you ask OpenSSL to request a certificate from the client, but also what triggers its built-in verification.
author Matthew Wild <mwild1@gmail.com>
date Tue, 01 Apr 2025 17:26:56 +0100
parent 12286:ad88732eea51
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5407
c9ff345a27e7 INSTALL: Update from wiki
Matthew Wild <mwild1@gmail.com>
parents: 4885
diff changeset
1 (This file was created from
7359
a5a080c12c96 Update every link to the documentation to use HTTPS
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 5407
diff changeset
2 https://prosody.im/doc/installing_from_source on 2013-03-31)
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
4 # Installing from source
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
5
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
6 ## Dependencies
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
7
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
8 There are a couple of development packages which Prosody needs installed
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
9 before you can build it. These are:
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
11 - The [Lua](http://lua.org/) library, version 5.4 recommended
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
12 - [OpenSSL](http://openssl.org/)
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
13 - String processing library, one of
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
14 - [ICU](https://icu.unicode.org/) (recommended)
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
15 - [GNU libidn](http://www.gnu.org/software/libidn/)
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
17 These can be installed on Debian/Ubuntu by running
12286
ad88732eea51 util.dependencies: Refer to 'apt' instead of 'apt-get'
Kim Alvefur <zash@zash.se>
parents: 12222
diff changeset
18 `apt build-dep prosody` or by installing the packages
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
19 `liblua5.4-dev`, `libicu-dev` and `libssl-dev`.
4885
8df3e709f8b7 INSTALL: Update with changes from wiki.
Kim Alvefur <zash@zash.se>
parents: 1192
diff changeset
20
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
21 On Mandriva try:
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
23 urpmi lua liblua-devel libidn-devel libopenssl-devel
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
25 On Mac OS X, if you have MacPorts installed, you can try:
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
26
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
27 sudo port install lua lua-luasocket lua-luasec lua-luaexpat
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
29 On other systems... good luck, but please let us know of the best way of
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
30 getting the dependencies for your system and we can add it here.
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
31
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
32 ## configure
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
34 The first step of building is to run the configure script. This creates
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
35 a file called 'config.unix' which is used by the next step to control
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
36 aspects of the build process.
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
38 ./configure
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
40 All options to configure can be seen by running
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
42 ./configure --help
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
43
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
44 ## make
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
45
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 Once you have run configure successfully, then you can simply run:
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 make
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 Simple? :-)
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
52 If you do happen to have problems at this stage, it is most likely due
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
53 to the build process not finding the dependencies. Ensure you have them
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
54 installed, and in the standard library paths for your system.
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 For more help, just ask ;-)
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 ==== install ====
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
59
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 At this stage you should be able to run Prosody simply with:
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 ./prosody
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
64 There is no problem with this, it is actually the easiest way to do
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
65 development, as it doesn't spread parts around your system, and you
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
66 can keep multiple versions around in their own directories without
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 conflict.
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 Should you wish to install it system-wide however, simply run:
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 sudo make install
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
12222
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
73 ...it will install into /usr/local/ by default. To change this you can
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
74 pass to the initial ./configure using the 'prefix' option, or edit
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
75 config.unix directly. If the new path doesn't require root permission to
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
76 write to, you also won't need (or want) to use 'sudo' in front of the
61592927335b INSTALL: Update from site version
Kim Alvefur <zash@zash.se>
parents: 7359
diff changeset
77 'make install'.
1192
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78
b1b42ce4f0f6 Finally add README and INSTALL files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 Have fun, and see you on Jabber!