
Author
======

Shane Hathaway
Zope Corporation
shane at zope dot com


VerboseSecurity Product
=======================

Zope has a flexible, fine-grained security model that lets you
configure context-dependent mappings from users to roles and from
roles to permissions.  The model fits most organizations' needs and
has been used all over the world, but the flexibility sometimes comes
at a price of complexity.

One major difficulty in using the Zope security model is its lack of
clarity when access is denied.  Because production sites should not
reveal too much about the site to those who are denied access, the
lack of verbosity in the default Zope security policy is appropriate
for such sites.  But site developers need more details.

This product attempts to explain the complete reasoning for failed
access.  It shows what object was being accessed, what permission is
required to access it, what roles map to that permission in that
context, the executable object and its owner, the effective proxy
roles, and other pertinent information.  All of this information
appears in the exception message when access is denied.

This product is designed for Zope 2.6.  However, it should work with
Zope 2.4 and Zope 2.5 as well.  It is currently in development.


Installation
============

Unpack the product in your Zope Products folder.  The VerboseSecurity
product replaces the Zope security policy with the
"VerboseSecurityPolicy".

This product can only show permission names if it is able to
dynamically patch (or "monkey-patch") the Python version of the Zope
PermissionRole module.  Everything else works without the patch, but
the required permission name is probably the most useful piece of
information that VerboseSecurity exposes.

Zope 2.5 and 2.6 include a C version of the PermissionRole module.
This product can not dynamically patch the C version.  So to enable
the display of permission names, you need to get Zope to use the
Python version of the PermissionRole module.  Do this by putting the
following in your environment before starting Zope::

    ZOPE_SECURITY_POLICY=PYTHON

If you start Zope with the VerboseSecurity product installed but with
the C version of PermissionRole, VerboseSecurity will issue a warning in
the Zope log file.

The next time an Unauthorized exception occurs, you'll get a complete
explanation for the failed access.  If you're using Zope 2.6, you can
also see recent exceptions through the web using the error_log object.
Note, however, that in the default configuration, error_log will not
display Unauthorized exceptions.  Just remove "Unauthorized" from the
list of ignored exceptions.


Side effects
============

Like all products that dynamically patch Zope, there are a few side
effects:

- The speed of security checks, which occur quite frequently in Zope,
will be slower, especially when access is denied.  The difference is
unlikely to be noticeable during site development, however.

- The product reveals a lot of information about the structure of your
site, so it may not be appropriate for some production sites.  It is
unlikely to inadvertently reveal passwords, though.

- The product may sometimes append information about a previous
Unauthorized exception to a new, unrelated Unauthorized exception.
Zope makes it difficult to do the right thing here, but possible
solutions exist.

- The PermissionRole patch included in the product internally adds an
imaginary role to the roles computed for a permission.  The imaginary
role is a munged version of the permission name.  Consequently, it is
possible to assign users to this imaginary role.  This is an
interesting feature to have, since it potentially lets you bypass role
assignment and assign users directly to permissions.  But this feature
should not be regarded as standard, and it is not officially
supported.


