Improve documentation

radicale/auth/__init__.py

@@ -18,39 +18,13 @@
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
 """
-Authentication management.
+Authentication module.
 
-Default is htpasswd authentication.
+Authentication is based on usernames and passwords. If something more
+advanced is needed an external WSGI server or reverse proxy can be used
+(see ``remote_user`` or ``http_x_remote_user`` backend).
 
-Apache's htpasswd command (httpd.apache.org/docs/programs/htpasswd.html)
-manages a file for storing user credentials. It can encrypt passwords using
-different methods, e.g. BCRYPT, MD5-APR1 (a version of MD5 modified for
-Apache), SHA1, or by using the system's CRYPT routine. The CRYPT and SHA1
-encryption methods implemented by htpasswd are considered as insecure. MD5-APR1
-provides medium security as of 2015. Only BCRYPT can be considered secure by
-current standards.
-
-MD5-APR1-encrypted credentials can be written by all versions of htpasswd (it
-is the default, in fact), whereas BCRYPT requires htpasswd 2.4.x or newer.
-
-The `is_authenticated(user, password)` function provided by this module
-verifies the user-given credentials by parsing the htpasswd credential file
-pointed to by the ``htpasswd_filename`` configuration value while assuming
-the password encryption method specified via the ``htpasswd_encryption``
-configuration value.
-
-The following htpasswd password encrpytion methods are supported by Radicale
-out-of-the-box:
-
-    - plain-text (created by htpasswd -p...) -- INSECURE
-    - CRYPT      (created by htpasswd -d...) -- INSECURE
-    - SHA1       (created by htpasswd -s...) -- INSECURE
-
-When passlib (https://pypi.python.org/pypi/passlib) is importable, the
-following significantly more secure schemes are parsable by Radicale:
-
-    - MD5-APR1   (htpasswd -m...) -- htpasswd's default method
-    - BCRYPT     (htpasswd -B...) -- Requires htpasswd 2.4.x
+Take a look at the class ``BaseAuth`` if you want to implement your own.
 
 """
 

radicale/auth/htpasswd.py

@@ -17,6 +17,41 @@
 # You should have received a copy of the GNU General Public License
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+Authentication backend that checks credentials with a htpasswd file.
+
+Apache's htpasswd command (httpd.apache.org/docs/programs/htpasswd.html)
+manages a file for storing user credentials. It can encrypt passwords using
+different methods, e.g. BCRYPT, MD5-APR1 (a version of MD5 modified for
+Apache), SHA1, or by using the system's CRYPT routine. The CRYPT and SHA1
+encryption methods implemented by htpasswd are considered as insecure. MD5-APR1
+provides medium security as of 2015. Only BCRYPT can be considered secure by
+current standards.
+
+MD5-APR1-encrypted credentials can be written by all versions of htpasswd (it
+is the default, in fact), whereas BCRYPT requires htpasswd 2.4.x or newer.
+
+The `is_authenticated(user, password)` function provided by this module
+verifies the user-given credentials by parsing the htpasswd credential file
+pointed to by the ``htpasswd_filename`` configuration value while assuming
+the password encryption method specified via the ``htpasswd_encryption``
+configuration value.
+
+The following htpasswd password encrpytion methods are supported by Radicale
+out-of-the-box:
+
+    - plain-text (created by htpasswd -p...) -- INSECURE
+    - CRYPT      (created by htpasswd -d...) -- INSECURE
+    - SHA1       (created by htpasswd -s...) -- INSECURE
+
+When passlib (https://pypi.python.org/pypi/passlib) is importable, the
+following significantly more secure schemes are parsable by Radicale:
+
+    - MD5-APR1   (htpasswd -m...) -- htpasswd's default method
+    - BCRYPT     (htpasswd -B...) -- Requires htpasswd 2.4.x
+
+"""
+
 import base64
 import functools
 import hashlib

radicale/auth/http_x_remote_user.py

@@ -17,6 +17,15 @@
 # You should have received a copy of the GNU General Public License
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+Authentication backend that takes the username from the
+``HTTP_X_REMOTE_USER`` header.
+
+It's intended for use with a reverse proxy. Be aware as this will be insecure
+if the reverse proxy is not configured properly.
+
+"""
+
 import radicale.auth.none as none
 
 

radicale/auth/none.py

@@ -17,6 +17,11 @@
 # You should have received a copy of the GNU General Public License
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+A dummy backend that accepts any username and password.
+
+"""
+
 from radicale import auth
 
 

radicale/auth/remote_user.py

@@ -17,6 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+Authentication backend that takes the username from the ``REMOTE_USER``
+WSGI environment variable.
+
+It's intended for use with an external WSGI server.
+
+"""
+
 import radicale.auth.none as none