# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1442084553 -7200
# Node ID 98ad01cc83cf6d4b920002c346dd9d2d6e5c7b3c
# Parent  0a7053d14b430fc2b0cd2b26d464ea0f224cb6c7
mod_tls_policy: Add README

diff -r 0a7053d14b43 -r 98ad01cc83cf mod_tls_policy/README.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_tls_policy/README.markdown	Sat Sep 12 21:02:33 2015 +0200
@@ -0,0 +1,43 @@
+% Cipher policy enforcement with application level error reporting
+
+# Introduction
+
+This module arose from discussions at the XMPP Summit about enforcing 
+better ciphers in TLS.  It may seem attractive to disallow some 
+insecure ciphers or require forward secrecy, but doing this at the TLS 
+level would the user with an unhelpful "Encryption failed" message.  
+This module does this enforcing at the application level, allowing 
+better error messages.
+
+# Configuration
+
+First, download and add the module to `module_enabled`.  Then you can 
+decide on what policy you want to have.
+
+Requiring ciphers with forward secrecy is the most simple to set up.
+
+``` lua
+tls_policy = "FS" -- allow only ciphers that enable forward secrecy
+```
+
+A more complicated example:
+
+``` lua
+tls_policy = {
+  c2s = {
+    encryption = "AES"; -- Require AES (or AESGCM) encryption
+    protocol = "TLSv1.2"; -- and TLSv1.2
+    bits = 128; -- and at least 128 bits (FIXME: remember what this meant)
+  }
+  s2s = {
+    cipher = "AESGCM"; -- Require AESGCM ciphers
+    protocol = "TLSv1.[12]"; -- and TLSv1.1 or 1.2
+    authentication = "RSA"; -- with RSA authentication
+  };
+}
+```
+
+# Compatibility
+
+Requires LuaSec 0.5
+