Welcome to the tutorial. This section is currently a work in progress. Please refer to cpol/cpol_demo or cpol/cpol_demo_linux in the source code distribution for examples of how to invoke C▪ POL's application programming interface (API), and look at cpol/src/location to see how to define the C▪ POL parameter objects.

Introduction to C▪ POL

C▪ POL is a policy evaluation engine determines the level of access that should be granted to a principal in the system given a set of policies and the system state. C▪ POL operates as a single C++ class that takes four type parameters via the C++ templates. The four objects are as follows:

• Access Token: The access token describes that an entity in the system can hold. For a file system an access token may contain read, write, and execute flags.

• Condition: A condition will evaluate to true or false given the current state of the system to determine if an entity should be given the access token associated with a policy.

• State: The state object contains information about the state of the system that may affect the condition. For location-aware privacy enforcement, the state contains the current time and the owner's location (content of the data).

• Cache Condition: The cache condition is like a time-to-live value. It is much smaller than a normal condition and should evaluate a lot faster. For the location-aware privacy implementation, the cache condition contains the time-to-live of a cached access token and the minimum change in the owner's location that will invalidate the access token.

After you have defined each of these objects, the next step is to create an application and instantiate the cpol class. As seen in cpol_demo, you can add new entities to cpol by calling cpol::AddUser(char* name), which returns a unique handle for the newly created entity.

It is worth mentioning here that the entity does not necessarily have to be a user, it could be an object as well. In C▪ POL there currently is no distinction between entities that can own resources and entities that can request resources; all entities can own and request resources.

Once cpol has been populated with entities, you can add access rules by calling cpol::AddRule(ID requester, ID owner, ID ruleTarget, ACCESS, CONDITION). An access rule gives the target entity a specific access token to the owner's resources while the condition is true. The first parameter is the entity requesting to add the rule. If this parameter is the same as the owner, then cpol accepts the rule addition. Otherwise, cpol checks to see if the requester has sufficient privileges to add the rule on the owner's behalf.

Finally, you can begin making access requests now that there are rules and entities in the system. To get an entity's access token for a given owner's resource, call the cpol::AddRule(STATE, ID requester, ID owner, ACCESS& returnValue) function. The first parameter is the current state of the system mentioned earlier. This contains the current time and the owner's location for the location-aware privacy implementation. Next are the unique identities of the entity requesting access and the owner. After cpol finishes evaluating each of the owner's rules that applies to the requester to see if the condition is true, it will return an access token indicating the appropriate rights that the requester has to the owner's resources. The application can now use this token to properly enforce the C▪ POL policies.