Metadata-Version: 1.1
Name: secobj
Version: 0.2a
Summary: ACL security for functions and classes
Home-page: https://github.com/cramren/secobj
Author: Marc Göldner
Author-email: info@cramren.de
License: GPL
Description: ============
        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 configurability 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 is 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 referencing a named access control list. The format of the string is the 
              unique name of the section in the configuration file without the prefix "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. The default owner is the user SYSTEM.
            - 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.
        
        
Keywords: acl authorization security access
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
