annotate mod_tls_policy/README.markdown @ 2906:d9603b555be2

luacheckrc: Forget about the _M global
author Kim Alvefur <zash@zash.se>
date Wed, 07 Mar 2018 18:15:31 +0100
parents ad24f8993385
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1845
ad24f8993385 mod_tls_policy/README: Fix summary so modules.prosody.im understands it
Kim Alvefur <zash@zash.se>
parents: 1843
diff changeset
1 ---
ad24f8993385 mod_tls_policy/README: Fix summary so modules.prosody.im understands it
Kim Alvefur <zash@zash.se>
parents: 1843
diff changeset
2 summary: Cipher policy enforcement with application level error reporting
ad24f8993385 mod_tls_policy/README: Fix summary so modules.prosody.im understands it
Kim Alvefur <zash@zash.se>
parents: 1843
diff changeset
3 ...
1842
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 # Introduction
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1843
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
7 This module arose from discussions at the XMPP Summit about enforcing
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
8 better ciphers in TLS. It may seem attractive to disallow some insecure
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
9 ciphers or require forward secrecy, but doing this at the TLS level
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
10 would the user with an unhelpful "Encryption failed" message. This
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
11 module does this enforcing at the application level, allowing better
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
12 error messages.
1842
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 # Configuration
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
1843
032b209bb8ff mod_tls_policy/README: Reflow and strip trailing whitespace (pandoc thougt it meant explicit line breaks)
Kim Alvefur <zash@zash.se>
parents: 1842
diff changeset
16 First, download and add the module to `module_enabled`. Then you can
1842
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 decide on what policy you want to have.
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 Requiring ciphers with forward secrecy is the most simple to set up.
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 ``` lua
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 tls_policy = "FS" -- allow only ciphers that enable forward secrecy
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 ```
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 A more complicated example:
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 ``` lua
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 tls_policy = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 c2s = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 encryption = "AES"; -- Require AES (or AESGCM) encryption
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 protocol = "TLSv1.2"; -- and TLSv1.2
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 bits = 128; -- and at least 128 bits (FIXME: remember what this meant)
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 }
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 s2s = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 cipher = "AESGCM"; -- Require AESGCM ciphers
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 protocol = "TLSv1.[12]"; -- and TLSv1.1 or 1.2
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 authentication = "RSA"; -- with RSA authentication
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 };
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 }
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 ```
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 # Compatibility
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44 Requires LuaSec 0.5
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45