Mercurial > prosody-modules
annotate mod_s2s_auth_dane/README.markdown @ 2459:8e686bf63441
mod_net_dovecotauth: Rename variable to avoid name clash [luacheck]
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sun, 22 Jan 2017 04:47:06 +0100 |
| parents | 3d8e2480fae0 |
| children | 63fb612d6ec5 |
| 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 | |
| 66 ; The DANE TLSA records. These three are equivalent, you would use only one of them. | |
| 67 ; First, using symbolic names: | |
| 68 _5269._tcp.xmpp.example.com. 300 IN TLSA DANE-EE Cert SHA2-256 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 | |
| 69 ; Using numbers: | |
| 70 _5269._tcp.xmpp.example.com. 300 IN TLSA 3 0 1 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 | |
| 71 ; Raw binary format, should work even with very old DNS tools: | |
| 72 _5269._tcp.xmpp.example.com. 300 IN TYPE52 \# 35 030001E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 | |
| 73 | |
| 74 [List of DNSSEC and DANE | |
| 75 tools](http://www.internetsociety.org/deploy360/dnssec/tools/) | |
| 76 | |
| 77 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
|
78 =============== |
| 1803 | 79 |
|
1965
3d8e2480fae0
mod_s2s_auth_dane/README: DANE Operational Guidance got RFC'd
Kim Alvefur <zash@zash.se>
parents:
1960
diff
changeset
|
80 - [DANE Operational Guidance][rfc7671] |
| 1803 | 81 |
| 82 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
|
83 ============= |
| 1803 | 84 |
| 85 Requires 0.9 or above. |