Mercurial > prosody-modules
annotate mod_s2s_auth_dane/README.markdown @ 3523:68beaf7fd7d6
luacheckrc: Copy line length setting from prosody
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sun, 31 Mar 2019 18:31:10 +0200 |
| parents | a6486881fe42 |
| children | daabba8fb45b |
| rev | line source |
|---|---|
| 1803 | 1 --- |
| 2 labels: | |
| 3 - 'Stage-Alpha' | |
| 4 - 'Type-S2SAuth' | |
| 5 summary: S2S authentication using DANE | |
| 6 ... | |
| 7 | |
| 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 | 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 | 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 | |
|
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 | 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 | 22 one](https://www.zash.se/luaunbound.html). |
| 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 | 25 |
| 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 | 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 | 30 `modules_enabled`; |
| 31 | |
| 32 modules_enabled = { | |
| 33 ... | |
| 34 "s2s_auth_dane"; | |
| 35 } | |
| 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 | 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 | 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 | 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 | |
|
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 | 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 | 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 | |
|
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 | 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 | 79 |
| 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 | 82 |
| 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 |