============
Introduction
============

The package "secobj" provides access control lists for functions, classes and methods. They are
declared and enforced by a decorator named "access". The goal of this library is to be simple and
effective in use but at the same time to provide enough configurbility to master complex scenarios.

As for the time being "secobj" only provides authorization based on access control lists. At a later
time it can be possible, that the library will be extended with authentication functionality.

The decorator "access" is the pivotal element of this library. It augments the decorated function,
class or method with variables, which have the naming pattern "__acl.*__". At runtime these
variables are evaluated by the decorating function and access is granted or denied. The signature of
the decorator ist as follows::

    def access(*rules, **kwargs)

The decorator can either be called with arguments or without. The possible arguments are:

    * *rules*: This is either a sequence of tuples defining the access control rules. Each tuple
      consits of two or more items:

        #. The desired action. "ALLOW" or "DENY" are provided.
        #. The effective principal. Either a user, group, list of groups or one of the predefined
           principals: ANONYMOUS, SYSTEM, AUTHENTICATED, OWNER, EVERYONE.
        #. Zero or more permissions, which will be granted or denied. If no permission is defined,
           than the default permission will be used as the permission defined by this rule.

      Or it is a string referncing a named access control list. The format of the string is the 
      unique name of the section in the configuration file with out the leading "rules:" followed 
      by the sign "#" and the name of the option in this section. If there is no such option defined
      in the configuration file, the named access control list will be ignored. This can be used to
      define external configurable hooks in the security system.

      Each access control list will be extended by the policy rules defined in the function
      "initsecurity", by the option "policy_rules" in section "secobj" and the option "policy" in
      the same section, in that order.

    * keyword *inherit*: A boolean flag which controlls if the access control rules defined by the 
      method of the super class or defined by the super class itself will have effect. This argument
      is only relevant on methods and classes and is ignored otherwise.
    * keyword *permission*: This is the permission which must be granted by one of the rules in the
      effective access control list.
      If this argument is not provided on a class, a default permission named like the fully
      qualified name of the class is defined. 
      If not provided on a method, the permission will be that of the class.
      If omitted on a function the "ALL" permission will be in effect, meaning, that any permission
      will do.
    * keyword *owner*: This defines the principal which will own the class and instances or
      function. This argument is ignored by methods. A method is always owned by the defining class
      or by the instance.
    * keyword *callback*: Defines a function which is called to retrieve the resource (class,
      method, function) which will be used to provide the runtime variables defining the access
      control. The function will be called with all arguments passed and must return an appropriate
      resource object.

Before the library can be used the function "initsecurity" must be called. With the optionally
provided configuration file a number of aspects can be controlled. A sensible default is defined by
the library. Logging is either configured by the using application or provided as a configuration
file to the function "initsecurity". If logging is not configured at all, the library will use a
null handler for the generated log messages. The signature of the function is as follows::

    initsecurity(configfile=None, logconfigfile=None, policyrules=None)

The arguments are as follows:

    * *configfile*: This is the name of the main configuration file defining the configurable 
      aspects. The relevant sections used by the library are "secobj" and "rules:<unique name>".
    * *logconfigfile*: Configuration options for the logging facility as described in the python
      library documentation. This parameter can be the same as the configuration file and is the
      name of the corresponding file.
    * *policyrules*: Same as the argument "rules" of the decorator "access". The rules defined here 
      are appended to every access control list.

