annotate mod_tls_policy/README.markdown @ 5553:67152838afbc

mod_http_oauth2: Improve error messages for URI properties Since there are separate validation checks for URI properties, including that they should use https, with better and more specific error reporting. Reverts 'luaPattern' to 'pattern' which is not currently supported by util.jsonschema, but allows anything that retrieves the schema over http to validate against it, should they wish to do so.
author Kim Alvefur <zash@zash.se>
date Sat, 17 Jun 2023 18:15:00 +0200
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