annotate mod_tls_policy/README.markdown @ 5256:44f7edd4f845

mod_http_oauth2: Reject non-local hosts in more code paths We're not issuing tokens for users on remote hosts, we can't even authenticate them since they're remote. Thus the host is always the local module.host so no need to pass around the host in most cases or use it for anything but enforcing the same host.
author Kim Alvefur <zash@zash.se>
date Thu, 16 Mar 2023 17:52:10 +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