policy-engine/docs/ape.md

Access policy engine

General overview

Purpose

Access policy engine (APE) is aimed at checking if a request can be performed over a resource by looking up the set chains of rules.

Terms

Term	Description	Structure overview
Request	The action that is being performed on the Resource.	Operation - GetObject,PutObject etc.; Properties - actor's public key, actor's attributes; Resource.
Resource	The object that the request is being performed on. Check also resource.md.	Name - strictly formatted string value; Properties.
Chain	A chain of Rule-s defined for a specific target. Chains are strictly distinguished by Name-s , i.e. chains with name ingress are not intersected with chains with name s3. Chains are stored in serialized format.	Base64-encoded ID; List of Rule-s; MatchType - defines rule status selection priority.
Rule	Rule defines which status is returned if Request matches all conditions.	Status: Allow, AccessDenied, QuotaLimitReached, NoRuleFound; Actions - operation defined by a schema (GetObject, PutContainer etc.); Resources; Any - if true then Reqeust matches Rule if any Condition is true; Conditions.
Name	Name of a chain (do not confuse with chain ID). Name defines a layer of Chain's usage, so chains are distinguished by Name-s. Basically, Name refers to a protocol.	String value (ingress, s3, iam).
Target	A scope of request. Target can be either simple (only namespace; only container; only user; only groups) or compound (namespace + container).	Namespace; Container; User; Groups.
Engine	Engine checks a request in a scope defined by Target. First, it is trying to match a request with rules defined in LocalOverrideStorage and, then, in MorphRuleChainStorage.	LocalOverrideStorage - chains stored in the local override storage have the highest priority MorphRuleChainStorage - basically, chains stored in Policy contract; ChainRouter - looks up chains and try to match them with Request.

Details

Here some entities are overviewed in more detail.

Resource

Resource's name is strictly formatted, the format is defined by a schema (native, aws etc.). Examples:

# The resource is the particular object with the address within Root namespace
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
# The resource is all objects within the container within Root namespace
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*
# The resource is the particular container within the namespace
native:container/namespace1/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj
# The resource is all containers within the namespace
native:container/namespace1/*

Rule

Rule works out if:

1. a requests's operation matches the rule's Actions;
2. resource name matches the rule's Resources;
3. if all (or at least one if Any=true) conditions in Condition is met. Each condition defines how to retrieve and compare the retrieved value. If Condition's Object is set to Resource then the value is retrieved from the resource's properties (example: container zone attribute). If Object is set to Request, the it's retrieved from the request's properties (example: actor's public key).

Name matching

Resource's name in Rule may contain wildcard '*' that can be considered as a regular expression:

# The resource is all objects within the container within Root namespace
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*

If an incoming request has such a resource name, then names are matched:

# The resource is all objects within the container within Root namespace
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr

If the incoming request has such a resource name that specifies a container's object within namespace, for instance, namespicy, then matching does not work out:

# The resource is all objects within the container within `namespicy` namespace:
native:object/namespicy/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr

Engine

Engine is trying to match the request against the target looking up chain rules, firstly, in LocalOverrideStorage (these rules are also known as local overrides) and then in MorphRuleChainStorage (contract Policy). Both storages iterate chain rules according to the specified priority of the targets: namespace -> container -> user -> groups.

Diagrams

The diagram demonstrates a scenario in Storage node. The request A cannot be performed as APE matched the request and returned Access Denied status. The request B is allowed and the client gets OK status.

The diagram demonstrates a complex scenario with S3, IAM and Storage node.