3 ### Operations and policy switch
5 ### (c) 2013 Mark Wooding
8 ###----- Licensing notice ---------------------------------------------------
10 ### This file is part of Chopwood: a password-changing service.
12 ### Chopwood is free software; you can redistribute it and/or modify
13 ### it under the terms of the GNU Affero General Public License as
14 ### published by the Free Software Foundation; either version 3 of the
15 ### License, or (at your option) any later version.
17 ### Chopwood is distributed in the hope that it will be useful,
18 ### but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ### GNU Affero General Public License for more details.
22 ### You should have received a copy of the GNU Affero General Public
23 ### License along with Chopwood; if not, see
24 ### <http://www.gnu.org/licenses/>.
28 import config
as CONF
; CFG
= CONF
.CFG
31 ### The objective here is to be able to insert a policy layer between the UI,
32 ### which is where the user makes requests to change a bunch of accounts, and
33 ### the backends, which make requested changes without thinking too much
34 ### about whether they're a good idea.
36 ### Here, we convert between (nearly) user-level /requests/, which involve
37 ### doing things to multiple service/user pairs, and /operations/, which
38 ### represent a single change to be made to a particular service. (This is
39 ### slightly nontrivial in the case of reset requests, since the intended
40 ### semantics may be that the services are all assigned the /same/ random
43 ###--------------------------------------------------------------------------
46 OPS
= ['set', 'reset', 'clear']
47 ## A list of the available operations.
49 class polswitch (U
.struct
):
50 """A small structure holding a value for each operation."""
53 ###--------------------------------------------------------------------------
54 ### Operation protocol.
56 ## An operation deals with a single service/user pair. The protocol works
57 ## like this. The constructor is essentially passive, storing information
58 ## about the operation but not actually performing it. The `perform' method
59 ## attempts to perform the operation, and stores information about the
60 ## outcome in attributes:
62 ## error Either `None' or an `ExpectedError' instance indicating what
65 ## result Either `None' or a string providing additional information
66 ## about the successful completion of the operation.
68 ## svc The service object on which the operation was attempted.
70 ## user The user name on which the operation was attempted.
72 class BaseOperation (object):
74 Base class for individual operations.
76 This is where the basic operation protocol is implemented. Subclasses
77 should store any additional attributes necessary during initialization, and
78 implement a method `_perform' which takes no parameters, performs the
79 operation, and returns any necessary result.
82 def __init__(me
, svc
, user
, *args
, **kw
):
83 """Initialize the operation, storing the SVC and USER in attributes."""
84 super(BaseOperation
, me
).__init__(*args
, **kw
)
89 """Perform the operation, and return whether it was successful."""
91 ## Set up the `result' and `error' slots here, rather than earlier, to
92 ## catch callers referencing them too early.
93 me
.result
= me
.error
= None
95 ## Perform the operation, and stash the result.
98 try: me
.result
= me
._perform()
99 except (IOError, OSError), e
: raise U
.ExpectedError
, (500, str(e
))
100 except U
.ExpectedError
, e
:
106 CONF
.export('BaseOperation')
108 class SetOperation (BaseOperation
):
109 """Operation to set a given password on an account."""
110 def __init__(me
, svc
, user
, passwd
, *args
, **kw
):
111 super(SetOperation
, me
).__init__(svc
, user
, *args
, **kw
)
114 me
.svc
.setpasswd(me
.user
, me
.passwd
)
115 CONF
.export('SetOperation')
117 class ClearOperation (BaseOperation
):
118 """Operation to clear a password from an account, preventing logins."""
120 me
.svc
.clearpasswd(me
.user
)
121 CONF
.export('ClearOperation')
123 class FailOperation (BaseOperation
):
124 """A fake operation which just raises an exception."""
125 def __init__(me
, svc
, user
, exc
):
133 CONF
.export('FailOperation')
135 ###--------------------------------------------------------------------------
138 CONF
.DEFAULTS
.update(
140 ## A boolean switch for each operation to tell us whether it's allowed. By
141 ## default, they all are.
142 ALLOWOP
= polswitch(**dict((i
, True) for i
in OPS
)))
144 ## A request object represents a single user-level operation targetted at
145 ## multiple services. The user might be known under a different alias by
146 ## each service, so requests operate on service/user pairs, bundled in an
149 ## Request methods are as follows.
151 ## check() Verify that the request complies with policy. Note that
152 ## checking that any particular user has authority over the
153 ## necessary accounts has already been done. One might want to
154 ## check that the passwords are sufficiently long and
155 ## complicated (though that rapidly becomes problematic, and I
156 ## don't really recommend it) or that particular services are or
157 ## aren't processed at the same time.
159 ## perform() Actually perform the request. A list of completed operation
160 ## objects is left in the `ops' attribute.
162 ## Performing the operation may leave additional information in attributes.
163 ## The `INFO' class attribute contains a dictionary mapping attribute names
164 ## to human-readable descriptions of this additional information.
166 ## Note that the request object has a fairly free hand in choosing how to
167 ## implement the request in terms of operations. In particular, it might
168 ## process additional services. Callers must not assume that they can
169 ## predict what the resulting operations list will look like.
171 class acct (U
.struct
):
172 """A simple pairing of a service SVC and USER name."""
173 __slots__
= ['svc', 'user']
175 class BaseRequest (object):
177 Base class for requests, provides basic protocol.
179 It provides an empty `INFO' map; a simple `check' method which checks the
180 operation name (in the class attribute `OP') against the configured policy
181 `CFG'ALLOWOP'; and the obvious `perform' method which assumes that the
182 `ops' list has already been constructed.
186 ## A dictionary describing the additional information returned by the
187 ## request: it maps attribute names to human-readable descriptions.
191 Check the request to make sure we actually want to proceed.
193 if not getattr(CFG
.ALLOWOP
, me
.OP
):
194 raise U
.ExpectedError
, \
195 (401, "Operation `%s' forbidden by policy" % me
.OP
)
197 def makeop(me
, optype
, svc
, user
, **kw
):
199 Hook for making operations. A policy class can substitute a
200 `FailOperation' to partially disallow a request.
202 return optype(svc
, user
, **kw
)
206 Perform the queued-up operations.
208 for op
in me
.ops
: op
.perform()
211 CONF
.export('BaseRequest', ExpectedError
= U
.ExpectedError
)
213 class SetRequest (BaseRequest
):
215 Request to set the password for the given ACCTS to NEW.
217 The new password is kept in the object's `new' attribute for easy
218 inspection. The `check' method ensures that the password is not empty, but
219 imposes no other policy restrictions.
224 def __init__(me
, accts
, new
):
226 me
.ops
= [me
.makeop(SetOperation
, acct
.svc
, acct
.user
, passwd
= new
)
231 raise U
.ExpectedError
, (400, "Empty password not permitted")
232 super(SetRequest
, me
).check()
234 CONF
.export('SetRequest')
236 class ResetRequest (BaseRequest
):
238 Request to set the password for the given ACCTS to something new but
239 nonspeific. The new password is generated based on a number of class
240 attributes which subclasses can usefully override.
242 ENCODING Encoding to apply to random data.
244 PWBYTES Number of random bytes to collect.
246 Alternatively, subclasses can override the `pwgen' method.
251 ## Password generation parameters.
255 ## Additional information.
256 INFO
= dict(new
= 'New password')
258 def __init__(me
, accts
):
260 me
.ops
= [me
.makeop(SetOperation
, acct
.svc
, acct
.user
, passwd
= me
.new
)
264 return U
.ENCODINGS
[me
.ENCODING
].encode(OS
.urandom(me
.PWBYTES
)) \
267 CONF
.export('ResetRequest')
269 class ClearRequest (BaseRequest
):
271 Request to clear the password for the given ACCTS.
276 def __init__(me
, accts
):
277 me
.ops
= [me
.makeop(ClearOperation
, acct
.svc
, acct
.user
)
280 CONF
.export('ClearRequest')
282 ###--------------------------------------------------------------------------
283 ### Master policy switch.
285 CONF
.DEFAULTS
.update(
287 ## Map a request type `set', `reset', or `clear', to the appropriate
289 RQCLASS
= polswitch(**dict((i
, None) for i
in OPS
)),
291 ## Alternatively, set this to a mixin class to apply common policy to all
292 ## the kinds of requests.
296 def set_policy_classes():
297 for op
, base
in [('set', SetRequest
),
298 ('reset', ResetRequest
),
299 ('clear', ClearRequest
)]:
300 if getattr(CFG
.RQCLASS
, op
): continue
302 cls
= type('Custom%sPolicy' % op
.title(), (base
, CFG
.RQMIXIN
), {})
305 setattr(CFG
.RQCLASS
, op
, cls
)
309 class outcome (U
.struct
):
310 __slots__
= ['rc', 'nwin', 'nlose']
316 class info (U
.struct
):
317 __slots__
= ['desc', 'value']
319 def operate(op
, accts
, *args
, **kw
):
321 Perform a request through the policy switch.
323 The operation may be one of `set', `reset' or `clear'. An instance of the
324 appropriate request class is constructed, and additional arguments are
325 passed directly to the request class constructor; the request is checked
326 for policy compliance; and then performed.
328 The return values are:
330 * an `outcome' object holding the general outcome, and a count of the
331 winning and losing operations;
333 * a list of `info' objects holding additional information from the
336 * the request object itself; and
338 * a list of the individual operation objects.
340 rq
= getattr(CFG
.RQCLASS
, op
)(accts
, *args
, **kw
)
345 if o
.error
: nlose
+= 1
348 if nlose
: rc
= outcome
.PARTIAL
349 else: rc
= outcome
.OK
351 if nlose
: rc
= outcome
.FAIL
352 else: rc
= outcome
.NOTHING
353 ii
= [info(v
, getattr(rq
, k
)) for k
, v
in rq
.INFO
.iteritems()]
354 return outcome(rc
, nwin
, nlose
), ii
, rq
, ops
356 ###----- That's all, folks --------------------------------------------------