Package flumotion :: Package component :: Package bouncers :: Module plug
[hide private]

Module plug

source code

Base class and implementation for bouncer components, who perform authentication services for other components.

Bouncers receive keycards, defined in flumotion.common.keycards, and then authenticate them.

Passing a keycard over a PB connection will copy all of the keycard's attributes to a remote side, so that bouncer authentication can be coupled with PB. Bouncer implementations have to make sure that they never store sensitive data as an attribute on a keycard.

Keycards have three states: REQUESTING, AUTHENTICATED, and REFUSED. When a keycard is first passed to a bouncer, it has the state REQUESTING. Bouncers should never read the 'state' attribute on a keycard for any authentication-related purpose, since it comes from the remote side. Typically, a bouncer will only set the 'state' attribute to AUTHENTICATED or REFUSED once it has the information to make such a decision.

Authentication of keycards is performed in the authenticate() method, which takes a keycard as an argument. The Bouncer base class' implementation of this method will perform some common checks (e.g., is the bouncer enabled, is the keycard of the correct type), and then dispatch to the do_authenticate method, which is expected to be overridden by subclasses.

Implementations of do_authenticate should eventually return a keycard with the state AUTHENTICATED or REFUSED. It is acceptable for this method to return either a keycard or a deferred that will eventually return a keycard.

FIXME: Currently, a return value of 'None' is treated as rejecting the keycard. This is unintuitive.

Challenge-response authentication may be implemented in do_authenticate(), by returning a keycard still in the state REQUESTING but with extra attributes annotating the keycard. The remote side would then be expected to set a response on the card, resubmit, at which point authentication could be performed. The exact protocol for this depends on the particular keycard class and set of bouncers that can authenticate that keycard class.

It is expected that a bouncer implementation keeps references on the currently active set of authenticated keycards. These keycards can then be revoked at any time by the bouncer, which will be effected through an 'expireKeycard' call. When the code that requested the keycard detects that the keycard is no longer necessary, it should notify the bouncer via calling 'removeKeycardId'.

The above process is leak-prone, however; if for whatever reason, the remote side is unable to remove the keycard, the keycard will never be removed from the bouncer's state. For that reason there is a more robust method: if the keycard has a 'ttl' attribute, then it will be expired automatically after 'keycard.ttl' seconds have passed. The remote side is then responsible for periodically telling the bouncer which keycards are still valid via the 'keepAlive' call, which resets the TTL on the given set of keycards.

Note that with automatic expiry via the TTL attribute, it is still preferred, albeit not strictly necessary, that callers of authenticate() call removeKeycardId when the keycard is no longer used.

Version: $Rev: 6982 $

Classes [hide private]
I am the base class for all bouncer plugs.
A very trivial bouncer implementation.
A base class for Challenge-Response bouncers