Redocument the encryption module config.

1 files changed, 45 insertions, 34 deletions

diff --git a/data/anope.example.conf b/data/anope.example.conf
index e87d26ba8..3bc249d24 100644
--- a/data/anope.example.conf
+++ b/data/anope.example.conf
@@ -1228,51 +1228,62 @@ module
 /*
  * [RECOMMENDED] Encryption modules.
  *
- * The encryption modules are used when dealing with passwords. This determines how
- * the passwords are stored in the databases, and does not add any security as
- * far as transmitting passwords over the network goes.
+ * The encryption modules are used when dealing with passwords. This determines
+ * how the passwords are stored in the databases.
  *
- * Without any encryption modules loaded users will not be able to authenticate unless
- * there is another module loaded that provides authentication checking, such as
- * ldap_authentication or sql_authentication.
- *
- * With enc_none, passwords will be stored in plain text, allowing for passwords
- * to be recovered later but it isn't secure and therefore is not recommended.
- *
- * The other encryption modules use one-way encryption, so the passwords can not
- * be recovered later if those are used.
- *
- * The first encryption module loaded is the primary encryption module. All new passwords are
- * encrypted by this module. Old passwords stored in another encryption method are
- * automatically re-encrypted by the primary encryption module on next identify.
+ * The first encryption module loaded is the primary encryption module. All new
+ * passwords are encrypted by this module. Old passwords encrypted with another
+ * encryption method are automatically re-encrypted with the primary encryption
+ * module the next time the user identifies.
+ */
+
+/*
+ * enc_sha2
  *
- * enc_md5, enc_sha1, and enc_old are deprecated, and are provided for users
- * to upgrade to a newer encryption module. Do not use them as the primary
- * encryption module. They will be removed in a future release.
+ * Provides support for encrypting passwords using the HMAC-SHA-2 algorithm. See
+ * https://en.wikipedia.org/wiki/SHA-2 and https://en.wikipedia.org/wiki/HMAC
+ * for more information.
+ */
+module
+{
+	name = "enc_sha2"
+
+	/** The sub-algorithm to use. Can be set to sha224 for SHA-224, sha256 for
+	 * SHA-256, sha284 for SHA-384 or sha512 to SHA-512. Defaults to sha256.
+	 */
+	#algorithm = "sha256"
+}
+
+/*
+ * enc_bcrypt
  *
+ * Provides support for encrypting passwords using the Bcrypt algorithm. See
+ * https://en.wikipedia.org/wiki/Bcrypt for more information.
  */
+#module
+{
+	name = "enc_bcrypt"
 
-#module { name = "enc_bcrypt" }
-module { name = "enc_sha2" }
+	/** The number of Bcrypt rounds to perform on passwords. Can be set to any
+	 * number between 10 and 32 but higher numbers are more CPU intensive and
+	 * may impact performance.
+	 */
+	#rounds = 10
+}
 
- /*
- * [DEPRECATED] Deprecated encryption modules. You can only use these for compatibility with
- * old databases and will need to load one of the above modules as your primary encryption
- * module.
-  */
+/*
+ * [DEPRECATED] enc_md5, enc_none, enc_old, enc_sha1, enc_sha256
+ *
+ * These modules are deprecated can *ONLY* be used as a secondary encryption
+ * module to retain compatibility with old Anope databases. They will be removed
+ * in a future release.
+ */
 #module { name = "enc_md5" }
 #module { name = "enc_none" }
+#module { name = "enc_old" }
 #module { name = "enc_sha1" }
 #module { name = "enc_sha256" }
 
-/*
- * enc_old is Anope's previous (broken) MD5 implementation used from 1.4.x to 1.7.16.
- * If your databases were made using that module, load it here to allow conversion to the primary
- * encryption method.
- */
-#module { name = "enc_old" }
-
-
 /* Extra (optional) modules. */
 include
 {