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

Author
~~~~~~

Kapil Thangavelu <hazmat at objectrealms.net>

Guido Wesdorp <guido at infrae.com>

Marius Gedminas <marius at pov.lt>
