Mercurial > prosody-modules

annotate mod_s2s_auth_dane/README.markdown @ 5668:ecfd7aece33b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_measure_modules: Report module statuses via OpenMetrics Someone in the chat asked about a health check endpoint, which reminded me of mod_http_status, which provides access to module statuses with full details. After that, this idea came about, which seems natural. As noted in the README, it could be used to monitor that critical modules are in fact loaded correctly. As more modules use the status API, the more useful this module and mod_http_status becomes.
author Kim Alvefur <zash@zash.se>
date Fri, 06 Oct 2023 18:34:39 +0200
parents 83afe4078e6e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 labels:
5120
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
3 - Stage-Broken
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
4 - Type-S2SAuth
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 summary: S2S authentication using DANE
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 ...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 Introduction
1836
5113f8ff6712 mod_s2s_auth_dane/README: Bump heading levels (modules.prosody.im decreases them one step) and fix some missing spaces
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
9 ============
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10
1950
f118e419a712 mod_s2s_auth_dane/README: Add missing whitespace
Kim Alvefur <zash@zash.se>
parents: 1838
diff changeset
11 This module implements DANE as described in [Using DNS Security
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 Extensions (DNSSEC) and DNS-based Authentication of Named Entities
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 (DANE) as a Prooftype for XMPP Domain Name
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 Associations](http://tools.ietf.org/html/draft-miller-xmpp-dnssec-prooftype).
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 Dependencies
1836
5113f8ff6712 mod_s2s_auth_dane/README: Bump heading levels (modules.prosody.im decreases them one step) and fix some missing spaces
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
17 ============
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
1838
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
19 This module requires a DNSSEC aware DNS resolver. Prosodys internal DNS
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
20 module does not support DNSSEC. Therefore, to use this module, a
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
21 replacement is needed, such as [this
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 one](https://www.zash.se/luaunbound.html).
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
1838
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
24 LuaSec 0.5 or later is also required.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 Configuration
1836
5113f8ff6712 mod_s2s_auth_dane/README: Bump heading levels (modules.prosody.im decreases them one step) and fix some missing spaces
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
27 =============
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28
1960
5f68a8928722 mod_s2s_auth_dane/README: Automagic links!
Kim Alvefur <zash@zash.se>
parents: 1950
diff changeset
29 After [installing the module][doc:installing\_modules], just add it to
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 `modules_enabled`;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 modules_enabled = {
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 ...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 "s2s_auth_dane";
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 }
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
1837
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
37 DANE Uses
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
38 ---------
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
39
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
40 By default, only DANE uses are enabled.
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
41
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
42 dane_uses = { "DANE-EE", "DANE-TA" }
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
43
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
44 Use flag Description
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
45 ----------- -------------------------------------------------------------------------------------------------------
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
46 `DANE-EE` Most simple use, usually a fingerprint of the full certificate or public key used the service
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
47 `DANE-TA` Fingerprint of a certificate or public key that has been used to issue the service certificate
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
48 `PKIX-EE` Like `DANE-EE` but the certificate must also pass normal PKIX trust checks (ie standard certificates)
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
49 `PKIX-TA` Like `DANE-TA` but must also pass normal PKIX trust checks (ie standard certificates)
6a3b48eded35 mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents: 1836
diff changeset
50
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 DNS Setup
1836
5113f8ff6712 mod_s2s_auth_dane/README: Bump heading levels (modules.prosody.im decreases them one step) and fix some missing spaces
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
52 =========
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53
1838
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
54 In order for other services to verify your site using using this plugin,
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
55 you need to publish TLSA records (and they need to have this plugin).
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
56 Here's an example using `DANE-EE Cert SHA2-256` for a host named
1c6d04f012e9 mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents: 1837
diff changeset
57 `xmpp.example.com` serving the domain `example.com`.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 $ORIGIN example.com.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 ; Your standard SRV record
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 _xmpp-server._tcp.example.com IN SRV 0 0 5269 xmpp.example.com.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 ; IPv4 and IPv6 addresses
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63 xmpp.example.com. IN A 192.0.2.68
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 xmpp.example.com. IN AAAA 2001:0db8:0000:0000:4441:4e45:544c:5341
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
2492
63fb612d6ec5 mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents: 1965
diff changeset
66 ; The DANE TLSA records.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 _5269._tcp.xmpp.example.com. 300 IN TLSA 3 0 1 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855
2492
63fb612d6ec5 mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents: 1965
diff changeset
68
63fb612d6ec5 mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents: 1965
diff changeset
69 ; If your zone file tooling does not support TLSA records, you can try the raw binary format:
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 _5269._tcp.xmpp.example.com. 300 IN TYPE52 \# 35 030001E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 [List of DNSSEC and DANE
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 tools](http://www.internetsociety.org/deploy360/dnssec/tools/)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 Further reading
1836
5113f8ff6712 mod_s2s_auth_dane/README: Bump heading levels (modules.prosody.im decreases them one step) and fix some missing spaces
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
76 ===============
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77
1965
3d8e2480fae0 mod_s2s_auth_dane/README: DANE Operational Guidance got RFC'd
Kim Alvefur <zash@zash.se>
parents: 1960
diff changeset
78 - [DANE Operational Guidance][rfc7671]
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
5120
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
80 # Compatibility
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81
5120
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
82 version status
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
83 --------- ------------
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
84 trunk broken[^1]
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
85 0.12 broken
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
86 0.11 works
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
87 0.10 works
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
88 0.9 works
3990
daabba8fb45b mod_s2s_auth_dane: It broke :(
Kim Alvefur <zash@zash.se>
parents: 2493
diff changeset
89
3991
eb56e743abe8 mod_s2s_auth_dane: Fix markdown link syntax
Kim Alvefur <zash@zash.se>
parents: 3990
diff changeset
90 **Broken** since [trunk revision 756b8821007a](https://hg.prosody.im/trunk/rev/756b8821007a).
2493
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
91
5120
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
92 # Known issues
2493
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
93
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
94 - A race condition between the DANE lookup and completion of the TLS
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
95 handshake may cause a crash. This does not happen in **trunk**
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
96 thanks to better async support.
a6486881fe42 mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents: 2492
diff changeset
97
5120
83afe4078e6e mod_s2s_auth_dane: Update Compatibility chart (doesn't work anymore)
Kim Alvefur <zash@zash.se>
parents: 3991
diff changeset
98 [^1]: since [756b8821007a](https://hg.prosody.im/trunk/rev/756b8821007a)