Security docs.

4 files changed, 99 insertions, 0 deletions

diff --git a/docs/modules/index.rst b/docs/modules/index.rst
index 38cd5a29d..644b9fdf4 100644
--- a/docs/modules/index.rst
+++ b/docs/modules/index.rst
@@ -16,3 +16,5 @@ Sub-packages
    :maxdepth: 2
 
    router
+   security
+
diff --git a/docs/modules/security.rst b/docs/modules/security.rst
new file mode 100644
index 000000000..0a692e521
--- /dev/null
+++ b/docs/modules/security.rst
@@ -0,0 +1,53 @@
+.. _security_module:
+
+:mod:`repoze.bfg.security`
+==========================
+
+.. automodule:: repoze.bfg.security
+
+  .. autofunction:: has_permission
+
+  .. attribute:: Everyone
+
+    The special principal id named 'Everyone'.  This principal id is
+    granted to all requests.  Its actual value is the string
+    'system.Everyone'.
+
+  .. attribute:: Authenticated
+
+    The special principal id named 'Authenticated'.  This principal id
+    is granted to all requests which contain any other non-Everyone
+    principal id (according to the security policy).  Its actual value
+    is the string 'system.Authenticated'.
+
+  .. attribute:: Allow
+
+    The ACE "action" (the first element in an ACE e.g. ``(Allow, Everyone,
+    'read')`` that means allow access.  A sequence of ACEs makes up an
+    ACL.  It is a string, and it's actual value is "Allow".
+
+  .. attribute:: Deny
+
+    The ACE "action" (the first element in an ACE e.g. ``(Deny,
+    'george', 'read')`` that means deny access.  A sequence of ACEs
+    makes up an ACL.  It is a string, and it's actual value is "Deny".
+
+  :class:`RemoteUserACLSecurityPolicy`
+  ------------------------------------
+
+  .. autoclass:: RemoteUserACLSecurityPolicy
+
+     .. automethod:: permits
+
+  :class:`Denied`
+  ===============
+
+  .. autoclass:: Denied
+     :members:
+
+  :class:`Allowed`
+  ================
+
+  .. autoclass:: Allowed
+     :members:
+
diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index becf3e3e4..e9e0f175a 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -17,6 +17,8 @@ from repoze.bfg.interfaces import IRequest
 from repoze.bfg.registry import registry_manager
 
 class Router:
+    """ WSGI application which routes requests to 'view' code based on
+    a view registry"""
     def __init__(self, root_policy, registry):
         self.root_policy = root_policy
         self.registry = registry
@@ -51,6 +53,12 @@ class Router:
         return app(environ, start_response)
 
 def make_app(root_policy, package=None, filename='configure.zcml'):
+    """ Create a view registry based on the application's ZCML.  and
+    return a Router object, representing a repoze.bfg WSGI
+    application.  'root_policy' must be a callable that accepts an
+    environ and returns a graph root object.  'package' is the
+    dotted-Python-path packagename of the application, 'filename' is
+    the ZCML file that should be parsed to create the view registry."""
     from repoze.bfg.registry import makeRegistry
     registry = makeRegistry(filename, package)
     return Router(root_policy, registry)
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index 21a0a3f2a..6ee2d7d95 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -14,6 +14,13 @@ Allow = 'Allow'
 Deny = 'Deny'
 
 def has_permission(permission, context, request):
+    """ Provided a permission (a string or unicode object), a context
+    (a model instance) and a request object, return ``Allowed`` if the
+    permission is granted in this context to the user implied by the
+    request. Return ``Denied`` if this permission is not granted in
+    this context to this user.  This delegates to the current security
+    policy.  Return True unconditionally if no security policy has
+    been configured in this application."""
     policy = queryUtility(ISecurityPolicy)
     if policy is None:
         return True
@@ -55,6 +62,23 @@ class ACLAuthorizer(object):
         
 
 class RemoteUserACLSecurityPolicy(object):
+    """ A security policy which:
+
+    - examines the request.environ for the REMOTE_USER variable and
+      uses any non-false value as a principal id for this request.
+
+    - uses an ACL-based authorization model which attempts to find an
+      ACL on the context, and which returns ``Allowed`` from its
+      'permits' method if the ACL found grants access to the current
+      principal.  It returns ``Denied`` if permission was not granted
+      (either explicitly via a deny or implicitly by not finding a
+      matching ACE action).  An ACL is an ordered sequence of ACE
+      tuples, e.g.  ``[(Allow, Everyone, 'read'), (Deny, 'george',
+      'write')]``.  ACLs stored on model instance objects as their
+      __acl__ attribute will be used by the security machinery to
+      grant or deny access.
+
+    """
     implements(ISecurityPolicy)
     authorizer_factory = ACLAuthorizer
     
@@ -62,6 +86,8 @@ class RemoteUserACLSecurityPolicy(object):
         self.logger = logger
 
     def permits(self, context, request, permission):
+        """ Return ``Allowed`` if the policy permits access,
+        ``Denied`` if not."""
         userid = request.environ.get('REMOTE_USER', None)
         effective_principals = [Everyone]
 
@@ -94,6 +120,11 @@ class PermitsResult:
         return msg
 
 class Denied(PermitsResult):
+    """ The value type returned by an ACL denial.  It evaluates equal
+    to all boolean false types.  It also has attributes which indicate
+    which acl, ace, permission, principals, and context were involved
+    in the request.  Its __str__ method prints a summary of these
+    attributes for debugging purposes. """
     def __nonzero__(self):
         return False
 
@@ -102,6 +133,11 @@ class Denied(PermitsResult):
             return True
 
 class Allowed(PermitsResult):
+    """ The value type returned by an ACL denial.  It evaluates equal
+    to all boolean true types.  It also has attributes which indicate
+    which acl, ace, permission, principals, and context were involved
+    in the request.  Its __str__ method prints a summary of these
+    attributes for debugging purposes. """
     def __nonzero__(self):
         return True