docs/pyutils.security.rst

   1 pyutils.security package
   2 ========================
   3
   4 Right now this package only contains an implementation that allows you to
   5 define and evaluate Access Control Lists (ACLs) easily.  For example::
   6
   7         even = acl.SetBasedACL(
   8             allow_set=set([2, 4, 6, 8, 10]),
   9             deny_set=set([1, 3, 5, 7, 9]),
  10             order_to_check_allow_deny=acl.Order.ALLOW_DENY,
  11             default_answer=False,
  12         )
  13         self.assertTrue(even(2))
  14         self.assertFalse(even(3))
  15         self.assertFalse(even(-4))
  16
  17 ACLs can also be defined based on other criteria, for example::
  18
  19         a_or_b = acl.StringWildcardBasedACL(
  20             allowed_patterns=['a*', 'b*'],
  21             order_to_check_allow_deny=acl.Order.ALLOW_DENY,
  22             default_answer=False,
  23         )
  24         self.assertTrue(a_or_b('aardvark'))
  25         self.assertTrue(a_or_b('baboon'))
  26         self.assertFalse(a_or_b('cheetah'))
  27
  28 Or::
  29
  30         weird = acl.StringREBasedACL(
  31             denied_regexs=[re.compile('^a.*a$'), re.compile('^b.*b$')],
  32             order_to_check_allow_deny=acl.Order.DENY_ALLOW,
  33             default_answer=True,
  34         )
  35         self.assertTrue(weird('aardvark'))
  36         self.assertFalse(weird('anaconda'))
  37         self.assertFalse(weird('blackneb'))
  38         self.assertTrue(weird('crow'))
  39
  40 There are implementations for wildcards, sets, regular expressions,
  41 allow lists, deny lists, sequences of user defined predicates, etc...
  42 You can also just subclass the base :class:`SimpleACL` interface to
  43 define your own ACLs easily.  Its __call__ method simply needs to
  44 decide whether an item is allowed or denied.
  45
  46 Once a :class:`SimpleACL` is defined, it can be used in :class:`CompoundACLs`::
  47
  48         a_b_c = acl.StringWildcardBasedACL(
  49             allowed_patterns=['a*', 'b*', 'c*'],
  50             order_to_check_allow_deny=acl.Order.ALLOW_DENY,
  51             default_answer=False,
  52         )
  53         c_d_e = acl.StringWildcardBasedACL(
  54             allowed_patterns=['c*', 'd*', 'e*'],
  55             order_to_check_allow_deny=acl.Order.ALLOW_DENY,
  56             default_answer=False,
  57         )
  58         conjunction = acl.AllCompoundACL(
  59             subacls=[a_b_c, c_d_e],
  60             order_to_check_allow_deny=acl.Order.ALLOW_DENY,
  61             default_answer=False,
  62         )
  63         self.assertFalse(conjunction('aardvark'))
  64         self.assertTrue(conjunction('caribou'))
  65         self.assertTrue(conjunction('condor'))
  66         self.assertFalse(conjunction('eagle'))
  67         self.assertFalse(conjunction('newt'))
  68
  69 a :class:`CompoundACL` can also be used inside another :class:`CompoundACL`
  70 so this should be a flexible framework when defining complex access control
  71 requirements:
  72
  73 There are two flavors of :class:`CompoundACLs`:
  74 :class:`AllCompoundACL` and :class:`AnyCompoundAcl`.  The former only
  75 admits an item if all of its sub-acls admit it and the latter will
  76 admit an item if any of its sub-acls admit it.:
  77
  78
  79 Submodules
  80 ----------
  81
  82 pyutils.security.acl module
  83 ---------------------------
  84
  85 .. automodule:: pyutils.security.acl
  86    :members:
  87    :undoc-members:
  88    :show-inheritance:
  89
  90 Module contents
  91 ---------------
  92
  93 .. automodule:: pyutils.security
  94    :members:
  95    :undoc-members:
  96    :show-inheritance: