Mercurial > prosody-modules
annotate mod_s2s_auth_dane/README.markdown @ 3214:453ec2938153
mod_adhoc_dataforms_demo/README: Set a summary
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 03 Aug 2018 20:23:03 +0200 (2018-08-03) |
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 |