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"
     />

1 files changed, 19 insertions, 1 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