author | Kim Alvefur <zash@zash.se> |
Sat, 25 Jan 2020 01:31:49 +0100 | |
changeset 3861 | 8752e5b5dd08 |
parent 2497 | a6486881fe42 |
child 3994 | daabba8fb45b |
permissions | -rw-r--r-- |
1807 | 1 |
--- |
2 |
labels: |
|
3 |
- 'Stage-Alpha' |
|
4 |
- 'Type-S2SAuth' |
|
5 |
summary: S2S authentication using DANE |
|
6 |
... |
|
7 |
||
8 |
Introduction |
|
1840
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:
1807
diff
changeset
|
9 |
============ |
1807 | 10 |
|
1954
f118e419a712
mod_s2s_auth_dane/README: Add missing whitespace
Kim Alvefur <zash@zash.se>
parents:
1842
diff
changeset
|
11 |
This module implements DANE as described in [Using DNS Security |
1807 | 12 |
Extensions (DNSSEC) and DNS-based Authentication of Named Entities |
13 |
(DANE) as a Prooftype for XMPP Domain Name |
|
14 |
Associations](http://tools.ietf.org/html/draft-miller-xmpp-dnssec-prooftype). |
|
15 |
||
16 |
Dependencies |
|
1840
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:
1807
diff
changeset
|
17 |
============ |
1807 | 18 |
|
1842
1c6d04f012e9
mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents:
1841
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:
1841
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:
1841
diff
changeset
|
21 |
replacement is needed, such as [this |
1807 | 22 |
one](https://www.zash.se/luaunbound.html). |
23 |
||
1842
1c6d04f012e9
mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents:
1841
diff
changeset
|
24 |
LuaSec 0.5 or later is also required. |
1807 | 25 |
|
26 |
Configuration |
|
1840
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:
1807
diff
changeset
|
27 |
============= |
1807 | 28 |
|
1964
5f68a8928722
mod_s2s_auth_dane/README: Automagic links!
Kim Alvefur <zash@zash.se>
parents:
1954
diff
changeset
|
29 |
After [installing the module][doc:installing\_modules], just add it to |
1807 | 30 |
`modules_enabled`; |
31 |
||
32 |
modules_enabled = { |
|
33 |
... |
|
34 |
"s2s_auth_dane"; |
|
35 |
} |
|
36 |
||
1841
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
37 |
DANE Uses |
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
38 |
--------- |
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
39 |
|
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
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:
1840
diff
changeset
|
41 |
|
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
42 |
dane_uses = { "DANE-EE", "DANE-TA" } |
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
43 |
|
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
44 |
Use flag Description |
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
diff
changeset
|
45 |
----------- ------------------------------------------------------------------------------------------------------- |
6a3b48eded35
mod_s2s_auth_dane/README: Describe DANE uses
Kim Alvefur <zash@zash.se>
parents:
1840
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:
1840
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:
1840
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:
1840
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:
1840
diff
changeset
|
50 |
|
1807 | 51 |
DNS Setup |
1840
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:
1807
diff
changeset
|
52 |
========= |
1807 | 53 |
|
1842
1c6d04f012e9
mod_s2s_auth_dane/README: Note about LuaSec
Kim Alvefur <zash@zash.se>
parents:
1841
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:
1841
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:
1841
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:
1841
diff
changeset
|
57 |
`xmpp.example.com` serving the domain `example.com`. |
1807 | 58 |
|
59 |
$ORIGIN example.com. |
|
60 |
; Your standard SRV record |
|
61 |
_xmpp-server._tcp.example.com IN SRV 0 0 5269 xmpp.example.com. |
|
62 |
; IPv4 and IPv6 addresses |
|
63 |
xmpp.example.com. IN A 192.0.2.68 |
|
64 |
xmpp.example.com. IN AAAA 2001:0db8:0000:0000:4441:4e45:544c:5341 |
|
65 |
||
2496
63fb612d6ec5
mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents:
1969
diff
changeset
|
66 |
; The DANE TLSA records. |
1807 | 67 |
_5269._tcp.xmpp.example.com. 300 IN TLSA 3 0 1 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 |
2496
63fb612d6ec5
mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents:
1969
diff
changeset
|
68 |
|
63fb612d6ec5
mod_s2s_auth_dane/README: Simplify zone file examlpe
Kim Alvefur <zash@zash.se>
parents:
1969
diff
changeset
|
69 |
; If your zone file tooling does not support TLSA records, you can try the raw binary format: |
1807 | 70 |
_5269._tcp.xmpp.example.com. 300 IN TYPE52 \# 35 030001E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 |
71 |
||
72 |
[List of DNSSEC and DANE |
|
73 |
tools](http://www.internetsociety.org/deploy360/dnssec/tools/) |
|
74 |
||
75 |
Further reading |
|
1840
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:
1807
diff
changeset
|
76 |
=============== |
1807 | 77 |
|
1969
3d8e2480fae0
mod_s2s_auth_dane/README: DANE Operational Guidance got RFC'd
Kim Alvefur <zash@zash.se>
parents:
1964
diff
changeset
|
78 |
- [DANE Operational Guidance][rfc7671] |
1807 | 79 |
|
80 |
Compatibility |
|
1840
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:
1807
diff
changeset
|
81 |
============= |
1807 | 82 |
|
83 |
Requires 0.9 or above. |
|
2497
a6486881fe42
mod_s2s_auth_dane/README: Mention the race condition in the absence of util.async
Kim Alvefur <zash@zash.se>
parents:
2496
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:
2496
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:
2496
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:
2496
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:
2496
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:
2496
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:
2496
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:
2496
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:
2496
diff
changeset
|
92 |