[[PageOutline]]

= [source:sandbox/pycon/security Security Sandbox] =

This sandbox aims at adding a finer grained control for the TracPermissions system.
 * Some related tickets: #654, #834, #948, #1316

The permission policy system has been [source:sandbox/pycon/security rewritten] on top of the ''[WikiContext Context]'' objects. 

The Wiki system, a significant part of the Ticket system and the attachment subsystem
are now using the new permission policy engine. 

 * View the revision [log:sandbox/pycon/security log]
 * See [diff:trunk@5420//sandbox/pycon/security@5421 differences] for Trac [milestone:0.11]dev
 * See [diff:trunk@3353//sandbox/pycon/security@3354 patch] for Trac [milestone:0.10]dev (initial implementation)

== 1000 ' View ==

 * Add an interface (`IPermissionPolicy`) for checking a users permission to access [WikiContext Trac resources].
 * Convert the current permission system to a plugin (`DefaultPermissionPolicy`).
 * Modify `PermissionCache` to cache the fine-grained policy check results (still needs some cleanup).
 * Convert each module to use fine-grained permissions (only the Wiki module has been converted so far).
 * API is backwards compatible.
 * Security policies can be "stacked".

== API ==

{{{
#!python
class IPermissionPolicy(Interface):
    """A security policy provider."""
    def check_permission(req, username, action, context):
        """Check that username can perform action in context.

        Must return True if action is allowed, False if action is denied, or
        None if indifferent.

        NOTE: req is passed in addition to context, as context is likely to be
        refactored to remove this."""
}}}

== Testing the features ==

You can check the source out from [http://svn.edgewall.com/repos/trac/sandbox/pycon/security here] using Subversion.

An example policy based on an Authz-style system has been added: 
see [source:sandbox/pycon/security/sample-plugins/authz_policy.py].
 - copy this file in your plugins directory
 - install genshi
 - plonk''(sic)'' a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere 
 - update your `trac.ini`:
{{{
[trac]
...
permission_policies = AuthzPolicy

[authz_policy]
authz_file = /some/trac/env/conf/authzpolicy.conf

[components]
...
authz_policy = enabled
}}}
 - Finally, restart your web server.

Note that the order in which permission policies are specified is quite critical, 
as policies will be examined in the given sequence.
A policy will return either `True`, `False` or `None` for a givein permission check.
Only if the return value is `None` will the ''next'' permission policy be consulted.
If no policy explicitly grants the permission, the final result will be `False` 
(i.e. no permission).

For example, if the authz_file contains:
{{{
[wiki:WikiStart]
* = VIEW

[wiki:PrivatePage]
john = VIEW
* =
}}}
and the default permissions are set like this:
{{{
john           WIKI_VIEW
jack           WIKI_VIEW
# anonymous has no WIKI_VIEW
}}}

Then: 
 - WikiStart will be viewable by all (including anonymous)
 - !PrivatePage will be viewable only by john
 - other pages will be viewable only by john and jack

----
See also: WikiContext