Mercurial > prosody-modules

annotate mod_s2s_auth_dane/README.markdown @ 3866:c0df50ce96f0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Handle internal http request errors early and then return Skips over attempted parsing of the payload which usually failed since the body is an error string like "connection refused", so this produced useless errors.
author Kim Alvefur <zash@zash.se>
date Sat, 25 Jan 2020 20:22:12 +0100
parents a6486881fe42
children daabba8fb45b
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:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 - 'Stage-Alpha'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 - 'Type-S2SAuth'
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
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 Compatibility
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
81 =============
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 Requires 0.9 or above.
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
84
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
85 Known issues
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
86 ============
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
87
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
88 - 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
89 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
90 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
91
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
92