Annotate

mod_tls_policy/README.markdown @ 1842:98ad01cc83cf

mod_tls_policy: Add README
author Kim Alvefur <zash@zash.se>
date Sat, 12 Sep 2015 21:02:33 +0200
child 1843:032b209bb8ff
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1842
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 % Cipher policy enforcement with application level error reporting
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 # Introduction
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 This module arose from discussions at the XMPP Summit about enforcing
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 better ciphers in TLS. It may seem attractive to disallow some
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 insecure ciphers or require forward secrecy, but doing this at the TLS
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 level would the user with an unhelpful "Encryption failed" message.
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 This module does this enforcing at the application level, allowing
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 better error messages.
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 # Configuration
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 First, download and add the module to `module_enabled`. Then you can
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 decide on what policy you want to have.
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 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
18
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 ``` lua
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 tls_policy = "FS" -- allow only ciphers that enable forward secrecy
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 ```
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 A more complicated example:
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 ``` lua
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 tls_policy = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 c2s = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 encryption = "AES"; -- Require AES (or AESGCM) encryption
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 protocol = "TLSv1.2"; -- and TLSv1.2
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 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
31 }
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 s2s = {
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 cipher = "AESGCM"; -- Require AESGCM ciphers
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 protocol = "TLSv1.[12]"; -- and TLSv1.1 or 1.2
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 authentication = "RSA"; -- with RSA authentication
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 };
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 }
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 # Compatibility
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 Requires LuaSec 0.5
98ad01cc83cf mod_tls_policy: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43