python-zope.security 3.8.3-2ubuntu1 / usr / share / pyshared / zope / security / README.txt

==============
Zope3 Security
==============

Introduction
------------

The Security framework provides a generic mechanism to implement security
policies on Python objects.  This introduction provides a tutorial of the
framework explaining concepts, design, and going through sample usage from the
perspective of a Python programmer using the framework outside of Zope.

Definitions
-----------

Principal
~~~~~~~~~

A generalization of a concept of a user.

Permission
~~~~~~~~~~

A kind of access, i.e. permission to READ vs. permission to WRITE.
Fundamentally the whole security framework is organized around checking
permissions on objects.

Purpose
-------

The security framework's primary purpose is to guard and check access to
Python objects.  It does this by providing mechanisms for explicit and
implicit security checks on attribute access for objects.  Attribute names are
mapped onto permission names when checking access and the implementation of
the security check is defined by the security policy, which receives the
object, the permission name, and an interaction.

Interactions are objects that represent the use of the system by one or more
principals.  An interaction contains a list of participations, which
represents the way a single principal participates in the interaction.  An
HTTP request is one example of a participation.

Its important to keep in mind that the policy provided is just a default, and
it can be substituted with one which doesn't care about principals or
interactions at all.

Framework Components
--------------------

Low Level Components
~~~~~~~~~~~~~~~~~~~~

These components provide the infrastructure for guarding attribute access and
providing hooks into the higher level security framework.

Checkers
~~~~~~~~

A checker is associated with an object kind, and provides the hooks that map
attribute checks onto permissions deferring to the security manager (which in
turn defers to the policy) to perform the check.

Additionally, checkers provide for creating proxies of objects associated with
the checker.

There are several implementation variants of checkers, such as checkers that
grant access based on attribute names.

Proxies
~~~~~~~

Wrappers around Python objects that implicitly guard access to their wrapped
contents by delegating to their associated checker.  Proxies are also viral in
nature, in that values returned by proxies are also proxied.

High Level Components
---------------------

Security Management
~~~~~~~~~~~~~~~~~~~

Provides accessors for setting up interactions and the global security policy.

Interaction
~~~~~~~~~~~

Stores transient information on the list of participations.

Participation
~~~~~~~~~~~~~

Stores information about a principal participating in the interaction.

Security Policy
~~~~~~~~~~~~~~~

Provides a single method that accepts the object, the permission, and the
interaction of the access being checked and is used to implement the
application logic for the security framework.

Narrative (agent sandbox)
-------------------------

As an example we take a look at constructing a multi-agent distributed system,
and then adding a security layer using the Zope security model onto it.

Scenario
~~~~~~~~

Our agent simulation consists of autonomous agents that live in various agent
homes/sandboxes and perform actions that access services available at their
current home.  Agents carry around authentication tokens which signify their
level of access within any given home.  Additionally agents attempt to migrate
from home to home randomly.

The agent simulation was constructed separately from any security aspects.
Now we want to define and integrate a security model into the simulation.  The
full code for the simulation and the security model is available separately;
we present only relevant code snippets here for illustration as we go through
the implementation process.

For the agent simulation we want to add a security model such that we group
agents into two authentication groups, "norse legends", including the
principals thor, odin, and loki, and "greek men", including prometheus,
archimedes, and thucydides.

We associate permissions with access to services and homes.  We differentiate
the homes such that certain authentication groups only have access to services
or the home itself based on the local settings of the home in which they
reside.

We define the homes/sandboxes

  - origin - all agents start here, and have access to all
    services here.

  - valhalla - only agents in the authentication group 'norse
    legend' can reside here.

  - jail - all agents can come here, but only 'norse legend's
    can leave or access services.


Process
~~~~~~~

Loosely we define a process for implementing this security model

  - mapping permissions onto actions

  - mapping authentication tokens onto permissions

  - implementing checkers and security policies that use our
    authentication tokens and permissions.

  - binding checkers to our simulation classes

  - inserting the hooks into the original simulation code to add
    proxy wrappers to automatically check security.

  - inserting hooks into the original simulation to register the
    agents as the active principal in an interaction.


Defining a Permission Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~

We define the following permissions::

   NotAllowed = 'Not Allowed'
   Public = Checker.CheckerPublic
   TransportAgent = 'Transport Agent'
   AccessServices = 'Access Services'
   AccessAgents = 'Access Agents'
   AccessTimeService = 'Access Time Services'
   AccessAgentService = 'Access Agent Service'
   AccessHomeService = 'Access Home Service'

