ACL stuff.

1 files changed, 96 insertions, 5 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 3869d6e7a..5566d7c28 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -12,7 +12,7 @@ Jargon
 Permission
 
   A string or unicode object that represents an action being taken
-  against a context.  For example, 'read', or 'view_blog_entries'.
+  against a context.  For example, ``read``, or ``view_blog_entries``.
 
 ACE
 
@@ -21,8 +21,8 @@ ACE
   describes three things: an *action* (one of either ``Allow`` or
   ``Deny``), a *principal* (a string describing a user or group), and
   a *permission*.  For example the ACE, ``(Allow, 'bob', 'read')`` is
-  a member of an ACL that indicates that the principal 'bob' is
-  allowed the permission 'read' against the context the ACL is
+  a member of an ACL that indicates that the principal ``bob`` is
+  allowed the permission ``read`` against the context the ACL is
   attached to.
 
 ACL
@@ -92,5 +92,96 @@ data when attempting to call some *view*.  The policy either allows
 the view that the permission was declared for to be called, or returns
 a ``401 Unathorized`` response code to the upstream WSGI server.
 
-
-
+Protecting Views with Permissions
+---------------------------------
+
+You declaratively protected a particular view with a permisson via the
+``configure.zcml`` application registry.  For example, the following
+declaration protects the view named "add_entry.html" when invoked
+against an IBlog context with the ``add`` permission::
+
+  <bfg:view
+      for=".models.IBlog"
+      view=".views.blog_entry_add_view"
+      name="add_entry.html"
+      permission="add"
+      />
+
+If a security policy is in place when this view is found during normal
+application operations, the user will need to possess the ``add``
+permission against the context to be able to invoke the
+``blog_entry_add_view`` view.
+
+Permission names are just strings.  They hold no special significance
+to the system.  You can name permissions whatever you like.
+
+Assigning ACLs to your Model Objects
+------------------------------------
+
+When ``repoze.bfg`` determines whether a user possesses a particular
+permission in a context, it examines the ACL associated with the
+context.  An ACL is associated with a context by virtue of the
+``__acl__`` attribute of the model object representing the context.
+This attribute can be defined on the model *instance* (if you need
+instance-level security), or it can be defined on the model *class*
+(if you just need type-level security).
+
+For example, an ACL might be attached to model for a blog via its
+class::
+
+  from repoze.bfg.security import Everyone
+  from repoze.bfg.security import Allow
+  from zope.location.interfaces import ILocation
+  from zope.location.location import Location
+
+  class IBlog(Interface):
+      pass
+
+  class Blog(dict, Location):
+      __acl__ = [
+          (Allow, Everyone, 'view'),
+          (Allow, 'group:editors', 'add'),
+          (Allow, 'group:editors', 'edit'),
+          ]
+      implements(IBlog, ILocation)
+
+The above ACL indicates that the Everyone principal (a system-defined
+principal) is allowed to view the blog, the ``group:editors``
+principal is allowed to add to and edit the blog.
+
+ACL Inheritance
+---------------
+
+While the security policy is in place, if a model object does not have
+an ACL when it is the context, its *parent* is consulted for an ACL.
+If that object does not have an ACL, *its* parent is consulted for an
+ACL, ad infinitum, until we've reached the root and there are no more
+parents left.
+
+The *first* ACL found by the security policy will be used as the
+effective ACL.  No combination of ACLs found during traversal or
+backtracking is done.
+
+Location-Awareness
+------------------
+
+In order to allow the security machinery to perform ACL inheritance,
+model objects should provide *location-awareness*.
+
+Objects have parents when they define an ``__parent__`` attribute
+which points at their parent object.  The root object's ``__parent__``
+is ``None``.  An object with a ``__parent__`` attribute and a
+``__name__`` attribute is said to be *location-aware*.
+
+If the root object in a ``repoze.bfg`` application declares that it
+implements the ``ILocation`` interface, it is assumed that the objects
+in the rest of the model are location-aware.  Even if they are not
+explictly, if the root object is marked as ``ILocation``, the bfg
+framework will wrap each object during traversal in a *location
+proxy*, which will wrap each object found during traversal in a proxy
+object that has both the ``__name__`` and ``__parent__`` attributes,
+but otherwise acts the same as your model object.
+
+You can of course supply ``__name__`` and ``__parent__`` attributes
+explicitly on all of your model objects, and no location proxying will
+be performed.