[Zope3-checkins] SVN: Zope3/trunk/src/zope/ Updated documtation
file to follow guidelines.
Stephan Richter
srichter at cosmos.phy.tufts.edu
Thu Feb 17 17:29:58 EST 2005
Log message for revision 29197:
Updated documtation file to follow guidelines.
Changed:
U Zope3/trunk/src/zope/app/authentication/idpicker.txt
U Zope3/trunk/src/zope/bforest/bforest.txt
A Zope3/trunk/src/zope/security/README.txt
D Zope3/trunk/src/zope/security/readme.txt
U Zope3/trunk/src/zope/security/untrustedinterpreter.txt
-=-
Modified: Zope3/trunk/src/zope/app/authentication/idpicker.txt
===================================================================
--- Zope3/trunk/src/zope/app/authentication/idpicker.txt 2005-02-17 21:22:58 UTC (rev 29196)
+++ Zope3/trunk/src/zope/app/authentication/idpicker.txt 2005-02-17 22:29:58 UTC (rev 29197)
@@ -1,7 +1,7 @@
-Id Pickler
+Id Picker
----------
-The Id pickler is a variation on the name chooser that picks numeric
+The Id picker is a variation on the name chooser that picks numeric
ids when no name is given.
>>> from zope.app.authentication.idpicker import IdPicker
Modified: Zope3/trunk/src/zope/bforest/bforest.txt
===================================================================
--- Zope3/trunk/src/zope/bforest/bforest.txt 2005-02-17 21:22:58 UTC (rev 29196)
+++ Zope3/trunk/src/zope/bforest/bforest.txt 2005-02-17 22:29:58 UTC (rev 29197)
@@ -1,4 +1,8 @@
-bforests are dictionary-like objects that use multiple BTrees for a backend and
+===========
+BForest API
+===========
+
+BForests are dictionary-like objects that use multiple BTrees for a backend and
support rotation of the composite trees. This supports various implementations
of timed member expirations, enabling caches and semi-persistent storage. A
useful and simple subclass would be to promote a key-value pair to the
Copied: Zope3/trunk/src/zope/security/README.txt (from rev 29171, Zope3/trunk/src/zope/security/readme.txt)
===================================================================
--- Zope3/trunk/src/zope/security/readme.txt 2005-02-16 21:20:50 UTC (rev 29171)
+++ Zope3/trunk/src/zope/security/README.txt 2005-02-17 22:29:58 UTC (rev 29197)
@@ -0,0 +1,340 @@
+==============
+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 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>
+
Deleted: Zope3/trunk/src/zope/security/readme.txt
===================================================================
--- Zope3/trunk/src/zope/security/readme.txt 2005-02-17 21:22:58 UTC (rev 29196)
+++ Zope3/trunk/src/zope/security/readme.txt 2005-02-17 22:29:58 UTC (rev 29197)
@@ -1,324 +0,0 @@
-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 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>
-
Modified: Zope3/trunk/src/zope/security/untrustedinterpreter.txt
===================================================================
--- Zope3/trunk/src/zope/security/untrustedinterpreter.txt 2005-02-17 21:22:58 UTC (rev 29196)
+++ Zope3/trunk/src/zope/security/untrustedinterpreter.txt 2005-02-17 22:29:58 UTC (rev 29197)
@@ -1,5 +1,6 @@
+======================
Untrusted interpreters
-**********************
+======================
Untrusted programs are executed by untrusted interpreters. Untrusted
interpreters make use of security proxies to prevent un-mediated
@@ -100,7 +101,7 @@
unless the results are basic objects.
Security proxies
-****************
+----------------
Security proxies are objects that wrap and mediate access to objects.
@@ -165,7 +166,7 @@
unless the result is a basic value.
Basic objects
-*************
+-------------
Basic objects are safe immutable objects that contain only immutable
subobjects. Examples of basic objects include:
@@ -198,7 +199,7 @@
is mediated by the security functions.
Rationale for mutable safe objects
-*********************************
+----------------------------------
Some safe objects are not basic. For these objects, we proxy the
objects if they originate from outside of the environment. We do this
More information about the Zope3-Checkins
mailing list