The nova.openstack.common.policy Module

Common Policy Engine Implementation

Policies can be expressed in one of two forms: A list of lists, or a string written in the new policy language.

In the list-of-lists representation, each check inside the innermost list is combined as with an “and” conjunction–for that check to pass, all the specified checks must pass. These innermost lists are then combined as with an “or” conjunction. This is the original way of expressing policies, but there now exists a new way: the policy language.

In the policy language, each check is specified the same way as in the list-of-lists representation: a simple “a:b” pair that is matched to the correct code to perform that check. However, conjunction operators are available, allowing for more expressiveness in crafting policies.

As an example, take the following rule, expressed in the list-of-lists representation:

[["role:admin"], ["project_id:%(project_id)s", "role:projectadmin"]]

In the policy language, this becomes:

role:admin or (project_id:%(project_id)s and role:projectadmin)

The policy language also has the “not” operator, allowing a richer policy rule:

project_id:%(project_id)s and not role:dunce

Finally, two special policy checks should be mentioned; the policy check “@” will always accept an access, and the policy check ”!” will always reject an access. (Note that if a rule is either the empty list (“[]”) or the empty string, this is equivalent to the “@” policy check.) Of these, the ”!” policy check is probably the most useful, as it allows particular rules to be explicitly disabled.

class AndCheck(rules)

Bases: nova.openstack.common.policy.BaseCheck

A policy check that requires that a list of other checks all return True. Implements the “and” operator.

add_check(rule)

Allows addition of another rule to the list of rules that will be tested. Returns the AndCheck object for convenience.

class BaseCheck

Bases: object

Abstract base class for Check classes.

class Check(kind, match)

Bases: nova.openstack.common.policy.BaseCheck

A base class to allow for user-defined policy checks.

class FalseCheck

Bases: nova.openstack.common.policy.BaseCheck

A policy check that always returns False (disallow).

class GenericCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class HttpCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class NotCheck(rule)

Bases: nova.openstack.common.policy.BaseCheck

A policy check that inverts the result of another policy check. Implements the “not” operator.

class OrCheck(rules)

Bases: nova.openstack.common.policy.BaseCheck

A policy check that requires that at least one of a list of other checks returns True. Implements the “or” operator.

add_check(rule)

Allows addition of another rule to the list of rules that will be tested. Returns the OrCheck object for convenience.

class ParseState

Bases: object

Implement the core of parsing the policy language. Uses a greedy reduction algorithm to reduce a sequence of tokens into a single terminal, the value of which will be the root of the Check tree.

Note: error reporting is rather lacking. The best we can get with this parser formulation is an overall “parse failed” error. Fortunately, the policy language is simple enough that this shouldn’t be that big a problem.

reduce()

Perform a greedy reduction of the token stream. If a reducer method matches, it will be executed, then the reduce() method will be called recursively to search for any more possible reductions.

reducers = [(['check', 'or', 'check'], '_make_or_expr'), (['or_expr', 'or', 'check'], '_extend_or_expr'), (['not', 'check'], '_make_not_expr'), (['check', 'and', 'check'], '_make_and_expr'), (['and_expr', 'and', 'check'], '_extend_and_expr'), (['(', 'or_expr', ')'], '_wrap_check'), (['(', 'and_expr', ')'], '_wrap_check'), (['(', 'check', ')'], '_wrap_check')]

result

Obtain the final result of the parse. Raises ValueError if the parse failed to reduce to a single result.

shift(tok, value)

Adds one more token to the state. Calls reduce().

class ParseStateMeta

Bases: type

Metaclass for the ParseState class. Facilitates identifying reduction methods.

class RoleCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class RuleCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class Rules(rules=None, default_rule=None)

Bases: dict

A store for rules. Handles the default_rule setting directly.

classmethod load_json(data, default_rule=None)

Allow loading of JSON rule data.

class TrueCheck

Bases: nova.openstack.common.policy.BaseCheck

A policy check that always returns True (allow).

check(rule, target, creds, exc=None, *args, **kwargs)

Checks authorization of a rule against the target and credentials.

Parameters:

• rule – The rule to evaluate.
• target – As much information about the object being operated on as possible, as a dictionary.
• creds – As much information about the user performing the action as possible, as a dictionary.
• exc – Class of the exception to raise if the check fails. Any remaining arguments passed to check() (both positional and keyword arguments) will be passed to the exception class. If exc is not provided, returns False.

Returns:

Returns False if the policy does not allow the action and exc is not provided; otherwise, returns a value that evaluates to True. Note: for rules using the “case” expression, this True value will be the specified string from the expression.

parse_rule(rule)

Parses a policy rule into a tree of Check objects.

reducer(*tokens)

Decorator for reduction methods. Arguments are a sequence of tokens, in order, which should trigger running this reduction method.

register(name, func=None)

Register a function or Check class as a policy check.

Parameters:

• name – Gives the name of the check type, e.g., ‘rule’, ‘role’, etc. If name is None, a default check type will be registered.
• func – If given, provides the function or class to register. If not given, returns a function taking one argument to specify the function or class to register, allowing use as a decorator.

reset()

Clear the rules used for policy checks.

set_rules(rules)

Set the rules in use for policy checks.