[Zope-CVS] CVS: Products/VerboseSecurity - README.txt:1.1

[Shane Hathaway]

Update of /cvs-repository/Products/VerboseSecurity
In directory cvs.zope.org:/tmp/cvs-serv6979

Added Files:
	README.txt 
Log Message:
Added a README that explains what this product is, how to install it, and
the (minor) side effects.


=== Added File Products/VerboseSecurity/README.txt ===

Author
======

Shane Hathaway
Zope Corporation
shane at zope dot com


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

Zope has a fine-grained security model.  Zope 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.  Production sites should not reveal too
much about the site to those who are denied access, so the Zope
security policy's lack of verbosity is appropriate for such sites.
But site developers require complete details.

This product attempts to explain the complete reasoning for failed
access.  It shows what 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.

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.

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, which this product is not able
to patch at runtime.  So to enable the disable of permission names,
you need to get Zope to switch back to 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 see 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.  In the default configuration, however, 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 does not
reveal passwords, however.

- 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 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.