and create a dictionary database mapping homes to authentication groups which
are linked to associated permissions.


Defining and Binding Checkers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Checkers are the foundational unit for the security framework.  They define
what attributes can be accessed or set on a given instance.  They can be used
implicitly via Proxy objects, to guard all attribute access automatically or
explicitly to check a given access for an operation.

Checker construction expects two functions or dictionaries, one is used to map
attribute names to permissions for attribute access and another to do the same
for setting attributes.

We use the following checker factory function::

   def PermissionMapChecker(permissions_map={},
                            setattr_permission_func=NoSetAttr):
       res = {}
       for k,v in permissions_map.items():
           for iv in v:
               res[iv]=k
       return checker.Checker(res.get, setattr_permission_func)

   time_service_checker = PermissionMapChecker(
                                  # permission : [methods]
                                  {'AccessTimeService':['getTime']}
                                  )

with the NoSetAttr function defined as a lambda which always return the
permission `NotAllowed`.

To bind the checkers to the simulation classes we register our checkers with
the security model's global checker registry::

   import sandbox_simulation
   from zope.security.checker import defineChecker
   defineChecker(sandbox_simulation.TimeService, time_service_checker)


Defining a Security Policy
~~~~~~~~~~~~~~~~~~~~~~~~~~

We implement our security policy such that it checks the current agent's
authentication token against the given permission in the home of the object
being accessed::

  class SimulationSecurityPolicy:

      implements(ISecurityPolicy)

      createInteraction = staticmethod(simpleinteraction.createInteraction)

      def checkPermission(self, permission, object, interaction):

          home = object.getHome()
          db = getattr(SimulationSecurityDatabase, home.getId(), None)

          if db is None:
              return False

          allowed = db.get('any', ())
          if permission in allowed or ALL in allowed:
              return True

          if interaction is None:
              return False
          if not interaction.participations:
              return False
          for participation in interaction.participations:
              token = participation.principal.getAuthenticationToken()
              allowed = db.get(token, ())
              if permission not in allowed:
                  return False

          return True

There are no specific requirements for the interaction class, so we can just
use `zope.security.simpleinteraction.Interaction`.

Since an interaction can have more than one principal, we check that *all* of
them are given the necessary permission.  This is not really necessary since
we only create interactions with a single active principal.

There is some additional code present to allow for shortcuts in defining the
permission database when defining permissions for all auth groups and all
permissions.


Integration
~~~~~~~~~~~

At this point we have implemented our security model, and we need to integrate
it with our simulation model.  We do so in three separate steps.

First we make it such that agents only access homes that are wrapped in a
security proxy.  By doing this all access to homes and services (proxies have
proxied return values for their methods) is implicitly guarded by our security
policy.

The second step is that we want to associate the active agent with the
security context so the security policy will know which agent's authentication
token to validate against.

The third step is to set our security policy as the default policy for the
Zope security framework.  It is possible to create custom security policies at
a finer grained than global, but such is left as an exercise for the reader.


Interaction Access
~~~~~~~~~~~~~~~~~~

The *default* implementation of the interaction management interfaces defines
interactions on a per thread basis with a function for an accessor.  This
model is not appropriate for all systems, as it restricts one to a single
active interaction per thread at any given moment.  Reimplementing the
interaction access methods though is easily doable and is noted here for
completeness.


Perspectives
~~~~~~~~~~~~

It's important to keep in mind that there is a lot more that is possible using
the security framework than what's been presented here.  All of the
interactions are interface based, such that if you need to re-implement the
semantics to suite your application a new implementation of the interface will
be sufficient.  Additional possibilities range from restricted interpreters
and dynamic loading of untrusted code to non Zope web application security
systems.  Insert imagination here ;-).


Zope Perspective
~~~~~~~~~~~~~~~~

A Zope3 programmer will never commonly need to interact with the low level
security framework.  Zope3 defines a second security package over top the low
level framework and authentication sources and checkers are handled via zcml
registration.  Still those developing Zope3 will hopefully find this useful as
an introduction into the underpinnings of the security framework.


Code
~~~~

The complete code for this example is available.

- sandbox.py - the agent framework

- sandbox_security.py - the security implementation and binding to the agent
  framework.


Authors
~~~~~~~

- Kapil Thangavelu <hazmat at objectrealms.net>
- Guido Wesdorp <guido at infrae.com>
- Marius Gedminas <marius at pov.lt>