Features

--------

- Two new security policies were added:
  RemoteUserInheritingACLSecurityPolicy and
  WhoInheritingACLSecurityPolicy.  These are security policies which
  take into account *all* ACLs defined in the lineage of a context
  rather than stopping at the first ACL found in a lineage.  See the
  "Security" chapter of the API documentation for more information.

- The API and narrative documentation dealing with security was
  changed to introduce the new "inheriting" security policy variants.

- Added glossary entry for "lineage".

Deprecations
------------

- The security policy previously named
  ``RepozeWhoIdentityACLSecurityPolicy`` now has the slightly saner
  name of ``WhoACLSecurityPolicy``.  A deprecation warning is emitted
  when this policy is imported under the "old" name; usually this is
  due to its use in ZCML within your application.  If you're getting
  this deprecation warning, change your ZCML to use the new name,
  e.g. change::

   <utility
     provides="repoze.bfg.interfaces.ISecurityPolicy"
     factory="repoze.bfg.security.RepozeWhoIdentityACLSecurityPolicy"
     />

  To::

   <utility
     provides="repoze.bfg.interfaces.ISecurityPolicy"
     factory="repoze.bfg.security.WhoACLSecurityPolicy"
     />

3 files changed, 74 insertions, 17 deletions

diff --git a/docs/api/security.rst b/docs/api/security.rst
index accc46205..5990f1809 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -32,6 +32,20 @@ Constants
     principal id (according to the security policy).  Its actual value
     is the string 'system.Authenticated'.
 
+.. attribute:: ALL_PERMISSIONS
+
+    An object that can be used as the ``permission`` member of an ACE
+    which matches all permissions unconditionally.  For example, an
+    ACE that uses ``ALL_PERMISSIONS`` might be composed like so:
+    ``('Deny', 'system.Everyone', ALL_PERMISSIONS)``.
+
+.. attribute:: DENY_ALL
+
+    A convenience shorthand ACE that defines ``('Deny',
+    'system.Everyone', ALL_PERMISSIONS)``.  This is often used as the
+    last ACE in an ACL in systems that use an "inheriting" security
+    policy, representing the concept "don't inherit any other ACEs".
+
 Return Values
 ~~~~~~~~~~~~~
 
@@ -64,6 +78,10 @@ Return Values
 Security Policies
 ~~~~~~~~~~~~~~~~~
 
-.. autofunction:: RepozeWhoIdentityACLSecurityPolicy
+.. autofunction:: WhoACLSecurityPolicy
+
+.. autofunction:: WhoInheritingACLSecurityPolicy
 
 .. autofunction:: RemoteUserACLSecurityPolicy
+
+.. autofunction:: RemoteUserInheritingACLSecurityPolicy
diff --git a/docs/glossary.rst b/docs/glossary.rst
index fc346252d..b55f8395c 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -332,3 +332,9 @@ Glossary
     is typically the physical root object (the object returned by the
     application root factory) unless :ref:`vhosting_chapter` is in
     use.
+  Lineage
+    An ordered sequence of objects based on a ":term:`location` -aware"
+    context.  The lineage of any given :term:`context` is composed of
+    itself, its parent, its parent's parent, and so on.  The order of
+    the sequence is context-first, then the parent of the context,
+    then its parent's parent, and so on.
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 87907730e..38335b6cd 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -25,26 +25,34 @@ However, if you add the following bit of code to your application's
 
    <utility
      provides="repoze.bfg.interfaces.ISecurityPolicy"
-     factory="repoze.bfg.security.RemoteUserACLSecurityPolicy"
+     factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
      />
 
 The above inscrutable stanza enables the
-``RemoteUserACLSecurityPolicy`` to be in effect for every request to
-your application.  The ``RemoteUserACLSecurityPolicy`` is a policy
-which compares the ``REMOTE_USER`` variable passed in the request's
-environment (as the sole :term:`principal`) against the principals
-present in any :term:`ACL` found in model data when attempting to call
-some :term:`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.
-
-.. note:: Another security policy also exists:
-   ``RepozeWhoIdentityACLSecurityPolicy``.  This policy uses principal
+``RemoteUserInheritingACLSecurityPolicy`` to be in effect for every
+request to your application.  The
+``RemoteUserInheritingACLSecurityPolicy`` is a policy which compares
+the ``REMOTE_USER`` variable passed in the request's environment (as
+the sole :term:`principal`) against the principals present in any
+:term:`ACL` found in model data when attempting to call some
+:term:`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.
+
+.. note:: Another "inheriting" security policy also exists:
+   ``WhoInheritingACLSecurityPolicy``.  This policy uses principal
    information found in the ``repoze.who.identity`` value set into the
    WSGI environment by the :term:`repoze.who` middleware rather than
-   ``REMOTE_USER`` information. This policy only works when
+   ``REMOTE_USER`` information. This policy only works properly when
    :term:`repoze.who` middleware is present in the WSGI pipeline.
 
+.. note:: "non-inheriting" security policy variants of the
+   (``WhoACLSecurityPolicy`` and ``RemoteUserACLSecurityPolicy``) also
+   exist.  These policies use the *first* ACL found as the canonical
+   ACL; they do not continue searching up the context lineage to find
+   "inherited" ACLs.  It is recommended that you use the inheriting
+   variants unless you need this feature.
+
 .. note:: See :ref:`security_policies_api_section` for more
    information about the features of the default security policies.
 
@@ -129,21 +137,46 @@ group, we can collapse this into a single ACE, as below.
 A principal is usually a user id, however it also may be a group id if
 your authentication system provides group information and the security
 policy is written to respect them.  The
-``RemoteUserACLSecurityPolicy`` does not respect group information.
+``RemoteUserInheritingACLSecurityPolicy`` does not respect group
+information.
 
 ACL Inheritance
 ---------------
 
-While the security policy is in place, if a model object does not have
+While any 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
+With *non-inheriting* security policy variants
+(e.g. ``WhoACLSecurityPolicy`` and ``RemoteUserACLSecurityPolicy``),
+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.
 
+With *inheriting* security policy variants
+(e.g. ``WhoInheritingACLSecurityPolicy`` and
+``RemoteUserInheritingACLSecurityPolicy``), *all* ACLs in the
+context's :term:`lineage` are consulted when determining whether
+access is allowed or denied.
+
+:ref:`security_policies_api_section` for more information about the
+features of the default security policies and the difference between
+the inheriting and non-inheriting variants.
+
+.. note:: It is recommended that you use the inheriting variant of a
+   security policy.  Inheriting variants of security policies make it
+   possible for you to form a security strategy based on context ACL
+   "inheritance" rather than needing to keep all information about an
+   object's security state in a single ACL attached to that object.
+   It's much easier to code applications that dynamically change ACLs
+   if ACL inheritance is used.  In reality, the non-inheriting
+   security policy variants exist only for backwards compatibility
+   with applications that used them in versions of :mod:`repoze.bfg`
+   before 0.8.  If this backwards compatibility was not required, the
+   non-inheriting variants probably just wouldn't exist.
+
 Location-Awareness
 ------------------